改ページ位置の自動修正について
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 個未満の項目を要求する必要がある場合があります。 詳しくは、「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
を返すことによって示されます。
first
引数の代わりに last
を指定した場合、結果の最後のページが最初に返されます。 この場合は、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」を参照してください。