Utilisation de la pagination dans l’API GraphQL

À propos de la pagination

L'API GraphQL de GitHub limite le nombre d'éléments que vous pouvez récupérer en une seule requête afin de protéger les serveurs de GitHub contre les requêtes excessives ou abusives. Lorsque vous utilisez l’API GraphQL, vous devez fournir un argument firstou last sur n’importe quelle connexion. La valeur de ces arguments doit être comprise entre 1 et 100. L’API GraphQL retourne le nombre de connexions spécifiées par l’argument first ou last.

Si les données auxquelles vous accédez ont plus de connexions que le nombre d’éléments spécifiés par l’argument first ou last., la réponse est divisée en « pages » plus petites de la taille spécifiée. Ces pages peuvent être extraites une à la fois jusqu’à ce que l’ensemble du jeu de données ait été récupéré. Chaque page contient le nombre d’éléments spécifiés par l’argument first ou last., sauf s’il s’agit de la dernière page, qui peut contenir un nombre inférieur d’éléments.

Ce guide montre comment demander des pages de résultats supplémentaires pour les réponses paginées, comment changer le nombre de résultats retournés sur chaque page et comment écrire un script pour récupérer plusieurs pages de résultats.

Demande d’une cursor dans votre requête

Lorsque vous utilisez l’API GraphQL, vous utilisez des curseurs pour parcourir un jeu de données paginé. Le curseur représente une position spécifique dans le jeu de données. Vous pouvez obtenir le premier et le dernier curseur d’une page en interrogeant l’objet pageInfo. Par exemple :

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

Dans cet exemple, pageInfo.startCursor donne le curseur pour le premier élément de la page. pageInfo.endCursor donne le curseur pour le dernier élément de la page. pageInfo.hasNextPage et pageInfo.hasPreviousPage indiquent s’il existe une page avant et après la page retournée.

Changement du nombre d’éléments par page

Les arguments first ou last. contrôlent le nombre d’éléments retournés. Le nombre maximal d’éléments que vous pouvez extraire à l’aide de l’argument first ou last est de 100. Vous devrez peut-être demander moins de 100 éléments si votre requête touche un grand nombre de données afin d’éviter d’atteindre une limite de débit ou de Nodes. Pour plus d’informations, consultez « Rate limits and query limits for the GraphQL API ».

Parcourir le jeu de données à l’aide de la pagination

Une fois que vous avez retourné un curseur à partir d’une requête, vous pouvez utiliser le curseur pour demander la page suivante des résultats. Pour ce faire, vous allez utiliser l’argument after ou before et le curseur.

Par exemple, en supposant que la pageInfo.endCursor valeur de l’exemple précédent était Y3Vyc29yOnYyOpHOUH8B7g==, vous pouvez utiliser cette requête pour demander la page suivante des résultats :

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

Vous pouvez continuer à envoyer des requêtes avec la nouvelle valeur pageInfo.endCursor retournée dans la réponse jusqu’à ce qu’il ne reste aucune page à parcourir, indiquée en pageInfo.hasNextPage retournant false.

Si vous avez spécifié l’argument last au lieu de l’argument first, la dernière page de résultats est retournée en premier. Dans ce cas, vous allez utiliser la valeur pageInfo.startCursor et l’argument before pour obtenir la page précédente des résultats. Une fois pageInfo.hasPreviousPage retourné false, vous avez atteint la dernière page. Par exemple :

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

Étapes suivantes

Vous pouvez utiliser le SDK Octokit de GitHub et le plugin octokit/plugin-paginate-graphql pour prendre en charge la pagination dans vos scripts. Pour plus d’informations, consultez plugin-paginate-graphql.js.