Guide d’intégration

Cette page présente plusieurs outils et concepts clés à connaître lors de l’intégration des endpoints de recherche d’utilisateurs à votre système. Nous avons divisé la page en plusieurs sections :

• Outils utiles
• Concepts clés
• Authentification
• developer portal, Projects, and Apps
• Limites de taux
• Fields and expansions
• Cas limites

​

Outils pratiques

Avant d’aborder certains concepts clés qui vous aideront à intégrer cet endpoint, nous vous recommandons de vous familiariser avec :

​

Postman

Postman est un excellent outil que vous pouvez utiliser pour tester un endpoint. Chaque requête Postman inclut tous les paramètres de chemin et de corps afin de vous aider à comprendre rapidement ce qui est à votre disposition. Pour en savoir plus sur nos collections Postman, veuillez consulter notre page “Utiliser Postman”. 

​

Exemples de code

Vous souhaitez configurer cet endpoint avec du code dans votre langage préféré ? Nous proposons plusieurs exemples de code que vous pouvez utiliser comme point de départ sur notre page GitHub.

​

Bibliothèques tierces

Profitez de l’une des bibliothèques tierces développées par notre communauté pour vous aider à démarrer. Vous pouvez trouver une bibliothèque compatible avec les endpoints v2 en recherchant le tag de version approprié.

​

Concepts clés

​

Authentification

Tous les endpoints X API v2 exigent que les requêtes soient authentifiées avec un ensemble d’identifiants, également appelés clés et jetons. Vous pouvez utiliser le Contexte utilisateur OAuth 1.0a, App only, ou OAuth 2.0 Autorisation par code avec PKCE pour authentifier les requêtes vers ces endpoints.

Contexte utilisateur OAuth 1.0a vous demande d’utiliser vos API Keys, des Access Tokens utilisateur et quelques autres paramètres pour créer un en-tête d’autorisation, que vous transmettrez ensuite avec votre requête. Les Access Tokens doivent être associés à l’utilisateur pour le compte duquel vous effectuez la requête. Si vous souhaitez générer un ensemble d’Access Tokens pour un autre utilisateur, celui-ci doit autoriser votre App via le 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 récupérer un Post ou des métriques privées depuis ces endpoints, vous devrez utiliser le Contexte utilisateur OAuth 1.0a ou OAuth 2.0 Autorisation par code avec PKCE, ce qui garantira que vous disposez des autorisations appropriées de l’utilisateur propriétaire de ce contenu.

App only requiert simplement que vous transmettiez un App only Access Token avec votre requête. Vous pouvez soit générer un App only Access Token directement au sein d’une App développeur, soit en générer un à l’aide de l’endpoint POST oauth2/token.

OAuth 2.0 Autorisation par code avec PKCE permet un meilleur contrôle de la portée d’une application et des flux d’autorisation sur plusieurs appareils. OAuth 2.0 vous permet de choisir des portées spécifiques et granulaires qui vous confèrent des permissions précises pour le compte 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 App settings du developer portal.

Veuillez noter

Si vous demandez les fields suivants, le Contexte utilisateur OAuth 1.0a ou OAuth 2.0 Autorisation par code est requis :

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics

​

developer portal, Projects et Apps développeur

Pour obtenir un ensemble d’identifiants d’authentification compatibles avec les endpoints de la X API v2, vous devez vous inscrire pour obtenir un compte développeur, configurer un Project dans ce compte, puis créer une App développeur dans ce Project. Vous pourrez ensuite retrouver vos clés et jetons dans votre App développeur.   

​

Limites de taux

Chaque jour, plusieurs milliers de développeurs envoient des requêtes à la X API. Pour gérer le volume de ces requêtes, des limites de taux sont appliquées à chaque endpoint, ce qui limite le nombre de requêtes que vous pouvez effectuer au nom de votre App ou d’un utilisateur authentifié.

Les endpoints de recherche d’utilisateurs sont soumis à des limites de taux à la fois au niveau de l’App et au niveau de l’utilisateur. Toutefois, l’endpoint de recherche de l’utilisateur authentifié est limité au niveau de l’utilisateur.

La limite de taux au niveau de l’App signifie que vous, en tant que développeur, ne pouvez effectuer qu’un certain nombre de requêtes vers cet endpoint sur une période donnée depuis une App donnée (définie par les clés et jetons que vous utilisez). La limite de taux au niveau de l’utilisateur signifie que l’utilisateur authentifié pour lequel vous effectuez la requête ne peut exécuter l’opération qu’un certain nombre de fois, et ce, quelle que soit l’App développeur.

Le tableau ci-dessous présente les limites de taux pour chaque endpoint.

Endpoint	Méthode HTTP	Limite de taux / Niveau
/2/users	GET	900 requêtes par 15 minutes / App et utilisateur
/2/users/:id	GET	900 requêtes par 15 minutes / App et utilisateur
/2/users/by	GET	900 requêtes par 15 minutes / App et utilisateur
/2/users/by/username/:username	GET	900 requêtes par 15 minutes / App et utilisateur
/2/users/me	GET	75 requêtes par 15 minutes / Utilisateur

​

Fields et expansions

La X API v2 permet aux utilisateurs de choisir précisément quelles data ils souhaitent récupérer depuis l’API à l’aide d’un ensemble d’outils appelés fields et expansions. Le paramètre expansions vous permet d’inclure les objets référencés dans le payload. Par exemple, cet endpoint vous permet d’utiliser l’expansion pinned_tweet_id.

Le paramètre fields vous permet de sélectionner exactement quels fields au sein des différents objets de data vous souhaitez recevoir. Ces endpoints renvoient principalement des objets utilisateur. Par défaut, l’objet utilisateur renvoie les fields id, name et username. Pour recevoir des fields supplémentaires tels que user.created_at ou user.location, vous devrez les demander explicitement à l’aide d’un paramètre fields. Parmi les fields importants à envisager dans votre intégration figurent nos données de sondage de Post, les métriques, les annotations et les fields d’ID de conversation.

Nous avons ajouté un guide expliquant comment utiliser fields et expansions dans notre X API v2 data dictionary.

​

Cas limites

• Le texte du Post est tronqué pour les Retweets. La solution provisoire à court terme consiste à développer le Post référencé et à récupérer le texte complet via l’expansion. Il s’agit d’un bug que nous corrigerons à l’avenir.