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."