Расширенные запросы — фильтрация, проекция и постраничный вывод в API

Три интерфейса с первого взгляда

Все три описаны в интерактивном справочнике API (страница /developers), в разделе Search, и требуют аутентификации — см. API Omniscol.

Фильтр where (в стиле Mango / MongoDB)

/api/search/entity и /api/search/query принимают условие where: структурированный фильтр с операторами в стиле MongoDB. Поле сопоставляется либо с прямым значением (неявное равенство), либо с объектом операторов; несколько операторов для одного поля объединяются неявным И. В названиях полей допустима запись через точку, чтобы обратиться к родительскому контексту (например, sites.name).

Несколько примеров:

{ "capacity": { "$gte": 20, "$lte": 50 } }
{ "level": { "$in": ["L1", "L2", "L3"] } }
{ "name": { "$regex": "^lab" } }
{ "city": { "$like": "ivry sur seine" } }
{ "$or": [ { "capacity": { "$gte": 50 } }, { "specialisation": "chemistry" } ] }

Проекция, сортировка и постраничный вывод

В /api/search/query есть ещё четыре параметра, которые делают ответ компактным и упорядоченным — это важно для сводной панели и ещё важнее для ИИ-агента, оплата которого идёт за токены:

• project — список полей, которые нужно оставить (запись через точку допускается). Всё остальное отбрасывается.
• sort — поле и порядок, asc или desc. Псевдополе _count.<поле> сортирует по длине поля-массива.
• limit и offset — разбивают результаты на страницы.

В ответе также есть блок meta: сколько элементов было до фильтрации, сколько прошло фильтр и сколько возвращено.

Полный пример

Найти кабинеты как минимум на 30 мест, оставить только название и вместимость, упорядочить от самого большого к самому маленькому и взять первые 20:

curl -X POST "https://votre-etablissement.omniscol.com/api/search/query" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "call": "os_dashboard_classrooms_get",
        "where": { "capacity": { "$gte": 30 } },
        "project": ["name", "capacity"],
        "sort": { "capacity": "desc" },
        "limit": 20
      }'

call — внутреннее имя конечной точки на чтение, которую нужно выполнить (как оно показано на странице /developers), params содержит параметры, свойственные этой конечной точке, а extract_path при необходимости указывает массив, который нужно отфильтровать внутри результата. Если его не указывать, как здесь, массив определяется автоматически.

Поиск свободного кабинета или преподавателя

Самая распространённая интеграция — снабжение данными интранета, системы бронирования или ETL — сводится к вопросу «кто или что свободно в такой-то момент?». На него напрямую отвечают конечные точки availability: они возвращают по каждой сущности только свободные промежутки времени на запрошенные даты, уже учитывая занятия, отсутствия и обязательные пожелания.

Доступность можно запросить двумя способами:

• По типу сущности — GET /api/schedules/availability/{datesrange}/{entity} (при необходимости /{entityId}) для одного типа сущности — teachers, classrooms, groups, resources…
• С явным фильтром — GET /api/schedules/availability/{datesrange} с параметром filter, где набор сужается тем же $where, что описан выше.

{datesrange} записывается в формате YYYYMMDD, а сегменты, разделённые запятыми, задают разрозненные даты — это удобно для «двух конкретных понедельников»: 20261005,20261012. Каждый возвращённый промежуток содержит day, start, end и time (в минутах): условие «не менее 3 часов» превращается в проверку time >= 180 на вашей стороне.

Преподаватель, свободный в конкретный промежуток времени

«Какие преподаватели свободны в понедельник, 5 октября?» — один вызов по типу сущности:

curl -G "https://votre-etablissement.omniscol.com/api/schedules/availability/20261005/teachers" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode "with_entities=true"

Свободные промежутки возвращаются сгруппированными по типу, затем по преподавателю — например, { "availability": { "teachers": { "t.dupont": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } } — и ваш инструмент выбирает тот, который покрывает нужный промежуток.

Кабинеты определённой вместимости, свободные в два понедельника

Объедините фильтр по сущности и доступность в одном вызове, используя полезное подмножество синтаксиса — только $where по вместимости:

curl -G "https://votre-etablissement.omniscol.com/api/schedules/availability/20261005,20261012" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode 'filter={"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}' \
  --data-urlencode "with_entities=true"

Omniscol возвращает свободные промежутки в оба понедельника для каждого кабинета как минимум на 30 мест. Затем ваш ETL оставляет кабинеты, у которых есть окно в 3 часа (time >= 180) в каждую из дат — объединение результатов по нескольким дням остаётся на вашей стороне, поэтому правило остаётся явным и проверяемым.

В filter для каждого типа сущности можно указать простой список идентификаторов ({"classrooms":["A101","B204"]}), подстановочный символ ({"teachers":"*"}), простое сопоставление по полю ({"teachers":[{"email":"…"}]}) или структурированный $where, показанный здесь.

Как выбрать подходящий интерфейс

• «Где встречается это слово?» → POST /api/search.
• «Какой сущности соответствует это название?» → POST /api/search/entity.
• «Дай кабинеты более чем на 30 мест, отсортированные, первая страница» → POST /api/search/query.
• «Кто или что свободно в этот промежуток времени?» → GET /api/schedules/availability/….

Для ИИ-агента

Эти интерфейсы существуют в значительной мере для ИИ-агентов. Полнотекстовый поиск и определение сущности превращают формулировку пользователя («преподаватель Иван Петров», «класс 7А») в точные идентификаторы; затем оркестратор запросов отвечает на отфильтрованный вопрос одним вызовом и возвращает только запрошенные поля — вместо нескольких вызовов и слишком большого ответа. Когда вы подключаете агента через MCP — подключение ИИ-агента, эти инструменты входят в число тех, которыми он может пользоваться.

Подключение к интранету, ETL или инструменту партнёра

Именно эти интерфейсы на чтение ежедневно используют сторонние инструменты. Распространённые варианты:

• Запрос данных из интранета или сводной панели — ваша страница обращается к конечным точкам на чтение (доступность, конечная точка занятий, сводные панели) с ограниченным токеном API и показывает результат. Со стороны Omniscol ничего устанавливать не нужно.
• Ночной ETL — плановая задача забирает то, что ей нужно (занятия за интервал дат, часы преподавателя, загрузку кабинетов) и загружает это в вашу информационную систему. search/query делает каждую выборку отфильтрованной, спроецированной и разбитой на страницы, чтобы ответ был компактным.
• Передача данных из вашей системы — обратное направление, чтобы Omniscol оставался согласованным с вашим источником достоверных данных: ночная задача может обновлять классы и преподавателей (POST /api/external/classes, POST /api/external/teachers) или загружать справочник собственных дисциплин (POST /api/admin/subjects/custom) из вашей базы.
• Школьная информационная система / ERP — для Aurion, Auriga и подобных подходящий инструмент — специальный коннектор, см. Синхронизация с внешними системами.
• Управление по событиям — чтобы получать уведомление об изменении, а не опрашивать систему в цикле, зарегистрируйте вебхук, см. Настройка API.

Делайте каждую интеграцию ограниченной: токен только для действительно нужных конечных точек, регулярно обновляемый и только на чтение везде, где интеграция только читает данные. См. API Omniscol.