Руководство по регулированию Microsoft Graph

Регулирование позволяет ограничить количество одновременных вызовов службы, чтобы предотвратить чрезмерную нагрузку на ресурсы. Служба Microsoft Graph предназначена для обработки большого объема запросов. Если запросов приходит слишком много, Microsoft Graph использует регулирование, чтобы поддерживать оптимальную производительность и надежность службы.

Ограничения регулирования зависят от сценария. Например, если выполняется большой объем операций записи, возможность регулирования выше, чем при выполнении только операций чтения.

Примечание.

Для решений, которым нужно извлекать большой объем данных из Microsoft Graph, вместо REST API Microsoft Graph должен использоваться Microsoft Graph Data Connect . Microsoft Graph Data Connect позволяет организациям массово извлекать данные Microsoft 365 без ограничений регулирования.

Что происходит при регулировании?

При превышении порогового значения регулирования Microsoft Graph ограничивает все дальнейшие запросы от этого клиента на определенный период времени. При регулировании Microsoft Graph возвращает код состояния HTTP 429 (слишком много запросов), и запросы завершаются ошибкой. Рекомендуемое время ожидания возвращается в заголовке ответа неудачного запроса. Поведение регулирования может зависеть от типа и количества запросов. Например, если у вас большой объем запросов, все типы запросов регулируются. Пороговые ограничения зависят от типа запроса. Таким образом, можно столкнуться с сценарием, в котором запись регулируется, но чтение по-прежнему разрешено.

Распространенные сценарии регулирования

Наиболее распространенные причины регулирования клиентов:

• большое количество запросов во всех приложениях клиента;
• большое количество запросов из конкретного приложения всех клиентов.

Пример отклика

При превышении порога регулирования Microsoft Graph реагирует с откликом, похожим на следующий.

HTTP/1.1 429 Too Many Requests
Content-Length: 312
Content-Type: application/json
Retry-After: 10

{
  "error": {
    "code": "TooManyRequests",
    "innerError": {
      "code": "429",
      "date": "2020-08-18T12:51:51",
      "message": "Please retry after",
      "request-id": "94fb3b52-452a-4535-a601-69e0a90e3aa2",
      "status": "429"
    },
    "message": "Please retry again later."
  }
}

Рекомендации по решению проблем с регулированием

Ниже приведены рекомендации по работе с регулированием.

• Сократите число операций каждого запроса.
• Сократите частоту вызовов.
• Избегайте немедленных повторов, так как запросы накапливаются, и их количество превышает ограничения использования.

При реализации обработки ошибок используйте код ошибки HTTP 429 для обнаружения регулирования. Неудачный ответ включает заголовок Retry-After ответа. Резервное копирование запросов с помощью задержки Retry-After — это самый быстрый способ восстановления после регулирования, так как Microsoft Graph продолжает регистрировать использование ресурсов во время регулирования клиента.

1. Подождите столько секунд, сколько указано в заголовке Retry-After.
2. Повторите запрос.
3. Если запрос снова завершается ошибкой с кодом ошибки 429, вы по-прежнему регулируетесь. Продолжайте использовать рекомендуемую Retry-After задержку и повторите запрос, пока он не завершится успешно.

Все ресурсы и API, описанные в разделе Ограничения для отдельных служб, предоставляют заголовок Retry-After, если не указано иное.

Развернутое описание регулирования в Microsoft Cloud см. в статье Модель регулирования.

Примечание.

Если в ответе не предоставляется заголовок Retry-After, рекомендуем реализовать политику повторения экспоненциальной задержки. Вы также можете реализовать более сложные шаблоны при создании крупномасштабных приложений.

В пакетах SDK Microsoft Graph уже реализованы обработчики, основанные на заголовке Retry-After или (по умолчанию) на политике повторения экспоненциальной задержки.

Рекомендации по избежанию регулирования

Шаблоны программирования, например постоянные опросы на ресурсе для проверки обновлений и регулярное сканирование коллекций ресурсов для проверки новых или удаленных ресурсов, чаще ведут к регулированию приложений и ухудшению общей производительности. Вместо этого необходимо по возможности использовать отслеживание изменений и уведомления об изменениях.

Примечание.

Подробные сведения — в рекомендациях по обнаружению файлов и определению изменений в масштабе.

Регулирование и пакетная обработка

Пакетная обработка JSON позволяет оптимизировать приложение, объединив несколько запросов в один объект JSON. Запросы в пакете оцениваются по отдельности с ограничениями регулирования, и если какой-либо запрос превышает ограничения, он завершается ошибкой с кодом 429 состояния и ошибкой, аналогичной предыдущему примеру ответа. Сам пакет завершается успешно с кодом 200 состояния (ОК). Несколько запросов можно регулировать в одном пакете. Вам следует повторно выполнить каждый неудачный запрос из пакета, используя значение, предоставленное в заголовке отклика retry-after из содержимого JSON. Вы можете повторить попытку выполнения всех неудачных запросов в новом пакете после самого долгого значения retry-after.

Если пакеты SDK автоматически повторно выполняют регулируемые запросы, не являющиеся пакетными, регулируемые запросы, входящие в пакет, не выполняются повторно автоматически.

Следующее действие

Определение ограничений регулирования для различных ресурсов Microsoft Graph