Utilisation de la pagination dans l’API GraphQL

Découvrez comment parcourir des ensembles de données à l’aide de la pagination par curseur avec l’API GraphQL.

À propos de la pagination

L’API GraphQL d’ARISE limite le nombre d’éléments que vous pouvez récupérer en une seule requête afin de se prémunir contre les requêtes excessives ou abusives adressées à nos serveurs. Lorsque vous utilisez l’API GraphQL, vous devez fournir un argument first ou last pour chaque requête paginée. La valeur de ces arguments doit être comprise entre 1 et 100. L’API GraphQL renverra le nombre d’éléments spécifié par l’argument first ou last.

Si les données auxquelles vous accédez comportent plus de connexions que le nombre d’éléments spécifié 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 récupérées une par une jusqu’à ce que l’ensemble des données ait été récupéré. Chaque page contient le nombre d’éléments spécifié par l’argument first ou last, sauf s’il s’agit de la dernière page, qui peut contenir un nombre d’éléments inférieur.

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

Tip

Le standard utilisé est le GraphQL Cursor Connections, créé par Relay. Bon nombre de clients GraphQL comprennent cette spécification et proposent des méthodes simplifiées pour itérer sur toutes les pages d’une requête.

Demander un curseur dans votre requête

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

query {
  groups(first: 100, after: null) {
    nodes {
      id
      name
      createdAt
    }
    pageInfo {
      endCursor
      startCursor
      hasNextPage
      hasPreviousPage
    }
  }
}

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

Changer le nombre d’éléments par page

Les arguments first et last déterminent le nombre d’éléments renvoyés. Le nombre maximal d’éléments que vous pouvez récupérer à l’aide de ces arguments est de 100. Si votre requête porte sur un volume important de données, vous devrez peut-être limiter le nombre d’éléments à moins de 100 afin d’éviter d’atteindre une limite de débit ou une limite de nœuds. Pour plus d’informations, consultez la section Limites pour l’API GraphQL.

Parcourir l’ensemble de données à l’aide de la pagination

Une fois que vous avez obtenu un curseur à la suite d’une requête, vous pouvez l’utiliser pour demander la page suivante de résultats. Pour ce faire, utilisez l’argument after ou before ainsi que le curseur.

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

query {
  groups(first: 1, after: "InVybjp1dWlkOjAxOWNmMTJhLTRmMTAtNzExZi04MDRhLWY4ODg3Y2U3ZWRlMSI") {
    nodes {
      id
      name
      createdAt
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Vous pouvez continuer à envoyer des requêtes en utilisant la nouvelle valeur de pageInfo.endCursor renvoyée dans la réponse jusqu’à ce qu’il n’y ait plus de pages à parcourir, ce qui est indiqué par la valeur false renvoyée par pageInfo.hasNextPage.

Important

Le contenu des curseurs doit être considéré comme opaque, il peut changer à tout moment. Il n’est donc pas recommandé de stocker les curseurs sur une longue période. Voir la spécification

Si vous avez spécifié l’argument last au lieu de first, la dernière page de résultats sera renvoyée en premier. Dans ce cas, vous utiliserez la valeur pageInfo.startCursor et l’argument before pour obtenir la page de résultats précédente. Lorsque pageInfo.hasPreviousPage renvoie false, vous avez atteint la dernière page. Par exemple :

query {
  groups(last: 1, after: "InVybjp1dWlkOjAxOWNmMTJhLTRmMTAtNzExZi04MDRhLWY4ODg3Y2U3ZWRlMSI") {
    nodes {
      id
      name
      createdAt
    }
    pageInfo {
      startCursor
      hasPreviousPage
    }
  }
}