GraphQL API 内での改ページ位置の自動修正の使用

GraphQL API でカーソル ベースの改ページ位置の自動修正を使用してデータ セットを走査する方法について説明します。

この記事の内容

改ページ位置の自動修正について

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 個未満の項目を要求する必要がある場合があります。 詳しくは、「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 を返すことによって示されます。

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 を参照してください。