Passer au contenu principal

​
Comment intégrer les points de terminaison de recherche de Publications

Cette page présente plusieurs outils et concepts clés à connaître lorsque vous intégrez les points de terminaison de recherche récente ou de recherche dans l’archive complète à votre système. Nous avons divisé la page en sections suivantes :

​
Outils utiles

Avant d’explorer certains concepts clés, nous vous recommandons d’utiliser l’un des outils ou des exemples de code suivants pour commencer à tester la fonctionnalité de ces points de terminaison.

​
Exemples de code

Vous souhaitez configurer ces points de terminaison avec du code dans votre langage de programmation préféré ? Nous mettons à disposition plusieurs exemples de code que vous pouvez utiliser comme point de départ sur notre page GitHub, notamment un client Python et un client Ruby.

​
Bibliothèques

Profitez de l’une de nos nombreuses bibliothèques tierces de la communauté pour vous aider à démarrer. Vous pouvez trouver une bibliothèque compatible avec les points de terminaison v2 en recherchant la balise de version appropriée.

​
Postman

Postman est un excellent outil pour tester ces points de terminaison. Chaque requête Postman inclut tous les paramètres du point de terminaison concerné afin de vous aider à comprendre rapidement ce qui est disponible. Pour en savoir plus sur nos collections Postman, consultez notre page Utiliser Postman.  

​
Concepts clés

​
Authentification

Tous les points de terminaison de X API v2 exigent que vous authentifiiez vos requêtes à l’aide d’un ensemble d’identifiants, également appelés clés et jetons. Vous pouvez utiliser OAuth 1.0a Contexte utilisateur, OAuth 2.0 App-Only ou OAuth 2.0 Authorization Code with PKCE pour authentifier vos requêtes vers le point de terminaison de recherche récente. Vous devez utiliser OAuth 2.0 App-Only lorsque vous utilisez le point de terminaison de recherche de l’archive complète. OAuth 2.0 App-Only nécessite simplement de transmettre un OAuth 2.0 App Access Token avec votre requête. Vous pouvez soit générer un Jeton d’accès d’App directement depuis une App développeur, soit en générer un en utilisant le point de terminaison POST oauth2/token. OAuth 1.0a Contexte utilisateur exige que vous utilisiez vos clés d’API, des jetons d’accès utilisateur et quelques autres paramètres pour créer un en-tête d’autorisation, que vous transmettrez ensuite avec votre requête. Les jetons d’accès doivent être associés à l’utilisateur pour le compte duquel vous effectuez la requête. Si vous souhaitez générer un ensemble de jetons d’accès pour un autre utilisateur, celui-ci doit autoriser votre App à l’aide du flux OAuth à 3 étapes. Veuillez noter qu’OAuth 1.0a peut être difficile à utiliser. Si vous n’êtes pas familier avec cette méthode d’authentification, nous vous recommandons d’utiliser une bibliothèque, un outil comme Postman ou OAuth 2.0 pour authentifier vos requêtes. Si vous souhaitez demander une Publication ou des métriques privées à partir de ces points de terminaison, vous devrez utiliser OAuth 1.0a Contexte utilisateur ou OAuth 2.0 Authorization Code with PKCE, ce qui garantira que vous disposez des autorisations appropriées de l’utilisateur propriétaire de ce contenu. OAuth 2.0 Authorization Code with PKCE permet un meilleur contrôle de la portée d’une application, ainsi que des flux d’autorisation sur plusieurs appareils. OAuth 2.0 vous permet de choisir des portées fines et spécifiques qui vous confèrent des autorisations précises au nom d’un utilisateur. Pour activer OAuth 2.0 dans votre App, vous devez l’activer dans les paramètres d’authentification de votre App, accessibles dans la section Paramètres de l’App du portail développeur.
Veuillez noterSi vous demandez les champs suivants, OAuth 1.0a Contexte utilisateur ou OAuth 2.0 Authorization Code est requis :
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics

​

Portail développeur, Projets et Apps développeur Pour utiliser n’importe quel point de terminaison de la X API v2, vous devez vous être inscrit à un compte développeur, avoir configuré un Projet dans ce compte et créé une App développeur au sein de ce Projet. Les clés et jetons de cette App développeur fonctionneront avec ces points de terminaison de recherche. Vous pouvez utiliser des clés et jetons d’un Projet avec n’importe quel niveau d’accès pour envoyer des requêtes au point de terminaison de recherche récente. En revanche, vous devrez utiliser un Projet avec un niveau d’accès Pro ou Enterprise pour envoyer des requêtes au point de terminaison de recherche dans l’archive complète. Si vous disposez de l’accès Enterprise, vous aurez accès à des fonctionnalités supplémentaires, notamment des opérateurs supplémentaires et des requêtes de plus grande longueur.  

​
Limites de débit

Chaque jour, des dizaines de milliers de développeurs envoient des requêtes à la X API. Pour gérer ce volume, des limites de débit sont appliquées à chaque point de terminaison afin de plafonner le nombre de requêtes qu’un développeur peut effectuer au nom d’une application ou d’un utilisateur authentifié. Différentes limites de débit s’appliquent à ces points de terminaison selon la méthode d’authentification utilisée. Les limites au niveau de l’application s’appliquent à une application qui effectue des requêtes via OAuth 2.0 App-Only, tandis que la limite au niveau de l’utilisateur s’applique aux requêtes effectuées au nom de l’utilisateur autorisant spécifique via OAuth 1.0a Contexte utilisateur ou OAuth 2.0 Authorization Code with PKCE. Ces deux types de limites sont fondés sur la fréquence des requêtes dans une fenêtre de 15 minutes. Par exemple, une application utilisant OAuth 2.0 App-Only pour effectuer des requêtes vers le point de terminaison de recherche récente peut effectuer 450 requêtes (y compris les requêtes de pagination) sur une période de 15 minutes. Cette même application, dans la même fenêtre de 15 minutes et avec deux utilisateurs authentifiés différents (utilisant OAuth 1.0a Contexte utilisateur ou OAuth 2.0 Authorization Code with PKCE), peut effectuer jusqu’à 180 requêtes (y compris les requêtes de pagination) vers le point de terminaison de recherche récente pour chaque utilisateur authentifié.  

​
Champs et extensions

X API v2 vous permet de sélectionner précisément les données à renvoyer par l’API en utilisant les champs et les extensions. Le paramètre expansions vous permet de développer les objets référencés dans le payload. Par exemple, ce point de terminaison vous permet de demander des objets sondage, lieu, média, et d’autres objets à l’aide du paramètre expansions. Les paramètres fields vous permettent de choisir exactement quels champs, au sein des différents objets de données, vous souhaitez recevoir. Par défaut, l’objet principal Publication renvoyé par ces points de terminaison inclut les champs id et text (en plus de edit_history_tweet_ids pour les Publications créées après le lancement de cette fonctionnalité). Pour recevoir des champs supplémentaires tels que author_id ou public_metrics, vous devez les demander explicitement à l’aide des paramètres fields. Parmi les champs importants à envisager dans votre intégration figurent nos données de sondage, les métriques, les annotations de Publication et le champ conversation ID. Nous avons ajouté à notre dictionnaire de données X API v2 un guide sur la manière d’utiliser conjointement les champs et les extensions.  

​
Statistiques

Les points de terminaison X API v2 vous permettent de demander des statistiques directement à partir des objets renvoyés, à condition d’inclure les champs appropriés dans votre requête. Il existe certaines limitations concernant les statistiques de Publications dont vous devez être conscient, notamment en lien avec la confidentialité des utilisateurs et les champs de réponse suivants :
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
Les champs mentionnés incluent des données de statistiques privées, ce qui signifie que vous devez être autorisé par l’éditeur de la Publication à récupérer ces données en son nom lors de l’utilisation du point de terminaison de recherche récente, et donc que vous devez utiliser OAuth 1.0a Contexte utilisateur. Étant donné que cette méthode d’authentification n’est utilisable qu’avec la recherche récente, vous ne pourrez pas récupérer ces statistiques via le point de terminaison de recherche dans l’archive complète. Par exemple, pour recevoir non_public_metrics pour les Publications de l’utilisateur dont l’id est 1234, vous devrez inclure dans votre requête des Jetons d’accès associés à cet utilisateur. Vous pouvez faire autoriser votre application par des utilisateurs et obtenir un ensemble de Jetons d’accès qui leur sont associés en utilisant le flux OAuth à 3 étapes. Toutes les non_public_metrics, organic_metrics et promoted_metrics ne sont disponibles que pour les Publications créées au cours des 30 derniers jours. Cela signifie que lorsque vous demandez les champs mentionnés, les résultats s’ajustent automatiquement pour n’inclure que des Publications des 30 derniers jours. Si ces champs sont demandés, seules les Publications rédigées par l’utilisateur authentifié seront renvoyées ; toutes les autres Publications renverront un message d’erreur.  

​
Créer des requêtes de recherche

La fonctionnalité clé de ces points de terminaison est l’utilisation d’une requête de recherche unique pour filtrer les Publications qui vous sont renvoyées. Ces requêtes sont constituées d’opérateurs appliqués aux attributs des Publications et des utilisateurs, tels que des mots-clés, des hashtags et des URL. Les opérateurs peuvent être combinés au sein de requêtes à l’aide de logique booléenne et de parenthèses afin d’affiner le comportement de correspondance de la requête. Vous pouvez consulter notre guide sur la création d’une requête pour en savoir plus. Ces points de terminaison utilisent la pagination afin que les réponses soient renvoyées rapidement. Lorsque le nombre de résultats dépasse ce qui peut être envoyé dans une seule réponse (jusqu’à 100 Publications pour la recherche récente et 500 pour la recherche dans l’archive complète), vous devrez paginer. Utilisez le paramètre max_results pour indiquer le nombre de résultats à renvoyer par page, et le paramètre pagination_token pour récupérer la page suivante de résultats. Pour en savoir plus, consultez notre guide de pagination.

​
Plafonds de Publications

Les points de terminaison de recherche de Publications sont limités quant au nombre de Publications qu’ils peuvent renvoyer au cours d’un mois donné, indépendamment de la pagination. Quel que soit le point de terminaison de recherche que vous utilisez, les Publications renvoyées seront comptabilisées dans le plafond de Publications au niveau du Projet Post caps. L’usage est affiché dans le portail développeur, et le « mois » commence à la date de renouvellement de votre abonnement indiquée sur le tableau de bord du portail développeur. Modifications de Publication Les Publications pouvant être modifiées peuvent l’être jusqu’à cinq fois dans les 30 minutes suivant la publication de la Publication originale. Les points de terminaison de recherche fourniront toujours la dernière version de la Publication. Si vous ne demandez que des Publications publiées il y a 30 minutes ou plus, vous recevrez toujours la version finale de la Publication. Toutefois, si vous avez un cas d’usage quasi en temps réel et interrogez des Publications publiées au cours des trente dernières minutes, ces Publications peuvent avoir été modifiées après leur réception. Ces Publications peuvent être réhydratées via la recherche ou le point de terminaison Post Lookup afin de confirmer leur état final. Pour en savoir plus sur le fonctionnement des modifications de Publication, consultez la page Notions fondamentales sur les modifications de Publication.   Étapes suivantes Effectuez votre première requête vers un point de terminaison de recherche de Publications Consultez la liste complète des paramètres, champs et plus encore dans nos pages de référence de l’API Obtenez de l’assistance ou dépannez une erreur