GraphQL API のレート制限とノード制限

ノードの制限

スキーマ検証に合格するには、すべての GraphQL API 呼び出しが次の標準を満たしている必要があります。

クライアントでは、すべての接続で first または last 引数を指定する必要があります。
first と last の値は 1 から 100 である必要があります。
個々の呼び出しでは、合計 500,000 個を超えるノードを要求することはできません。

呼び出し中のノードの計算

以下の2つの例は、呼び出し中の合計ノード数を計算する方法を示しています。

単純なクエリ：

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: 10) {
      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

プライマリレート制限

GraphQL API は、各クエリにポイントを割り当て、特定の時間内に使用できるポイントを制限します。この制限は、不正使用やサービス拒否攻撃を防ぐのに役立ち、すべてのユーザーが API を使用できるようにします。

REST API には、個別のプライマリレート制限もあります。詳しくは、「REST API のレート制限」を参照してください。

一般に、認証の方法に基づいて GraphQL API のプライマリレート制限を計算できます。

ユーザーの場合: 1 ユーザーごとに 1 時間あたり 5,000 ポイント。これには、personal access token で行われた要求と、アプリを承認したユーザーに代わって GitHub App または OAuth app によって行われた要求が含まれます。 GitHub Enterprise Cloud 組織が所有する GitHub App によってユーザーに代わって行われた要求には、1 時間あたり 10,000 ポイントのより高いレート制限があります。同様に、GitHub Enterprise Cloud 組織が所有または承認した OAuth app によってユーザーに代わって行われた要求には、GitHub Enterprise Cloud 組織のメンバーである場合、1 時間あたり 10,000 ポイントのより高いレート制限があります。
GitHub App のインストールが GitHub Enterprise Cloud 組織にない場合: インストールごとに 1 時間あたり 5,000 ポイント。 20 以上のリポジトリを持つインストールでは、リポジトリごとにⅠ時間あたり 50 ポイントが追加されます。ユーザー数が 20 人を超える組織のインストールでは、ユーザーごとに 1 時間あたり別の 50 ポイントを受け取ります。レート制限は、1 時間あたり 12,500 ポイントを超えて増やすことはできません。 (インストールアクセストークンではなく) ユーザーアクセストークンのレート制限は、ユーザーのプライマリレート制限によって決まります。
GitHub Enterprise Cloud 組織での GitHub App のインストールの場合: インストールごとに 1 時間あたり 10,000 ポイント。 (インストールアクセストークンではなく) ユーザーアクセストークンのレート制限は、ユーザーのプライマリレート制限によって決まります。
OAuth apps の場合: 1 時間あたり 5,000 ポイント、またはアプリが GitHub Enterprise Cloud 組織によって所有されている場合は 1 時間あたり 10,000 ポイント。これは、アプリがクライアント ID とクライアントシークレットを使用してパブリックデータを要求する場合にのみ適用されます。 OAuth app によって生成される OAuth アクセストークンのレート制限は、ユーザーのプライマリレート制限によって決まります。
_GitHub Actions ワークフロー_の GITHUB_TOKEN の場合: リポジトリごとに 1 時間あたり 1,000 ポイント。 GitHub.com の Enterprise アカウントに属するリソースに対する要求の場合、制限はリポジトリごとに 1 時間あたり 15,000 ポイントです。

次のセクションで説明するように、クエリのポイント値をチェックしたり、予想されるポイント値を計算したりすることができます。ポイントとレート制限を計算するための数式は、変更される可能性があります。

プライマリレート制限の状態のチェック

各応答で送信されるヘッダーを使用して、プライマリレート制限の現在の状態を判断できます。

ヘッダー名	説明
`x-ratelimit-limit`	1 時間あたりで使用できるポイントの数の上限
`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
  }
}

フィールド	説明
`limit`	1 時間あたりで使用できるポイントの数の上限
`remaining`	現在のレート制限ウィンドウ内の残っているポイントの数
`used`	現在のレート制限ウィンドウ内の使用したポイントの数
`resetAt`	現在のレート制限ウィンドウが UTC エポック秒単位でリセットされる時刻。

クエリのポイント値を返す

rateLimit オブジェクトの cost フィールドに対してクエリを実行すると、クエリのポイント値を返すことができます。

query {
  viewer {
    login
  }
  rateLimit {
    cost
  }
}

クエリのポイント値の予測

クエリを作成する前に、クエリのポイント値を大まかに計算することもできます。

呼び出し中のそれぞれのユニークなコネクションを満たすために必要なリクエスト数を加算していきます。すべての要求が first または last 引数の制限に達するとします。
その数字を 100 で除算し、結果を最も近い整数に丸めて最終的な集計ポイント値を取得します。このステップは、大きな数値を正規化します。

注: GraphQL API の呼び出しの最小ポイント値は 1 です。

以下は、クエリとスコアの計算の例です。

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

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

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

このクエリを完了するには、5,101リクエストが必要です。

100 個のリポジトリが返されますが、API でリポジトリのリストを取得するために表示者のアカウントに接続する必要があるのは一度だけです。したがって、リポジトリの要求 = 1 です
50 個の Issue が返されますが、API では Issue のリストを取得するために 100 個のリポジトリそれぞれに接続する必要があります。したがって、Issue の要求 = 100 です
60 個のラベルが返されますが、API ではラベルのリストを取得するために潜在的に合計 5,000 個の Issue のそれぞれに接続する必要があります。したがって、ラベルの要求 = 5,000 です
合計 = 5,101 です

100 で除算して丸めると、最終的なクエリのスコアは 51 になります。

セカンダリレート制限

プライマリレート制限に加えて、GitHub では、乱用を防ぎ、すべてのユーザーが API を使用できるように、セカンダリレート制限が適用されます。

次の場合、セカンダリレート制限が発生する可能性があります。

同時実行要求が多すぎます。 同時要求は 100 個以下です。この制限は、REST API と GraphQL API 全体で共有されます。
1 分あたりの 1 つのエンドポイントに対する要求が多すぎます。 REST API エンドポイントには 1 分あたり 900 ポイント以下、GraphQL API エンドポイントには 1 分あたり 2,000 ポイント以下を使用できます。ポイントの詳細については、「セカンダリレート制限のポイントの計算」を参照してください。
1 分あたりの要求が多すぎます。 リアルタイムの 60 秒あたりの CPU 時間は 90 秒以下です。 GraphQL API の場合、この CPU 時間の 60 秒以下を使用できます。 API 要求の合計応答時間を測定することで、CPU 時間を大まかに見積もることができます。
短時間に過剰なコンピューティングリソースを消費するリクエストを大量に送信します。
短時間で GitHub に大量のコンテンツを作成します。 一般に、1 分あたり 80 件以下のコンテンツ生成要求と、1 時間あたり 500 件を超えるコンテンツ生成要求は許可されません。一部のエンドポイントでは、コンテンツ作成の制限が低くなります。コンテンツ作成の制限には、GitHub ウェブインターフェイスに対して実行されるアクションと、REST API と GraphQL API を介して実行されるアクションが含まれます。

これらのセカンダリレート制限は、予告なしに変更される場合があります。また、未公開の理由により、セカンダリレート制限が発生する可能性もあります。

セカンダリレート制限のポイントの計算

一部のセカンダリレート制限は、要求のポイント値によって決まります。 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 ヘッダーで指定された時刻 (UTC エポック秒数) まで要求を再試行しないでください。

セカンダリレート制限を超えた場合は、応答の状態は 200 または 403 になり、セカンダリレート制限に達したことを示すエラーメッセージが表示されます。 retry-after 応答ヘッダーが存在する場合は、その秒数が経過するまで要求を再試行しないでください。 x-ratelimit-remaining ヘッダーが 0 の場合、x-ratelimit-reset ヘッダーで指定された時刻 (UTC エポック秒数) まで要求を再試行しないでください。それ以外の場合は、少なくとも 1 分間待ってから再試行します。セカンダリレート制限の要求が継続して失敗する場合は、再試行の間に指数関数的に増加する時間を待ち、特定の回数の再試行の後にエラーをスローします。

レート制限中に要求を続けると、統合を禁止する可能性があります。

レート制限を超えないようにする

レート制限を超えないようにするには、変更要求間で少なくとも 1 秒一時停止し、同時要求を回避する必要があります。

API でデータをポーリングする代わりに、Webhook イベントをサブスクライブする必要もあります。詳しくは、「Webhook ドキュメント」を参照してください。

API 要求を表示するために、監査ログをストリーミングすることもできます。これは、レート制限を超える統合のトラブルシューティングに役立ちます。詳しくは、「Enterprise の監査ログのストリーミング」を参照してください。

GraphQL API のレート制限とノード制限

この記事の内容