リソース制限

GitHubのGraphQL APIは、GitHubのサービスに対する過剰な呼び出し、あるいは悪用の呼び出しに対する保護としてかけられている制限があります。

ここには以下の内容があります:

ノードの制限
レート制限

ノードの制限

スキーマ検証をパスするためには、すべてのGraphQL API v4の呼び出しが以下の標準を満す必要があります。

クライアントはすべてのコネクションで引数としてfirstもしくはlastを渡さなければなりません。
first及びlastの値は1から100の間でなければなりません。
個々の呼び出しは合計500,000以上のノードをリクエストできません。

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

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

単純なクエリ：

query {
viewer {
repositories(first: 50) {
edges {
repository:node {
name
      issues(first: <span class="greenbox">10</span>) {
        totalCount
        edges {
          node {
            title
            bodyHTML
          }
        }
      }
    }
  }
}

  }
}

計算：

50         = 50 リポジトリ


50 x 10  = 500 リポジトリのIssue
        = 550 総ノード</pre>

複雑なクエリ：

query {
viewer {
repositories(first: 50) {
edges {
repository:node {
name
      pullRequests(first: <span class="greenbox">20</span>) {
        edges {
          pullRequest:node {
            title

            comments(first: <span class="bluebox">10</span>) {
              edges {
                comment:node {
                  bodyHTML
                }
              }
            }
          }
        }
      }

      issues(first: <span class="greenbox">20</span>) {
        totalCount
        edges {
          issue:node {
            title
            bodyHTML

            comments(first: <span class="bluebox">10</span>) {
              edges {
                comment:node {
                  bodyHTML
                }
              }
            }
          }
        }
      }
    }
  }
}

followers(first: <span class="bluebox">10</span>) {
  edges {
    follower:node {
      login
    }
  }
}

  }
}

計算：

50              = 50 リポジトリ


50 x 20       = 1,000 プルリクエスト


50 x 20 x 10 = 10,000 プルリクエストのコメント


50 x 20       = 1,000 Issue


50 x 20 x 10 = 10,000 Issueのコメント


10              = 10 フォロワー
             = 22,060 総ノード</pre>

レート制限

GraphQL API v4 の制限は、REST API v3 のレート制限とは異なります。

APIのレート制限が異なっているのはなぜでしょうか？ GraphQLでは、一つのGraphQLの呼び出しで複数のRESTの呼び出しを置き換えることができます。単一の複雑なGraphQLの呼び出しが、数千のRESTリクエストと等価なこともあります。単一の GraphQL 呼び出しは REST API レート制限を大幅に下回りますが、クエリはGitHub のサーバーが演算するのと同等の負荷になる可能性があります。

クエリのサーバーにとってのコストを正確に表すために、GraphQL API v4は呼び出しのレート制限スコアを正規化されたポイントのスケールに基づいて計算します。クエリのスコアは、親のコネクションやその子のfirst及びlast引数を計算に入れます。

この式は、MySQLやElasticSearch、GitといったGitHubのシステムの潜在的な負荷を事前計算するために、親のコネクション及びその子のfirst及びlast引数を使います。
新しいコネクションはそれぞれ独自のポイント値を持ちます。ポイントは呼び出しからの他のポイントと組み合わされて、全体としてのレート制限スコアになります。

GraphQL API v4のレート制限は、1時間あたり5,000ポイントです。

1時間あたり5,000ポイントは、1時間あたり5,000回の呼び出しとは同じではないことに注意してください。GraphQL API v4とREST API v3は、異なるレート制限を使います。

ノート: 現在の式とレート制限は、開発者によるGraphQL API v4の利用の様子を観察するにつれて、変更される可能性があります。

呼び出しのレート制限のステータスを返す

REST API v3 では、返された HTTP ヘッダを調べることにより、レート制限のステータスを確認できます。

GraphQL API v4では、rateLimitオブジェクトのフィールドに対してクエリを行うことで、レート制限のステータスを調べることができます。

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

limitフィールドは、60分のウィンドウ内でクライアントが消費できる最大のポイント数を返します。
costフィールドは、レート制限に対してカウントされる、現在の呼び出しのポイントコストを返します。
remainingフィールドは、現在のレート制限ウィンドウ内に残っているポイント数を返します。
resetAtは、現在のレート制限ウィンドウがリセットされる時間をUTCエポック秒で返します。

呼び出しの実行前にレート制限スコアを計算する

rateLimitオブジェクトに対してクエリを実行すれば、呼び出しのスコアが返されますが、その呼び出しを実行すると制限に対してカウントされます。このジレンマを避けるために、呼び出しのスコアを実行前に計算することができます。以下の計算は、rateLimit { cost }が返すのとおおよそ同じコストを求めます。

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

ノート: GraphQL API v4に対する呼び出しの最小コストは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になります。