Passer au contenu principal

​
Comment intégrer les endpoints Timelines

Cette page présente plusieurs outils et concepts clés à connaître pour intégrer les endpoints Timelines dans votre système. Nous avons réparti le contenu en sections comme suit :

​
Outils pratiques

Avant d’aborder quelques concepts clés, nous vous recommandons d’utiliser l’un des outils ou des exemples de code ci-dessous pour commencer à tester la fonctionnalité de ces endpoints. Exemples de code Vous souhaitez configurer ces endpoints avec du code dans votre langage de programmation préféré ? Nous proposons plusieurs exemples de code que vous pouvez utiliser comme point de départ sur notre page GitHub. Bibliothèques Tirez parti de nos nombreuses bibliothèques tierces de la communauté pour vous aider à démarrer. Vous pouvez trouver une bibliothèque compatible avec les endpoints v2 en recherchant le tag de version approprié. Postman Postman est un excellent outil pour tester ces endpoints. Chaque requête Postman inclut tous les paramètres de chemin et de corps, afin de vous aider à comprendre rapidement ce qui est disponible. Pour en savoir plus sur nos collections Postman, veuillez consulter notre page Utiliser Postman.

​
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 soit le Contexte utilisateur OAuth 1.0a, soit OAuth 2.0 Autorisation par code avec PKCE pour authentifier les requêtes vers ces endpoints. Vous pouvez utiliser OAuth 2.0 App-Only pour la timeline des Posts d’un utilisateur et la timeline des mentions d’un utilisateur. Contexte utilisateur OAuth 1.0a vous oblige à 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 en utilisant 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 d’utiliser 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 soit le Contexte utilisateur OAuth 1.0a, soit 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. OAuth 2.0 App-Only exige simplement que vous transmettiez un App Access Token OAuth 2.0 avec votre requête. Vous pouvez soit générer un App Access Token directement au sein d’une App développeur, soit en générer un en utilisant l’endpoint POST oauth2/token. Vous pouvez l’utiliser pour la timeline des Posts d’un utilisateur ou la timeline des mentions d’un utilisateur. OAuth 2.0 Autorisation par code avec PKCE permet un meilleur contrôle du périmètre d’une application et des flux d’autorisation sur plusieurs appareils. OAuth 2.0 vous permet de choisir des périmètres précis et granulaires qui vous confèrent des autorisations spécifiques 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, disponibles dans la section des paramètres du developer portal.
Veuillez noterSi 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
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
Developer portal, Projects et Apps développeur Pour utiliser tout endpoint X API v2, vous devez créer un compte développeur, configurer un Project au sein de ce compte, et créer une App développeur dans ce Project. Vos clés et jetons au sein de cette App développeur fonctionneront pour ces endpoints de timelines. Limites de taux Chaque jour, de très nombreux développeurs effectuent des requêtes vers la X API. Pour aider à gérer le volume, des limites de taux sont appliquées à chaque endpoint afin de limiter le nombre de requêtes que chaque développeur peut effectuer au nom d’une App ou d’un utilisateur authentifié. Différentes limites de taux s’appliquent à ces endpoints selon la méthode d’authentification utilisée. Les limites de taux au niveau de l’App s’appliquent à une App effectuant des requêtes via OAuth 2.0 App-Only, tandis que la limite de taux au niveau de l’utilisateur s’applique aux requêtes effectuées au nom de l’utilisateur autorisant spécifique via le Contexte utilisateur OAuth 1.0a. Ces deux limites de taux sont basées sur la fréquence des requêtes dans une fenêtre de 15 minutes. Par exemple, une App utilisant l’authentification OAuth 2.0 App-Only pour ces deux endpoints de timelines peut effectuer 1500 requêtes (y compris les requêtes de pagination) vers la timeline des Posts de l’utilisateur, et 450 requêtes (y compris les requêtes de pagination) vers la timeline des mentions de l’utilisateur sur une période de 15 minutes. La même App, sur la même période de 15 minutes, avec deux utilisateurs autorisés différents (utilisant le Contexte utilisateur OAuth 1.0a) peut effectuer 900 requêtes (y compris les requêtes de pagination) vers la timeline des Posts de l’utilisateur, et 180 requêtes (y compris les requêtes de pagination) vers la timeline des mentions de l’utilisateur pour chaque utilisateur authentifié. La timeline d’accueil en ordre antichronologique a une limite de taux par utilisateur de 180 requêtes par fenêtre de 15 minutes. Avec cet endpoint, vous pouvez renvoyer chaque Post créé sur une timeline au cours des 7 derniers jours ainsi que les 800 plus récents, quelle que soit la date de création. Fields and expansions La X API v2 vous permet de sélectionner exactement quelles données vous souhaitez recevoir de l’API en utilisant les fields et les expansions. Le paramètre expansions vous permet d’inclure les objets référencés dans la charge utile. Par exemple, cet endpoint vous permet de demander des objets de type sondage, lieu, média et d’autres objets à l’aide du paramètre expansions. Le paramètre fields vous permet de sélectionner précisément quels fields au sein des différents objets de données vous souhaitez recevoir. Par défaut, l’Objet Post principal renvoyé par ces endpoints inclut les fields id et text. Pour recevoir des fields supplémentaires tels que author_id ou public_metrics, vous devrez explicitement les demander à l’aide des paramètres fields. Certains fields importants que vous pourriez envisager d’utiliser dans votre intégration sont nos données de sondage, les métriques, les annotations de Post et les fields conversation ID. Nous avons ajouté à notre dictionnaire de données X API v2 un guide sur comment utiliser conjointement les fields et expansions. Métriques de Post Les endpoints de la X API v2 vous permettent de demander des métriques de Post directement à partir de l’Objet Post renvoyé, à condition d’inclure les fields appropriés dans votre requête. Il existe certaines limitations concernant les métriques de Post dont vous devez être conscient, notamment en lien avec la confidentialité des utilisateurs et les fields 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 fields indiqués incluent des métriques privées, ce qui signifie que vous devez être autorisé par l’éditeur du Post à récupérer ces données en leur nom lorsque vous utilisez l’endpoint de la timeline des Posts de l’utilisateur, ce qui implique que vous devez utiliser OAuth 1.0a User Context ou OAuth 2.0 Authorization Code Flow with PKCE. Par exemple, afin de recevoir non_public_metrics pour la timeline des Posts de l’utilisateur avec l’ID utilisateur 1234, vous devrez inclure des access tokens associés à cet utilisateur dans votre requête. Vous pouvez faire autoriser votre App par des utilisateurs et recevoir un ensemble d’access tokens qui leur sont associés en utilisant le flux OAuth à 3 étapes. Si vous utilisez la timeline des mentions de l’utilisateur, les fields indiqués ne seront pas disponibles à moins que l’auteur de la mention n’ait autorisé votre App à accéder à ses métriques privées et que vous utilisiez les access tokens de cet utilisateur lors de la requête avec le Contexte utilisateur OAuth 1.0a. Tous les non_public_metrics, organic_metrics et promoted_metrics ne sont disponibles que pour les Posts créés au cours des 30 derniers jours. Cela signifie que lorsque vous demandez les fields indiqués, les résultats s’ajustent automatiquement pour n’inclure que les Posts des 30 derniers jours. Si ces fields sont demandés, seuls les Posts rédigés par l’utilisateur authentifié seront renvoyés ; tous les autres Posts renverront un message d’erreur. Pagination Ces endpoints utilisent la pagination afin que les réponses soient renvoyées rapidement. Dans les cas où il y a plus de résultats que ce qui peut être envoyé dans une seule réponse (jusqu’à 100 Posts pour les endpoints de timelines), vous devrez paginer. Utilisez le paramètre max_results pour indiquer combien de résultats seront renvoyés par page et le paramètre pagination_token pour renvoyer la page suivante de résultats. Vous pouvez en savoir plus en consultant notre guide de pagination. Filtrage des résultats Ces endpoints incluent plusieurs paramètres que vous pouvez utiliser pour filtrer les résultats. En utilisant start_date et end_date, vous pouvez restreindre les résultats à une période spécifique. Si vous préférez utiliser des ID de Post pour sélectionner un ensemble précis de Posts, vous pouvez utiliser since_id et until_id. La timeline des Posts d’utilisateur propose également un paramètre exclude qui peut retirer les Retweets et les réponses de vos résultats.  Post caps et volume de Posts renvoyés Les endpoints de timeline des Posts d’utilisateur et de timeline des mentions d’utilisateur sont limités quant au nombre de Posts qu’ils peuvent renvoyer sur un mois donné. L’endpoint de la timeline d’accueil antichronologique n’est pas soumis à cette limitation. Quel que soit l’endpoint de timeline que vous utilisez, les Posts renvoyés seront comptabilisés dans les Post caps au niveau du Project. L’utilisation est affichée dans le developer portal, et le « mois » commence à la date de renouvellement de votre abonnement indiquée sur le developer portal dashboard.  L’endpoint de la timeline des Posts d’utilisateur ne renverra que les 3 200 Posts les plus récents publiés sur la timeline d’un utilisateur. Si vous définissez start_time et end_time sur une période incluant des Posts au-delà des 3 200 plus récents, vous recevrez une réponse réussie, mais aucun Post. Il est également important de noter que, si vous passez excludes=replies avec vos requêtes de timeline des Posts d’utilisateur, seuls les 800 Posts les plus récents seront renvoyés. L’endpoint de la timeline des mentions d’utilisateur ne renverra que les 800 mentions de Post les plus récentes. L’endpoint de la timeline d’accueil antichronologique renvoie les 3 200 derniers Posts. Modifications de Post Les Posts éligibles aux modifications peuvent être modifiés jusqu’à cinq fois dans les 30 minutes suivant la publication du Post initial. Les endpoints de recherche fourniront toujours la dernière version du Post. Si vous ne demandez que des Posts publiés il y a 30 minutes ou plus, vous recevrez toujours la version finale du Post. Cependant, si vous avez un cas d’usage quasi temps réel et interrogez des Posts publiés au cours des trente dernières minutes, ces Posts peuvent avoir été modifiés après leur réception. Ces Posts peuvent être réhydratés avec la recherche ou l’endpoint Post Lookup pour confirmer leur état final. Pour en savoir plus sur le fonctionnement des modifications de Post, consultez la page Edit Posts fundamentals.   Cas limites
  • Lors de la demande de métriques non publiques sur l’endpoint de la timeline des Posts d’utilisateur pour des Posts datant de plus de 30 jours, vous pouvez voir un next_token dans la réponse avec un nombre de résultats de 0. Pour éviter ce problème, assurez-vous que la période demandée avec le paramètre non_public_metrics se situe dans les 30 jours les plus récents. De plus, la valeur minimale de max_results doit être 10. Ces mesures peuvent aider à éviter ce scénario, mais cela peut tout de même se produire.
  • Demander des métriques promues pour des Posts qui n’ont pas été promus renvoie une réponse vide, au lieu de data de Post. Notre équipe travaille actuellement à la résolution de ce problème.
  • Pour un Retweet qui contient un texte de Post supérieur à 140 caractères, le champ text sera tronqué au lieu de renvoyer le texte complet du Post. La solution de contournement à court terme consiste à développer le Post référencé et à récupérer le texte complet depuis l’expansion. Il s’agit d’un bug que nous corrigerons à l’avenir.
Étapes suivantes [Effectuez votre première requête vers un endpoint Timelines]/x-api/posts/timelines#getting-started-with-reverse-chronological-home-timeline “Effectuez votre première requête vers un endpoint Timelines”) Consultez la liste complète des paramètres, fields et plus encore dans nos pages de référence de l’API Obtenez de l’aide ou dépannez une erreur
⌘I