在 GraphQL API 中使用分页

关于分页

GitHub 的 GraphQL API 限制了您可以在单个请求中获取的项目数量，以防止对 GitHub 服务器进行过度或滥用请求。当您使用 GraphQL API 时，必须在任何连接上提供 first 或 last 参数。这些参数的值必须介于 1 到 100 之间。GraphQL API 将返回由 first 或 last 参数指定的连接数量。

如果您访问的数据连接数量超过 first 或 last 参数指定的项目数量，则响应将被分成指定大小的较小的“页面”。这些页面可以一次获取一个，直到检索到整个数据集。每个页面包含由 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指示。

如果您指定了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."