Эффективная работа с API: кеширование, вебхуки и ограничения частоты запросов
PremiumИнтеграция, которая каждую минуту опрашивает Omniscol, чтобы проверить, изменились ли данные, в большинстве случаев получает тот же ответ, что и при предыдущем вызове. Она впустую расходует свою квоту и нагружает сервер, не получая новой информации.
На этой странице описаны механизмы, позволяющие избежать лишних вызовов, а также ограничения частоты запросов, действующие для API.
Не получать неизменившиеся данные
Большинство ответов API на чтение содержат заголовок ETag, который
идентифицирует версию ответа. Сохраняйте этот идентификатор вместе с
полученными данными и передавайте его при следующем вызове в заголовке
If-None-Match:
curl -i -G "https://votre-etablissement.omniscol.com/api/schedules/lessons/20261102-20261108" \
-H "Authorization: Bearer $TOKEN" \
-H 'If-None-Match: W/"os1.…"'
Если данные не изменились, Omniscol отвечает 304 Not Modified без тела
ответа. Тогда вы можете повторно использовать данные, сохранённые в кеше. В
противном случае вы получаете полный ответ 200 OK с новым ETag.
ETag — непрозрачное значение: сохраняйте его и отправляйте обратно без
изменений, вместе с кавычками и префиксом W/, не пытаясь его составлять или
расшифровывать. Он привязан к запросу, который его создал, и к использованному
доступу: не применяйте его для другого URL или с другим токеном.
Заголовок Cache-Control: private, no-cache указывает, что ответ можно
хранить в приватном кеше, но перед повторным использованием его необходимо
повторно проверить в Omniscol. Именно для этого служит If-None-Match.
Некоторые ответы не содержат ETag, в частности когда они зависят от текущей даты и могут меняться без изменения данных учётной записи. Такие ответы нужно получать заново при каждом вызове.
После развёртывания новой версии Omniscol все ETag обновляются, даже если
данные не изменились. Первый вызов тогда получает ответ 200, а последующие
вызовы снова могут получать ответы 304.
Ответ 304 также снижает нагрузку на сервер. В большинстве случаев, когда с
момента последнего вызова данные учётной записи не изменились, Omniscol может
ответить, даже не перечитывая соответствующие данные, и такой 304 не
засчитывается в квоту, связанную с вашим ключом API. 304, полученный после
перечитывания данных, засчитывается как обычный ответ.
Поэтому регулярная повторная проверка остаётся недорогой, пока данные не меняются. Тем не менее на неё распространяется общее ограничение по IP-адресу.
Хранить ответы в кеше
Если несколько пользователей или несколько экранов вашего приложения обращаются к одним и тем же данным, опрашивать Omniscol для каждого из них не нужно.
Храните ответы и их ETag в кеше приложения, находящемся под вашим контролем,
например в Redis, Memcached или таблице базы данных. Тогда ваше приложение
сможет отдавать данные из этого кеша, который сам повторно проверяет их в
Omniscol с помощью If-None-Match через регулярные промежутки времени или
когда вебхук сообщает об изменении.
Ключ кеша должен учитывать полный URL, использованный токен аутентификации и,
если вы их используете, тело запроса GET и заголовки, от которых зависит
ответ, например Accept-Language. Два токена с разными правами могут давать
доступ к разным данным: ответ, полученный с одним из них, никогда не должен
отдаваться пользователю, права которого не позволяют получить эти данные.
Храните также тело каждого ответа вместе с его ETag. Без соответствующих
данных ответ 304 не позволяет восстановить ожидаемый результат.
Этот кеш приложения отличается от общего HTTP-кеша: директива
Cache-Control: private запрещает последнему хранить ответы.
Получать уведомления вместо регулярного опроса
Вместо периодической проверки того, изменились ли данные, вы можете попросить Omniscol уведомлять ваше приложение при возникновении изменения.
Этот механизм основан на вебхуках, которые настраиваются на экране настройки API (см. Настройка API). Вебхук может отслеживать конкретную конечную точку или событие, объединяющее несколько изменений, например изменение расписания.
Сбрасывать кеш при получении вебхука
Самый простой способ — рассматривать вебхук как сигнал сброса кеша.
Когда приходит уведомление, ваше приложение помечает соответствующие данные как устаревшие и повторно проверяет их в Omniscol. Интерпретировать содержимое изменения не нужно: вебхук лишь сообщает, что требуется новая проверка.
Такой подход естественно сочетается с кешем, описанным выше.
Синхронизировать занятия по разности
Если вы поддерживаете синхронизированную копию занятий, опция С данными события изменения расписания позволяет получать разность, содержащую добавленные, изменённые и удалённые занятия.
Тогда ваше приложение может применять только эти изменения, не получая заново всё расписание целиком.
Гарантировать получение уведомлений
Omniscol делает только одну попытку отправки на каждый вебхук. Он ждёт не более четырёх секунд, не повторяет отправку при сбое и фиксирует его в своих журналах.
Поэтому ваш сервер должен быстро подтверждать получение ответом 200 OK или
202 Accepted, а необходимую обработку выполнять асинхронно.
Сохраняйте также периодическую повторную проверку как резервный механизм. Если
ваш сервер был недоступен в момент отправки вебхука, эта проверка позволит
обнаружить пропущенные изменения. Благодаря ответам 304 она остаётся
недорогой, когда данные актуальны.
Защитить вебхуки
Чтобы убедиться, что уведомление действительно пришло от Omniscol, настройте пользовательский HTTP-заголовок с секретом, известным только вашему приложению и Omniscol. Ваш сервер должен отклонять вызовы, не содержащие ожидаемого значения.
Два дополнительных заголовка содержат сведения о контексте уведомления:
X-Schoolидентифицирует соответствующую учётную запись Omniscol;X-OS-authсодержит токен аутентификации пользователя, внёсшего изменение.
Токен, передаваемый в X-OS-auth, конфиденциален. Не записывайте его в свои
журналы, не передавайте другим сервисам и строго ограничьте доступ к нему.
Запрашивать только необходимые данные
Ответ с меньшим объёмом данных, как правило, быстрее формируется, передаётся и сохраняется в кеше.
Для занятий ограничивайте запрашиваемый период и фильтруйте результаты по интересующим вас сущностям (см. API занятий).
Для поиска конечная точка search/query предлагает фильтры, проекцию полей и
постраничный вывод (см. Расширенные запросы).
Чтобы обновить большое количество однотипных элементов (классов, кабинетов, дисциплин и т. д.), используйте конечные точки, позволяющие передать всю коллекцию одним запросом, если они есть в документации OpenAPI, вместо множества отдельных вызовов.
Соблюдать ограничения частоты запросов
К вызовам API применяются два ограничения частоты запросов. Когда ограничение
достигнуто, Omniscol отвечает 429 Too Many Requests и заголовком
Retry-After, указывающим, сколько секунд нужно подождать перед повторным
запросом.
Ограничение по IP-адресу
Общее ограничение составляет 300 запросов за окно в 10 секунд для всех конечных точек API, включая MCP и информационные панели.
Для правильно спроектированной интеграции этого порога, как правило, достаточно. Тем не менее его можно достичь циклами вызовов без пауз или чрезмерным числом параллельных запросов.
Ограничение по ключу API
Токены, выданные одним ключом API, делят две квоты:
- 60 запросов в минуту;
- 5 000 запросов в сутки.
Ответы могут содержать следующие заголовки, позволяющие отслеживать расход:
RateLimit-Policyуказывает действующие квоты, например60;w=60, 5000;w=86400;RateLimit-Limitуказывает квоту, соответствующую ближайшему к исчерпанию ограничению;RateLimit-Remainingуказывает количество запросов, всё ещё доступных для этой квоты;RateLimit-Resetуказывает число секунд до её обновления.
Эти заголовки, в частности, отсутствуют в ответах 304, полученных без
перечитывания данных: их отсутствие не означает, что квота исчерпана.
Когда квота исчерпана, ответ 429 также указывает время ожидания в своём
теле, в поле retry_after.
Ответы 304, полученные без перечитывания данных, не засчитываются в эти
квоты, но на них распространяется общее ограничение по IP-адресу.
Если эти ограничения мешают законному использованию API, свяжитесь с нами, а не создавайте дополнительные ключи.
Обрабатывать ошибки и повторные попытки
После ответа 429
Выдержите паузу, указанную в Retry-After, прежде чем повторять запрос.
Немедленная повторная попытка бесполезна и может затянуть ситуацию, особенно
если несколько процессов вашего приложения одновременно делают новые попытки.
После ошибки сервера или превышения времени ожидания
После ошибки 5xx или превышения времени ожидания запрос на чтение можно
повторить с увеличивающейся задержкой между попытками: например, одна
секунда, затем две, затем четыре, вплоть до максимального числа попыток.
Для запроса на запись ситуация иная: изменение могло быть сохранено, даже если ответ до вас так и не дошёл. Прежде чем повторять операцию, проверьте фактическое состояние данных, чтобы избежать дублирующих изменений.
После ответа 401
Ответ 401 Unauthorized, как правило, нельзя устранить повторной попыткой с
тем же токеном. Он может, в частности, означать, что срок действия токена
истёк, что его ключ API удалён или у него истёк срок действия, либо что
запрошенная конечная точка не входит в число разрешённых для него.
Проверьте токен и связанные с ним разрешения, прежде чем повторять вызов (см. API Omniscol).