GraphQL API에서 페이지 매김 사용

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
      }
    }
  }
}

false을(를) 반환하는 pageInfo.hasNextPage(으)로 표시되는 트래버스할 페이지가 없을 때까지 응답에 반환된 새 pageInfo.endCursor 값이 있는 쿼리를 계속 보낼 수 있습니다.

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"를 참조하세요.