Ограничения скорости и ограничения запросов для API GraphQL

Ограничение основной скорости

API GraphQL назначает точки каждому запросу и ограничивает точки, которые можно использовать в течение определенного периода времени. Это ограничение помогает предотвратить злоупотребления и атаки типа "отказ в обслуживании" и гарантирует, что API остается доступным для всех пользователей.

REST API также имеет отдельный основной предел скорости. Дополнительные сведения см. в разделе Ограничения скорости для REST API.

Как правило, вы можете вычислить основной предел скорости для API GraphQL на основе метода проверки подлинности:

Для пользователей: 5000 точек в час на пользователя. Это включает запросы, сделанные как с помощью пользователя, personal access tokenGitHub AppOAuth app так и от имени пользователя, авторизовавшего приложение. Запросы, сделанные от имени пользователя, GitHub App принадлежащим организации GitHub Enterprise Cloud , имеют более высокий лимит ставки — 10 000 баллов в час. Аналогично, запросы, OAuth app сделанные от вашего имени компаниейGitHub Enterprise Cloud, принадлежащей или одобренной GitHub Enterprise Cloud организацией, имеют более высокий лимит ставки — 10 000 баллов в час, если вы являетесь членом организации.
Для GitHub App установок, не входящих в GitHub Enterprise Cloud организацию или предприятие: 5 000 очков в час за одну установку. Установки, имеющие более 20 репозиториев, получают еще 50 точек в час для каждого репозитория. Установки, которые находятся в организации с более чем 20 пользователями, получают еще 50 очков в час для каждого пользователя. Ограничение скорости не может превышать 12500 точек в час. Лимит скорости для токенов user access (в отличие от токенов установки access) определяется основным лимитом для пользователей.
Для GitHub App установок в GitHub Enterprise Cloud организации или предприятии: 10 000 очков в час за одну установку. Лимит скорости для токенов user access (в отличие от токенов установки access) определяется основным лимитом для пользователей.
Для OAuth apps: 5 000 баллов в час или 10 000 очков в час, если приложение принадлежит организации GitHub Enterprise Cloud . Это применяется только при использовании идентификатора клиента и секрета клиента для запроса общедоступных данных. Лимит скорости для токенов доступа OAuth, генерируемых a, OAuth app определяется основным лимитом для пользователей.
Для GITHUB_TOKEN рабочих GitHub Actions процессов: 1000 очков в час на репозиторий. Для запросов к ресурсам, принадлежащим корпоративному аккаунту на GitHub.com, лимит составляет 15 000 очков в час на репозиторий.

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

Проверка состояния основного ограничения скорости

Вы можете использовать заголовки, отправляемые с каждым ответом, чтобы определить текущее состояние основного ограничения скорости.

Имя заголовка	Description
`x-ratelimit-limit`	Максимальное количество точек, которые можно использовать в час
`x-ratelimit-remaining`	Количество точек, оставшихся в текущем окне ограничения скорости
`x-ratelimit-used`	Количество точек, использованных в текущем окне ограничения скорости
`x-ratelimit-reset`	Время сброса текущего ограничения скорости в секундах в формате UTC
`x-ratelimit-resource`	Ресурс ограничения скорости, к которому подсчитывается запрос. Для запросов GraphQL это всегда будет `graphql`.

Вы также можете запросить rateLimit объект, чтобы проверить ограничение скорости. По возможности следует использовать заголовки ответов ограничения скорости вместо запроса API, чтобы проверить ограничение скорости.

query {
  viewer {
    login
  }
  rateLimit {
    limit
    remaining
    used
    resetAt
  }
}

Поле	Description
`limit`	Максимальное количество точек, которые можно использовать в час
`remaining`	Количество точек, оставшихся в текущем окне ограничения скорости
`used`	Количество точек, использованных в текущем окне ограничения скорости
`resetAt`	Время сброса текущего ограничения скорости в секундах в формате UTC

Возврат значения точки запроса

Вы можете вернуть значение точки запроса, запросив cost поле в объекте rateLimit :

query {
  viewer {
    login
  }
  rateLimit {
    cost
  }
}

Прогнозирование значения точки запроса

Вы также можете примерно вычислить значение точки запроса перед выполнением запроса.

Сложите количество запросов, необходимых для выполнения каждого уникального подключения в вызове. Предположим, что каждый запрос будет достигать ограничений для аргумента first или last.
Разделите число на 100 и округите результат до ближайшего целого числа, чтобы получить окончательное значение статистической точки. На этом шаге нормализуется большое число.

Примечание.

Минимальное значение точки вызова API GraphQL равно 1.

Ниже приведен пример запроса и вычисления оценки.

query {
  viewer {
    login
    repositories(first: 100) {
      edges {
        node {
          id

          issues(first: 50) {
            edges {
              node {
                id

                labels(first: 60) {
                  edges {
                    node {
                      id
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Для выполнения этого запроса требуется 5101 вызов:

Хотя возвращается 100 репозиториев, API должен подключиться к учетной записи зрителя один раз, чтобы получить список репозиториев. Таким образом, число запросов для репозиториев = 1.
Хотя возвращается 50 проблем, API должен подключиться к каждому из 100 репозиториев, чтобы получить список проблем. Таким образом, число запросов для проблем = 100.
Хотя возвращается 60 меток, API должен подключиться к каждой из 5000 потенциальных проблем, чтобы получить список меток. Таким образом, число запросов для меток = 5000.
Всего 5101 запрос.

Разделим на 100, округлим, и получим окончательную оценку для запроса: 51.

Дополнительные ограничения скорости

Помимо ограничений основной частоты GitHub применяет ограничения вторичной частоты, чтобы предотвратить злоупотребление и сохранить API доступным для всех пользователей.

Если вы можете столкнуться с дополнительным ограничением скорости:

Сделайте слишком много одновременных запросов. Допускается не более 100 одновременных запросов. Это ограничение используется для REST API и API GraphQL.
Сделайте слишком много запросов к одной конечной точке в минуту. Для конечных точек REST API разрешено не более 900 точек в минуту, а для конечной точки API GraphQL разрешено не более 2000 точек в минуту. Дополнительные сведения о точках см. в разделе "Вычисление точек" для дополнительного ограничения скорости.
Сделайте слишком много запросов в минуту. Допускается не более 90 секунд ЦП в 60 секунд в реальном времени. Не более 60 секунд этого времени ЦП может быть для API GraphQL. Вы можете приблизительно оценить время ЦП, измеряя общее время отклика для запросов API.
Слишком много запросов, которые потребляют чрезмерные вычислительные ресурсы в течение короткого периода времени.
Создание слишком большого объема содержимого на GitHub в течение короткого времени. Как правило, не более 80 запросов на создание содержимого в минуту и не более 500 запросов на создание контента в час. Некоторые конечные точки имеют более низкие ограничения на создание контента. Ограничения создания контента включают действия, выполняемые на веб-интерфейсе GitHub и через REST API и API GraphQL.
Сделайте слишком много запросов на токены доступа OAuth за короткое время. Не более 2 000 запросов на OAuth token доступа в час для GitHub Apps и OAuth apps.

Эти ограничения вторичной ставки подлежат изменению без уведомления. Вы также можете столкнуться с дополнительным ограничением скорости по нераскрытым причинам.

Вычисление точек для дополнительного ограничения скорости

Некоторые ограничения вторичной частоты определяются значениями точек запросов. Для запросов GraphQL эти значения точек отделены от вычислений значений точек для основного ограничения скорости.

Запросить	Точки
Запросы GraphQL без изменений	1
Запросы GraphQL с изменениями	5
Большинство REST API `GET`и HEAD``OPTIONS запросов	1
Большинство REST API`POST`, PATCH``PUTили `DELETE` запросов	5

Некоторые конечные точки REST API имеют другую стоимость точки, которая не является общедоступной.

Превышение предела скорости

Если вы превышаете основной предел частоты, состояние ответа по-прежнему будет отображаться200, но вы получите сообщение об ошибке, а значение заголовка x-ratelimit-remaining будет.0 Не следует повторять запрос до тех пор, пока не указано время, указанное заголовком x-ratelimit-reset .

Если превышено ограничение вторичной скорости, состояние ответа будет 200 или 403, и вы получите сообщение об ошибке, указывающее, что вы достигли дополнительного ограничения скорости. retry-after Если заголовок ответа присутствует, не следует повторять запрос до тех пор, пока не истекло много секунд. Если заголовок x-ratelimit-remaining имеет значение 0, то не следует повторять запрос до тех пор, пока не будет время, в секундах эпохи UTC, указанных заголовком x-ratelimit-reset . В противном случае дождитесь хотя бы одной минуты, прежде чем повторить попытку. Если запрос продолжает завершаться ошибкой из-за дополнительного ограничения скорости, подождите экспоненциально увеличивающееся время между повторными попытками и вызовите ошибку после определенного числа повторных попыток.

Продолжая делать запросы во время ограничения скорости, может привести к запрету интеграции.

Оставаться под ограничением скорости

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

Кроме того, следует подписаться на события веб-перехватчика вместо опроса API для данных. Дополнительные сведения см. в разделе Документация по веб-перехватчикам.

Вы также можете потоковую передачу журнала аудита для просмотра запросов API. Это поможет устранить неполадки интеграции, превышающие ограничение скорости. Дополнительные сведения см. в разделе Потоковая передача журнала аудита для предприятия.

Предельное число узлов

Для прохождения валидации schema все API GraphQL calls должны соответствовать следующим стандартам:

Клиенты должны предоставить аргумент first или last по любому связи.
Значения first и last должны находиться в пределах 1–100.
Отдельные звонки не могут запрашивать более 500 000 узлов.

Подсчет узлов в вызове

В этих двух примерах показано, как вычислить общее количество узлов в вызове.

Простой запрос:

query {
  viewer {
    repositories(first: 50) {

edges { repository:node { name

issues(first: 10) { totalCount edges { node { title bodyHTML } } } } } } } }

Расчет:

50         = 50 repositories
    +
   50 x 10  = 500 repository issues

= 550 total nodes

Сложный запрос:

query {
  viewer {
    repositories(first: 50) {

edges { repository:node { name

pullRequests(first: 20) { edges { pullRequest:node { title

comments(first: 10) { edges { comment:node { bodyHTML } } } } } }

issues(first: 20) { totalCount edges { issue:node { title bodyHTML

comments(first: 10) { edges { comment:node { bodyHTML } } } } } } } } }

   followers(first: <span class="bluebox">10</span>) {

edges { follower:node { login } } } } }

Расчет:

50              = 50 repositories
    +
   50 x 20       = 1,000 pullRequests
    +
   50 x 20 x 10 = 10,000 pullRequest comments
    +
   50 x 20       = 1,000 issues
    +
   50 x 20 x 10 = 10,000 issue comments
    +
   10              = 10 followers

= 22,060 total nodes

Время ожидания

Если GitHub обработка запроса API-запроса занимает более 10 секунд, GitHub запрос будет завершен, и вы получите ответ на тайм-аут и сообщение о том, что «Мы не смогли ответить на ваш запрос вовремя».

Когда это происходит, вы можете получить либо статус кода a 502 или 504 . Оба статуса указывают на то, что ваш запрос истёк.

GitHub оставляет за собой право изменять окно тайм-аута для защиты скорости и надёжности API.

Вы можете проверить состояние API GraphQL на githubstatus.com , чтобы определить, связано ли время ожидания с API. Вы также можете попытаться упростить запрос или попробовать его позже. Для советов по улучшению эффективности запросов смотрите стратегии оптимизации запросов.

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

Другие ограничения ресурсов

Для защиты скорости и надёжности API GitHub также применяется другие ограничения по ресурсам. Если ваш запрос в GraphQL потребляет слишком много ресурсов, GitHub запрос прекратится и вернёт частичные результаты вместе с ошибкой, указывающей на превышение лимитов ресурсов.

Примеры запросов, которые могут превышать ограничения ресурсов:

Запрос тысяч объектов или глубоко вложенных связей в одном запросе.
Одновременное использование больших first или last аргументов в нескольких подключениях.
Получение подробных сведений для каждого объекта, например всех комментариев, реакций и связанных проблем для каждого репозитория.

Стратегии оптимизации запросов

Ограничение количества объектов: используйте меньшие значения для first или last аргументов и размыкайтесь по результатам.
Уменьшите глубину запроса: не запрашивайте глубоко вложенные объекты, если это не необходимо.
Результаты фильтрации: используйте аргументы для фильтрации данных и возврата только необходимых данных.
Разделение больших запросов: разбиение сложных запросов на несколько простых запросов.
Запрос только обязательных полей: выберите только нужные поля, а не запрос всех доступных полей.

Следуя этим стратегиям, вы можете снизить вероятность попадания ограничений ресурсов и повысить производительность и надежность запросов API.

Ограничения скорости и ограничения запросов для API GraphQL

В этой статье