Skip to main content

Esta versão do GitHub Enterprise Server foi descontinuada em 2024-09-25. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise Server. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

Como usar paginação na API GraphQL

Saiba como percorrer conjuntos de dados usando a paginação baseada em cursor com a API GraphQL.

Sobre paginação

A API GraphQL do GitHub limita o número de itens em que você pode efetuar fetch em uma única solicitação, para proteger contra solicitações excessivas ou abusivas aos servidores do GitHub. Ao usar a API GraphQL, você deve fornecer um argumento first ou last em todas as conexões. O valor desses argumentos deve ficar entre 1 e 100. A API GraphQL retornará o número de conexões especificado pelo argumento first ou last.

Se os dados que você está acessando tiverem mais conexões do que o número de itens especificado pelo argumento first ou last, a resposta será dividida em "páginas" menores do tamanho especificado. É possível efetuar fetch em uma dessas páginas por vez, até que todo o conjunto de dados tenha sido recuperado. Cada página contém o número de itens especificado pelo argumento first ou last, a menos que seja a última página, que talvez contenha um número menor de itens.

Este guia demonstra como solicitar páginas adicionais de resultados para respostas paginadas, como alterar o número de resultados retornados em cada página e como escrever um script para buscar várias páginas de resultados.

Como solicitar um cursor em sua consulta

Ao usar a API GraphQL, você usa cursores para percorrer um conjunto de dados paginado. O cursor representa uma posição específica no conjunto de dados. Você pode obter o primeiro e o último cursor em uma página consultando o objeto pageInfo. Por exemplo:

query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(first: 100, after: null) {
      nodes {
        createdAt
        number
        title
      }
      pageInfo {
        endCursor
        startCursor
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

Neste exemplo, pageInfo.startCursor fornece o cursor para o primeiro item na página. pageInfo.endCursor fornece o cursor para o último item na página. pageInfo.hasNextPage e pageInfo.hasPreviousPage indicam se há uma página antes e depois da que foi retornada.

Como alterar o número de itens por página

Os argumentos first e last controlam quantos itens são retornados. O número máximo de itens em que você pode efetuar fetch usando o argumento first ou last é 100. Talvez seja necessário solicitar menos de 100 itens se a consulta resultar em muitos dados, para evitar atingir um limite de uma taxa ou nó. Para obter mais informações, confira "Limites de taxa e limites de nó para a API GraphQL".

Como percorrer o conjunto de dados usando paginação

Depois de um cursor ser retornado de uma consulta, você pode usá-lo para solicitar a próxima página de resultados. Para fazer isso, você usará o argumento after ou before e o cursor.

Por exemplo, supondo que o valor pageInfo.endCursor do exemplo anterior era Y3Vyc29yOnYyOpHOUH8B7g==, você pode usar essa consulta para solicitar a próxima página de resultados:

query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(first: 1, after: "Y3Vyc29yOnYyOpHOUH8B7g==") {
      nodes {
        createdAt
        number
        title
      }
      pageInfo {
        endCursor
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

Você pode continuar a enviar consultas com o novo valor pageInfo.endCursor retornado na resposta até que não haja mais páginas para percorrer, indicado por pageInfo.hasNextPage retornando false.

Se você especificou o argumento last em vez do first, a última página de resultados será retornada primeiro. Nesse caso, você usará o valor o pageInfo.startCursor e o argumento before para obter a página anterior de resultados. Quando pageInfo.hasPreviousPage tiver retornado false, você terá chegado à última página. Por exemplo:

query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(last: 1, before: "R3Vyc29yOnYyOpHOHcfoOg==") {
      nodes {
        createdAt
        number
        title
      }
      pageInfo {
        startCursor
        hasPreviousPage
      }
    }
  }
}

Próximas etapas

Você pode usar o SDK Octokit do GitHub e o plugin octokit/plugin-paginate-graphql para dar suporte à paginação em seus scripts. Para obter mais informações, consulte "plugin-paginate-graphql.js."