Passer au contenu principal

​
Introduction

La pagination est une fonctionnalité des endpoints de la X API v2 qui renvoient plus de résultats qu’une seule réponse ne peut en contenir. Dans ce cas, les data sont renvoyées sous forme de « pages ». La pagination désigne les méthodes permettant de demander, de manière programmatique, l’ensemble des pages afin de récupérer l’intégralité du jeu de résultats. Tous les endpoints de l’API ne prennent pas en charge la pagination ni ne l’exigent, mais elle est souvent utilisée lorsque les ensembles de résultats sont volumineux.

​
Cas d’utilisation de la pagination

Pour récupérer tous les résultats d’une requête : Utilisez la pagination pour obtenir l’ensemble des données pertinentes liées à une requête et à ses paramètres. Elle est requise lorsqu’il existe plus de résultats correspondants que la valeur de max_results pour une requête. Boucler des requêtes avec des jetons de pagination permet de récupérer tous les résultats. Dès qu’une réponse est renvoyée sans next_token, on peut supposer que tous les résultats ont été parcourus. La pagination ne doit pas être utilisée pour le sondage. Pour obtenir les résultats les plus récents depuis une requête précédente, reportez-vous au sondage avec since_id. Pour parcourir les résultats d’une requête : La pagination offre des options directionnelles pour naviguer dans les résultats d’une requête, à l’aide des valeurs next_token et previous_token renvoyées dans les réponses. Ces jetons peuvent être fournis en tant que pagination_token dans la requête suivante pour passer à la page de résultats suivante ou précédente.

​
Définitions des jetons de pagination

  • next_token - Chaîne opaque renvoyée dans l’objet meta de la réponse pour les endpoints qui prennent en charge la pagination. Indique que d’autres résultats sont disponibles et peut être utilisée comme paramètre pagination_token dans la requête suivante pour retourner la page suivante de résultats. La dernière page de résultats ne comporte pas de next_token.
    • previous_token - Chaîne opaque renvoyée dans l’objet meta de la réponse pour les endpoints qui prennent en charge la pagination. Indique qu’une page précédente de résultats est disponible et peut être utilisée comme paramètre pagination_token dans la requête suivante pour retourner la page précédente de résultats.
    • pagination_token - Paramètre utilisé dans les requêtes de pagination. À renseigner avec la valeur de next_token pour la page suivante de résultats. À renseigner avec la valeur de previous_token pour la page précédente de résultats.

​
Principes fondamentaux de la pagination

  • Les endpoints qui utilisent la pagination renvoient, à la requête initiale, une première page de résultats et fournissent un next_token dans l’objet meta de la réponse JSON si d’autres pages de résultats sont disponibles. Pour récupérer tous les résultats, répétez ce processus jusqu’à ce qu’aucun next_token ne figure plus dans la réponse.
    • Les résultats sont livrés dans l’ordre antéchronologique. C’est valable au sein de chaque page comme sur l’ensemble des pages :
      • Le premier Post de la première réponse sera le plus récent.
      • Le dernier Post de la dernière réponse sera le plus ancien.
    • Le paramètre de requête max_results vous permet de définir le nombre de Posts renvoyés par page. Il existe une valeur par défaut et une valeur maximale pour max_results.
    • Toute implémentation de pagination implique l’extraction de jetons depuis la charge utile de la réponse, pouvant être réutilisés dans des requêtes ultérieures.
    • Dans certaines situations, vous pouvez obtenir moins que max_results par page. Ne supposez pas que le nombre de résultats par page sera toujours égal à la valeur du paramètre max_results.
    • Les meilleures façons d’utiliser la pagination pour obtenir l’exhaustivité des résultats consistent à employer une logique de boucle dans votre code d’intégration ou à utiliser une bibliothèque compatible avec X API v2.

​
Exemple de pagination

Ici, il y a trois pages de résultats, car max_results est fixé à 100 et il existe environ 295 Posts créés par l’utilisateur portant l’id 2244994945 (@XDevelopers) entre le 1ᵉʳ janvier 2019 à 17:00:00 UTC et le 12 décembre à 00:00:00 UTC. Le premier Post de la première page (1337498609819021312) est le plus récent, et le dernier Post de la troisième page de résultats (1082718487011885056) est le plus ancien.

​
Demande initiale

      https://api.x.com/2/users/2244994945/tweets?tweet.fields=created_at&max_results=100&start_time=2019-01-01T17:00:00Z&end_time=2020-12-12T01:00:00Z

​
Tableau des séquences

Première RequêteDeuxième PageTroisième PageQuatrième Page
Paramètres de Requête- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 7140w- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 7140k9- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 71408hi
Réponsejson { "data": [ { "created_at": "2020-12-11T20:44:52.000Z", "id": "1337498609819021312", "text": "Thanks to everyone who tuned in today..." }, ... , { "created_at": "2020-05-06T17:24:31.000Z", "id": "1258085245091368960", "text": "It's now easier to understand Tweet impact..." } ], "meta": { "oldest_id": "1258085245091368960", "newest_id": "1337498609819021312", "result_count": 100, "next_token": "7140w" } } json { "data": [ { "created_at": "2020-04-29T17:01:44.000Z", "id": "1255542797765013504", "text": "Our developer community is full of inspiring ideas..." }, ... , { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549579035496449", "text": "Soon, we'll be releasing tools in..." } ], "meta": { "oldest_id": "1197549579035496449", "newest_id": "1255542797765013504", "result_count": 100, "next_token": "7140k9", "previous_token": "77qp8" } } json { "data": [ { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549578418941952", "text": "We know that some people who receive a large volume of replies may..." }, ... , { "created_at": "2019-01-08T19:19:37.000Z", "id": "1082718487011885056", "text": "Updates to Grid embeds..." } ], "meta": { "oldest_id": "1082718487011885056", "newest_id": "1197549578418941952", "result_count": 95, "next_token": "71408hi", "previous_token": "77qplte" } } json { "meta": { "result_count": 0, "previous_token": "77qpw8l" } }
Actions à Effectuer pour la Requête SuivantePour obtenir la page suivante, récupérez la valeur next_token directement depuis la réponse (7140w) et utilisez-la comme pagination_token pour l’appel de requête suivant.Pour continuer à récupérer tous les résultats : récupérez la valeur next_token directement depuis la réponse (7140k9) et utilisez-la comme pagination_token pour l’appel de requête suivant. Pour revenir à la page précédente : récupérez la valeur previous_token directement depuis la réponse (77qp8) et utilisez-la comme pagination_token pour l’appel de requête suivant.Pour continuer à récupérer tous les résultats : récupérez la valeur next_token directement depuis la réponse (71408hi) et utilisez-la comme pagination_token pour l’appel de requête suivant. Pour revenir à la page précédente : récupérez la valeur previous_token directement depuis la réponse (77qplte) et utilisez-la comme pagination_token pour l’appel de requête suivant.Notez qu’il n’y a pas de next_token, ce qui indique que tous les résultats ont été récupérés. Pour revenir à la page précédente : récupérez la valeur previous_token directement depuis la réponse (77qpw8l) et utilisez-la comme pagination_token pour l’appel de requête suivant.
⌘I