Pagination

​

Pagination de la recherche récente

​

Introduction

Les requêtes de recherche correspondent généralement à plus de Publications qu’il n’est possible d’en renvoyer dans une seule réponse d’API. Dans ce cas, les données sont renvoyées sous la forme d’une série de « pages ». La pagination désigne les méthodes permettant de demander l’ensemble des pages afin de récupérer l’intégralité du jeu de données.

Voici les éléments de base de la pagination pour la recherche récente :

• Les points de terminaison de recherche récente répondent à une requête avec au moins une page et fournissent un next_token dans leur réponse JSON si des pages supplémentaires sont disponibles. Pour recevoir des Publications correspondantes, ce processus peut être répété jusqu’à ce qu’aucun token ne soit inclus dans la réponse.

• Le next_token n’expire pas. Plusieurs requêtes utilisant la même valeur de next_token recevront les mêmes résultats, quel que soit le moment où la requête est effectuée.

• Les Publications sont renvoyées dans l’ordre chronologique inverse, dans le fuseau horaire UTC. Cela est valable au sein de chaque page, ainsi qu’entre plusieurs pages :

  • La première Publication de la première réponse sera la plus récente correspondant à votre requête.
  • La dernière Publication de la dernière réponse sera la plus ancienne correspondant à votre requête.

• Le paramètre de requête max_results vous permet de configurer le nombre de Publications renvoyées par réponse. La valeur par défaut est de 10 Publications, avec un maximum de 100. 

• Toute implémentation de pagination impliquera d’analyser les next_tokens dans la charge utile de la réponse, puis de les inclure dans la requête de recherche de « page suivante ». Voir ci‑dessous pour plus de détails sur la façon de construire ces requêtes de « page suivante ».  

Le point de terminaison de recherche récente a été conçu pour prendre en charge deux modèles d’utilisation fondamentaux :

• Get historical - Demander les Publications correspondant à une période donnée. Il s’agit généralement de requêtes ponctuelles utilisées pour la recherche historique. Les requêtes de recherche peuvent être basées sur les paramètres de requête start_time et end_time. Le point de terminaison de recherche récente répond avec des Publications renvoyées dans l’ordre chronologique inverse, en commençant par la Publication correspondante la plus récente. 

• Polling - Demander les Publications correspondantes qui ont été publiées depuis la dernière Publication reçue. Ces cas d’usage ont souvent un objectif quasi temps réel et se caractérisent par des requêtes fréquentes, afin de « surveiller » l’apparition de nouvelles Publications d’intérêt. Le point de terminaison de recherche récente fournit le paramètre de requête since_id pour prendre en charge le modèle d’« interrogation régulière ». Pour faciliter la navigation à l’aide des id de Publication, le paramètre de requête until_id est également disponible.  

Nous allons maintenant aborder le mode historique. Il s’agit du mode par défaut du point de terminaison de recherche récente et il illustre les principes fondamentaux de la pagination. Nous verrons ensuite des exemples de cas d’usage d’interrogation régulière. Lorsque l’interrogation régulière déclenche la pagination, une étape supplémentaire est nécessaire pour gérer les requêtes de recherche.  

​

Récupération de données historiques

Cette section décrit comment vous pouvez récupérer des Publications sur une période d’intérêt (actuellement limitée aux sept derniers jours) à l’aide des paramètres de requête start_time et end_time. Les requêtes historiques sont généralement des requêtes ponctuelles utilisées pour la recherche et d’analyse. 

Effectuer des requêtes sur un intervalle de temps donné correspond au mode par défaut de l’endpoint recent search. Si une requête de recherche ne spécifie pas de paramètre de requête start_time, end_time ou since_id, end_time sera défini par défaut sur « now » (en réalité 30 secondes avant l’heure de la requête) et start_time sera défini par défaut sur sept jours auparavant.

L’endpoint répondra avec la première « page » de Publications en ordre antichronologique, en commençant par la Publication la plus récente. Le corps JSON de la réponse inclura également un next_token s’il existe des pages de données supplémentaires. Pour collecter l’ensemble des Publications correspondantes, quel que soit le nombre de pages, vous devez effectuer des requêtes jusqu’à ce qu’aucun next_token ne soit fourni. 

Par exemple, voici une requête initiale pour des Publications contenant le mot-clé snow au cours de la dernière semaine :

https://api.x.com/2/tweets/search/recent?query=snow

La réponse inclut les 10 Publications les plus récentes, ainsi que ces attributs « meta » dans la réponse JSON :

"meta": {
        "newest_id": "1204860593741553664",
        "oldest_id": "1204860580630278147",
        "next_token": "b26v89c19zqg8o3fobd8v73egzbdt3qao235oql",
        "result_count": 10
    }

Pour récupérer les 10 Publications suivantes, ce next_token est ajouté à la requête d’origine. La requête serait :

https://api.x.com/2/tweets/search/recent?query=snow&next_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql

Le processus qui consiste à rechercher un next_token et à l’inclure dans une requête ultérieure peut être répété jusqu’à ce que toutes les Publications (ou un certain nombre de Publications) aient été collectées, ou jusqu’à ce qu’un nombre spécifié de requêtes ait été effectué. Si la fidélité des données (collecter toutes les correspondances de votre requête) est essentielle pour votre cas d’utilisation, un simple schéma « répéter jusqu’à ce que request.next_token soit nul » suffira.

​

Cas d’usage de scrutation et d’écoute

Cette section décrit comment vous pouvez récupérer des Publications récentes en interrogeant de manière répétée l’endpoint de recherche récente avec le paramètre de requête since_id. 

Dans les cas d’usage de scrutation, des requêtes du type « de nouvelles Publications intéressantes ? » sont effectuées de manière continue et fréquente. Contrairement aux cas d’usage historiques, qui basent les requêtes sur le temps, les cas d’usage de scrutation reposent généralement sur les ID de Publication.

L’élément central du schéma de scrutation est que chaque nouvelle Publication possède un ID unique qui est « émis » par la plateforme X généralement dans l’ordre croissant. Si une Publication a un ID inférieur à une autre, cela signifie qu’elle a été publiée plus tôt.

L’endpoint de recherche récente prend en charge la navigation dans l’archive des Publications par ID de Publication. Les réponses de l’endpoint incluent les ID de Publication oldest_id et newest_id. En mode scrutation, les requêtes sont effectuées avec since_id défini sur l’ID le plus grand/le plus récent reçu jusqu’à présent. 

Par exemple, supposons qu’une requête pour de nouvelles Publications à propos de la neige soit effectuée toutes les cinq minutes, et que la dernière Publication reçue ait un ID de Publication de 10000. Au moment de scruter, la requête ressemble à :

https://api.x.com/2/tweets/search/recent?query=snow&since_id=10000

Ensuite, disons que sept Publications ont été publiées depuis notre dernière requête. Comme elles tiennent toutes sur une seule « page » de données, il n’y a pas de next_token. La réponse fournit l’ID de Publication de la Publication la plus récente :

"meta": {
        "newest_id": "12000",
        "oldest_id": "10005",
        "result_count": 7
    }

Pour effectuer la prochaine requête de polling, cette valeur newest_id est utilisée pour définir le prochain paramètre since_id :

https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000

Lorsqu’il y a davantage de données disponibles et que des next tokens sont fournis, seule la valeur newest_id de la première page de résultats est nécessaire. Chaque page de données inclura les valeurs newest_id et oldest_id, mais la valeur fournie dans la première page est la seule nécessaire pour la prochaine requête de polling planifiée régulièrement. Ainsi, si vous implémentez un modèle de polling ou si vous recherchez des Publications par plage d’ID, la logique de pagination est légèrement plus compliquée. 

Supposons maintenant qu’il y ait 18 Publications supplémentaires correspondantes. L’endpoint renverrait cette réponse initiale avec une page de données complète et un next_token pour demander la page suivante de données pour cette période de cinq minutes. Elle inclurait également l’ID de Publication le plus récent nécessaire pour le prochain intervalle de polling dans cinq minutes.

"meta": {
        "newest_id": "13800",
        "oldest_id": "12500",
        "next_token": "fnsih9chihsnkjbvkjbsc",
        "result_count": 10
    }

Pour collecter toutes les données correspondant à cette période de cinq minutes, incluez le next_token dans votre prochaine requête, avec la même valeur de since_id que pour la requête précédente.

https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000&next_token=fnsih9chihsnkjbvkjbsc

"meta": {
        "newest_id": "12300",
        "oldest_id": "12010",
        "result_count": 8
    }

Cette deuxième réponse renvoie les huit Publications restantes, sans next_token. Notez que nous ne mettons pas à jour la valeur de newest_id (12300) et que nous basons plutôt notre prochaine requête since_id sur la valeur de newest_id de la première réponse :

https://api.x.com/2/tweets/search/recent?query=snow&since_id=13800