Acerca de la paginación
La GraphQL API de GitHub limita el número de elementos que se pueden capturar en una sola solicitud para protegerse frente a solicitudes excesivas o abusivas a los servidores de GitHub. Al usar GraphQL API, debe proporcionar un argumento first o last en cualquier conexión. El valor de estos argumentos debe estar entre 1 y 100. GraphQL API devolverá el número de conexiones especificadas por el argumento first o last.
Si los datos a los que tiene acceso tienen más conexiones que el número de elementos especificados por el argumento first o last, la respuesta se divide en "páginas" más pequeñas del tamaño especificado. Estas páginas se pueden capturar de una en una hasta que se haya recuperado todo el conjunto de datos. Cada página contiene el número de elementos especificados por el argumento first o last, a menos que sea la última página, que puede contener un número inferior de elementos.
En esta guía se describe cómo solicitar más páginas de resultados de respuestas paginadas, cómo cambiar el número de resultados devueltos en cada página y cómo escribir un script para capturar varias páginas de resultados.
Solicitud de un cursor en la consulta
Al usar GraphQL API, se usan cursores para recorrer un conjunto de datos paginado. El cursor representa una posición específica en el conjunto de datos. Puede obtener el primer y último cursor de una página consultando el objeto pageInfo. Por ejemplo:
query($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
pullRequests(first: 100, after: null) {
nodes {
createdAt
number
title
}
pageInfo {
endCursor
startCursor
hasNextPage
hasPreviousPage
}
}
}
}
En este ejemplo, pageInfo.startCursor proporciona el cursor para el primer elemento de la página. pageInfo.endCursor proporciona el cursor para el último elemento de la página. pageInfo.hasNextPage e pageInfo.hasPreviousPage indican si hay una página antes y después de la página que se devolvió.
Modificación del número de elementos por página
Los argumentos first y last controlan cuántos elementos se devuelven. El número máximo de elementos que puede capturar mediante el argumento first o last es 100. Es posible que tenga que solicitar menos de 100 elementos si la consulta toca una gran cantidad de datos para evitar alcanzar un límite de velocidad o un límite de nodos. Para más información, consulta Límites de volumen y límites de nodo para GraphQL API.
Recorrido de un conjunto de datos mediante paginación
Una vez que devuelva un cursor de una consulta, puede usar el cursor para solicitar la siguiente página de resultados. Para ello, usará el argumento after o before y el cursor.
Por ejemplo, suponiendo que el valor pageInfo.endCursor del ejemplo anterior era Y3Vyc29yOnYyOpHOUH8B7g==, puede usar esta consulta para solicitar la siguiente 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
}
}
}
}
Puede seguir enviando consultas con el nuevo valor pageInfo.endCursor devuelto en la respuesta hasta que no quedan páginas por recorrer, indicado por pageInfo.hasNextPage devolviendo false.
Si especificó last en lugar del argumento first, primero se devolverá la última página de resultados. En este caso, usará el valor pageInfo.startCursor y el argumento before para obtener la página anterior de resultados. Una vez que pageInfo.hasPreviousPage devuelve false, ha llegado a la última página. Por ejemplo:
query($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
pullRequests(last: 1, before: "R3Vyc29yOnYyOpHOHcfoOg==") {
nodes {
createdAt
number
title
}
pageInfo {
startCursor
hasPreviousPage
}
}
}
}
Pasos siguientes
Puede usar el SDK de Octokit de GitHub y el complemento octokit/plugin-paginate-graphql para soportar la paginación en los scripts. Para obtener más información, consulta plugin-paginate-graphql.js.