ページネーションについて
GitHubの GraphQL API では、GitHubのサーバーに対する過剰または不正な要求から保護するために、1 つの要求でフェッチできる項目の数が制限されます。 GraphQL API を使用する場合は、任意の接続に対して first または last 引数を指定する必要があります。 これらの引数の値は 1～100 で指定してください。 GraphQL API は、first または last 引数で指定された接続の数を返します。
アクセスするデータの接続数が、first または last 引数で指定された項目の数よりも多い場合、応答は指定したサイズの小さい "ページ" に分割されます。 これらのページは、データ セット全体が取得されるまで、1 つずつ順番に取得できます。 各ページには、first または last 引数で指定された項目の数が含まれます。そのページが最後のページである場合は、含まれる項目の数が少なくなる場合があります。
このガイドでは、ページ分割された応答に結果の追加ページを要求する方法、各ページで返される結果の数を変更する方法、および複数の結果ページをフェッチするスクリプトを記述する方法を示します。
クエリで cursor を要求する
GraphQL API を使用する際は、カーソルを使用して、ページネーションされたデータセットを移動します。 カーソルは、データ セット内の特定の位置を表します。
pageInfo オブジェクトに対してクエリを実行すると、ページの最初と最後のカーソルを取得できます。 次に例を示します。
query($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
pullRequests(first: 100, after: null) {
nodes {
createdAt
number
title
}
pageInfo {
endCursor
startCursor
hasNextPage
hasPreviousPage
}
}
}
}
この例では、 pageInfo.startCursor はページの最初の項目のカーソルを指定します。
pageInfo.endCursor は、ページの最後の項目のカーソルを指定します。
pageInfo.hasNextPage と pageInfo.hasPreviousPage は 、返されたページの前後にページがあるかどうかを示します。
ページごとのアイテム数の変更
`first` および `last` 引数は、返される項目の数を制御します。
`first` または `last` 引数を使用してフェッチできる項目の最大数は 100 個です。 レートまたはノードの制限に達しないように、クエリが大量のデータにタッチする場合は、100 個未満の項目を要求する必要がある場合があります。 詳しくは、「[AUTOTITLE](/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api)」をご覧ください。
ページネーションを使用したデータセットの巡回
クエリからカーソルを返したら、カーソルを使用して結果の次のページを要求できます。 そのためには、after または before の引数とカーソルを使用します。
たとえば、前の例の pageInfo.endCursor 値が Y3Vyc29yOnYyOpHOUH8B7g== であったと仮定すると、このクエリを使用して結果の次のページを要求できます。
query($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
pullRequests(first: 1, after: "Y3Vyc29yOnYyOpHOUH8B7g==") {
nodes {
createdAt
number
title
}
pageInfo {
endCursor
hasNextPage
hasPreviousPage
}
}
}
}
走査するページがなくなるまで、応答で返された新しい pageInfo.endCursor 値を使用してクエリを送信し続けることができ、それは pageInfo.hasNextPage が false を返すことによって示されます。
`last` 引数の代わりに `first` を指定した場合、結果の最後のページが最初に返されます。 この場合は、`pageInfo.startCursor` 値と `before` 引数を使用して、結果の前のページを取得します。
`pageInfo.hasPreviousPage` が `false` を返したら、最後のページに到達していることになります。 次に例を示します。
query($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
pullRequests(last: 1, before: "R3Vyc29yOnYyOpHOHcfoOg==") {
nodes {
createdAt
number
title
}
pageInfo {
startCursor
hasPreviousPage
}
}
}
}
次のステップ
GitHub の Octokit SDK と octokit/plugin-paginate-graphql プラグインを使用して、スクリプトでのページネーションをサポートすることができます。 詳細については、「plugin-paginate-graphql.jsを参照してください。