Примечание.
Ограничения скорости включены только для вашего экземпляра, если администратор сайта включил их. Даже если ограничения скорости отключены для вашего экземпляра, вы можете по-прежнему следовать рекомендациям, которые помогут вам избежать превышения предела скорости. Это может помочь уменьшить нагрузку на серверах.
Избегайте опроса
Вы должны подписаться на события веб-перехватчика вместо опроса API для данных. Это поможет вашей интеграции оставаться в пределах ограничения скорости API. Дополнительные сведения см. в разделе Документация по веб-перехватчикам.
Если вы не можете использовать веб-перехватчики и необходимо провести опрос API, провести опрос как можно эффективнее, чтобы избежать превышения ограничения скорости:
- Опрос только так часто, как нужно, по фиксированному расписанию. Если ответ содержит
x-poll-intervalзаголовок, подождите по крайней мере, что много секунд, прежде чем снова опросить ту же конечную точку. - Сделайте прошедшие проверку подлинности условные запросы, чтобы без изменений данные не учитываются в отношении основного ограничения скорости. Дополнительные сведения см. в разделе "Использование условных запросов".
- Запрашивайте только необходимые данные и сохраняйте ответы в стабильном режиме, чтобы больше ваших опросов возвращались
304 Not Modified. Дополнительные сведения см. в разделе "Запросы, которые можно кэшировать".
Создание аутентифицированных запросов
Запросы, прошедшие проверку подлинности, имеют более высокий уровень первичной частоты, чем запросы без проверки подлинности. Чтобы избежать превышения предела скорости, следует выполнять прошедшие проверку подлинности запросы. Дополнительные сведения см. в разделе Ограничения скорости для REST API.
Избегайте одновременных запросов
Чтобы избежать превышения ограничений вторичной частоты, следует выполнять последовательные запросы вместо параллельного выполнения. Для этого можно реализовать систему очередей для запросов.
Приостановка между мутативными запросами
Если вы делаете большое количество POST, PATCH``PUTили DELETE запросы, подождите по крайней мере одну секунду между каждым запросом. Это поможет избежать дополнительных ограничений скорости.
Обработка ошибок ограничения скорости соответствующим образом
Если вы получаете ошибку ограничения скорости, следует временно прекратить выполнение запросов в соответствии с этими рекомендациями:
retry-afterЕсли заголовок ответа присутствует, не следует повторять запрос до тех пор, пока не истекло много секунд.- Если заголовок
x-ratelimit-remainingимеет значение0, вы не должны выполнять другой запрос до тех пор, пока время, указанное заголовкомx-ratelimit-reset. Заголовокx-ratelimit-resetнаходится в секундах эпохи UTC. - В противном случае дождитесь хотя бы одной минуты, прежде чем повторить попытку. Если запрос продолжает завершаться ошибкой из-за дополнительного ограничения скорости, подождите экспоненциально увеличивающееся время между повторными попытками и вызовите ошибку после определенного числа повторных попыток.
Продолжая делать запросы во время ограничения скорости, может привести к запрету интеграции.
Следуйте перенаправлениям
GitHub REST API использует HTTP-перенаправление, где это уместно. Следует предположить, что любой запрос может привести к перенаправлению. Получение перенаправления HTTP не является ошибкой, и вы должны следовать перенаправлению.
Код 301 состояния указывает на постоянное перенаправление. Необходимо повторить запрос к URL-адресу, указанному заголовком location . Кроме того, необходимо обновить код, чтобы использовать этот URL-адрес для будущих запросов.
302 Код 307 состояния или указывает временное перенаправление. Необходимо повторить запрос к URL-адресу, указанному заголовком location . Однако не следует обновлять код, чтобы использовать этот URL-адрес для будущих запросов.
Другие коды состояния перенаправления могут использоваться в соответствии с спецификациями HTTP.
Не анализируйте URL-адреса вручную
Многие конечные точки API возвращают значения URL-адреса для полей в тексте ответа. Не следует пытаться проанализировать эти URL-адреса или предсказать структуру будущих URL-адресов. Это может привести к нарушению вашей интеграции, если GitHub в будущем изменится структура URL. Вместо этого следует искать поле, содержащее необходимые сведения. Например, конечная точка для создания проблемы возвращает html_url поле со значением, как https://github.com/octocat/Hello-World/issues/1347 и number поле со значением, например 1347. Если вам нужно знать количество проблем, используйте number поле вместо синтаксического анализа html_url поля.
Аналогичным образом не следует пытаться вручную создавать запросы на страницы. Вместо этого следует использовать заголовки ссылок, чтобы определить, какие страницы результатов можно запросить. Дополнительные сведения см. в разделе Использование разбиения на страницы в REST API.
Использование условных запросов
Большинство конечных точек возвращают etag заголовок, и многие конечные точки возвращают last-modified заголовок. Значения этих заголовков можно использовать для выполнения условных GET запросов. Если ответ не изменился, вы получите 304 Not Modified ответ. Выполнение условного запроса не учитывается в отношении основного ограничения скорости, если 304 возвращается ответ, и запрос был выполнен правильно авторизован с заголовком Authorization . Это делает условные запросы особенно полезными при опросе конечной точки, так как каждый 304 Not Modified ответ быстро и не использует ограничение скорости.
В следующих примерах замените YOUR-TOKEN маркер доступа. Замените REPO-OWNER учетной записью, владеющей репозиторием, и замените REPO-NAME именем репозитория.
Выполнение условного запроса с помощью etag:
-
Выполните запрос и сохраните значение заголовка
etagиз ответа.curl --include --header "Authorization: Bearer YOUR-TOKEN" http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pullsОтвет включает
etagзаголовок:HTTP/2 200 etag: "644b5b0155e6404a9cc4bd9d8b1ae730" -
В следующем запросе на тот же URL-адрес отправьте сохраненное значение в заголовке
if-none-match.curl --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"' http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pullsЕсли данные не изменились, вы получите
304 Not Modifiedответ, который не учитывается в отношении основного ограничения скорости:HTTP/2 304
Вы также можете использовать last-modified заголовок. Например, если предыдущий last-modified запрос вернул значение Wed, 25 Oct 2023 19:17:59 GMTзаголовка, можно использовать if-modified-since заголовок в следующем запросе:
curl --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT' http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME
Условные запросы для небезопасных методов, таких как POST, PUT``PATCHи DELETE не поддерживаются, если иное не указано в документации для определенной конечной точки.
Создание запросов, которые можно кэшировать
Условный запрос экономит время и ограничение скорости, если конечная точка возвращается 304 Not Modified. Конечная точка возвращается 304 , когда запрошенное представление не изменилось после сохранения его etag или last-modified значения; несвязанные заголовки ответа, такие как дата, по-прежнему могут отличаться. Чтобы сделать 304 ответы более вероятными при опросе, сохраняйте свои запросы стабильными и конкретными.
Запрашивайте только необходимые данные. Меньший, более конкретный ответ меняется реже, поэтому он возвращается 304 Not Modified чаще. Например, чтобы проверить запросы на вытягивание для одной ветви, отфильтруйте список по этой ветви вместо перечисления каждого запроса на вытягивание и поиска результатов самостоятельно. Замените HEAD-OWNER учетной записью, которая владеет головной ветвью; для запроса на вытягивание из вилки это учетная запись, которая владеет вилкой. Замените BRANCH-NAME именем ветви и ЗАкодируйте URL-адрес, если он содержит специальные символы, такие как # или &:
curl --include --header "Authorization: Bearer YOUR-TOKEN" "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/pulls?head=HEAD-OWNER:BRANCH-NAME"
При просмотре списка используйте стабильный порядок сортировки. Некоторые параметры, например sort=updated, переупорядочение списка при изменении элемента. При переходе элемента на новую позицию элементы между старыми и новыми позициями перемещаются на разные страницы, поэтому страницы, которые вы уже извлекли, могут возвращать новые данные вместо 304 Not Modified. Стабильный порядок, например по умолчанию, останавливает обновления существующих элементов от переупорядочения списка, хотя добавление или удаление элементов по-прежнему может перемещать записи на другие страницы.
Используйте одни и те же параметры при каждом опросе одних и того же данных. Другой размер страницы, номер страницы или фильтр создает другой ответ с другим etag.
Не игнорируйте ошибки
Не следует игнорировать повторяющиеся 4xx и 5xx коды ошибок. Вместо этого необходимо убедиться, что вы правильно взаимодействуете с API. Например, если конечная точка запрашивает строку и передаете его числовое значение, вы получите ошибку проверки. Аналогичным образом, попытка доступа к неавторизованной или несуществующей конечной точке приведет к ошибке 4xx.
Если вы опрашивание и ресурс неоднократно возвращает 404 Not Found ответ, не продолжайте запрашивать его на каждом опросе. Сначала убедитесь, что он 404 не вызван проверкой подлинности или авторизацией.
GitHub
404 Not Found возвращает ответ вместо ответа 403 Forbidden на некоторые частные ресурсы, если учетные данные не предоставляют доступ, поэтому 404 не всегда означает, что ресурс отсутствует. Дополнительные сведения см. в разделе Устранение неполадок с REST API. Убедившись, что ваши учетные данные верны, подождите гораздо дольше, прежде чем снова проверить или повторите проверку только в том случае, если у вас есть причина поверить, что ресурс существует. Многократно запрашивая отсутствующий ресурс, выпустите ограничение скорости и может активировать дополнительный предел скорости.
Намеренное игнорирование повторяющихся ошибок проверки может привести к временному блокированию приложения из-за нарушения.