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 個未満の項目を要求する必要がある場合があります。 詳しくは、「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 を参照してください。