Настройка API: переопределение конечных точек и вебхуки

Где найти

Модуль Администрирование, экран Импорт/Экспорт, раздел Настройка API, кнопка API.

Экран доступен только на аккаунтах Premium и защищён усиленной аутентификацией: перед открытием окна Omniscol повторно запрашивает пароль администратора. Любое действие на этом экране затрагивает технический контракт вашей интеграции, поэтому настройку выполняют совместно с Omniscol.

Общая конфигурация

Здесь вы задаёте HTTP-заголовки (формат ключ1:значение1;ключ2:значение2), которые применяются ко всем вебхукам. Это подходящее место, чтобы передавать токен аутентификации вашему собственному серверу (например, для Authorization: Bearer …, которого ожидает ваш сервер). Для переопределения аутентификация, напротив, указывается в заголовках самой конечной точки (см. ниже).

Переопределение конечной точки

Переопределение заново задаёт конечную точку API Omniscol так, что веб-приложение обращается вместо неё к другому URL. Есть три сценария использования — от самого мощного до самого простого.

Отдавать данные напрямую из вашей информационной системы

Это самый мощный сценарий. Вы перенаправляете конечную точку на чтение на внешний URL — как правило, на ETL, который связан с внутренней информационной системой вашего учебного заведения. Тогда веб-приложение берёт данные напрямую из этой системы, а не из локальной копии, которую хранит Omniscol.

На практике: если URL перенаправления — абсолютный внешний адрес, веб-приложение обращается к нему напрямую, минуя серверы Omniscol, и использует ответ как есть — точно так, как если бы он пришёл от Omniscol. Единственное условие: ваша система должна отвечать в формате, которого Omniscol ожидает для этой конечной точки (та же структура JSON): промежуточного преобразования нет. Для этой конечной точки локальная копия Omniscol больше не запрашивается; отображаются актуальные данные вашей системы.

Пример: каталог дисциплин учебного заведения отдаётся на лету из вашей информационной системы, так что любое изменение на стороне школы сразу видно в Omniscol, без повторного импорта.

Аутентификация в вашей системе указывается здесь в заголовках самой конечной точки (например, Authorization: Bearer …), в строке переопределения. Метод HTTP тоже можно задать для каждой конечной точки.

Подключить конечную точку самого приложения к внешнему источнику актуальных данных — возможность столь же мощная, сколь и требовательная: пользуйтесь ею вместе с вашей ИТ-службой и по согласованию с Omniscol.

Включить в цепочку ваш собственный сервер или прокси

Вызовы можно также пропускать через ваш собственный сервер или прокси — например, чтобы разрешить совместное использование ресурсов между источниками (CORS) или чтобы добавить собственную логику между веб-приложением и Omniscol.

Отключить конечную точку

Чтобы отключить конечную точку, не указывайте для неё никакого URL перенаправления (метод null).

Учтите, как это влияет на интерфейс. Omniscol — одностраничное веб-приложение (SPA), элементы интерфейса которого определяются доступными конечными точками: кнопки, вкладки и меню отображаются, только если существует конечная точка, от которой они зависят. Поэтому отключение конечной точки динамически убирает при следующем отображении зависящие от неё элементы интерфейса, а если вы отключите все конечные точки модуля, из навигации исчезнет весь модуль. Элементы именно убираются, а не просто скрываются, и всё это происходит без какого-либо вмешательства в код: достаточно изменить конфигурацию и перезагрузить приложение.

В таблице для каждой конечной точки указаны: её ключ (внутренний код операции), исходный URL, метод HTTP, новый URL перенаправления и собственные заголовки. Поле поиска помогает найти конечную точку, которую нужно переопределить.

Вебхуки (исходящие вызовы)

Вебхук поручает Omniscol отправить HTTP-запрос на ваш URL после того, как операция выполнена успешно. Так внешняя система получает актуальные сведения в реальном времени — информационная панель, учебная онлайн-среда, система управления кадрами, собственная синхронизация…

Вебхук привязывается двумя способами:

• к конкретной конечной точке (ключ операции);
• к групповому событию, которое сразу охватывает целое семейство операций. Существует три групповых события:
  • изменение расписания — любое изменение, затрагивающее действующее расписание, включая побочные эффекты: сохранение расписания, создание, перенос или удаление занятий, публикация расписания, отсутствия преподавателей или классов, как только затронута какая-либо дата, и структурные удаления (кабинета, дисциплины…) в опубликованном расписании — удаление дисциплины удаляет использовавшие её занятия, а это само по себе изменение. Правки, не выходящие за пределы неопубликованного черновика, это событие не запускают;
  • изменение преподавателя (добавление, обновление или удаление);
  • изменение дисциплины (собственные дисциплины).

Для каждого вебхука вы указываете URL обратного вызова, метод HTTP, флажок «с данными» (прикладывать ли тело исходного запроса?) и собственные заголовки.

Что получает ваш сервер

Вызов отправляется в формате application/json и содержит, помимо ваших заголовков:

• тело исходного запроса, если включена опция «с данными»;
• блок метаданных Omniscol: вызванный URL, код конечной точки, метод, параметры, токен аутентификации пользователя, идентификатор учебного заведения и конфигурацию самого вебхука;
• заголовки для отслеживания: X-OS-original-query, X-OS-original-endpoint, X-OS-auth и X-School.

Для события изменение расписания, если включена опция «с данными», вызов дополнительно содержит перечень изменений по занятиям (добавленные, изменённые, удалённые занятия) — это удобно, если нужно передавать дальше только то, что изменилось.

Поведение

Вебхуки отправляются в фоновом режиме после того, как операция пользователя завершилась: они не замедляют интерфейс и не блокируют его в случае сбоя на вашем сервере. Исходящий вызов, который не удался, записывается в журнал и не прерывает работу в Omniscol. У каждого вызова короткий тайм-аут (несколько секунд): ваш сервер должен быстро подтвердить получение и обработать остальное у себя.

Что нужно знать

• API Omniscol предоставляет часть операций; переопределение или вебхук применяется только к фактически доступным конечным точкам. Список и аутентификацию см. на странице API Omniscol.
• Для интеграции с программным комплексом (ERP, система управления кадрами, учебная онлайн-среда) часто лучше подходит специальная синхронизация — см. страницу Синхронизация с внешними системами. Внутри неё используется тот же механизм вебхуков.
• Чтобы ИИ-агент мог обращаться к вашим данным без разработки, см. страницу MCP — подключение ИИ-агента.