v1 vers v2

Standard v1.1 par rapport à X API v2

Si vous avez déjà travaillé avec le endpoint v1.1 statuses/filter, ce guide peut vous aider à comprendre les similarités et les différences entre les endpoints de flux filtré standard et ceux de X API v2.

• Similarités
  • Paramètres de requête et opérateurs
  • Prise en charge de l’historique de modification des Publications et des métadonnées
• Différences
  • URL des endpoints
  • Nécessité d’une App et d’un Project
  • Méthode d’authentification
  • Volume de règles et flux persistant
  • Format des données de réponse
  • Paramètres de requête
  • Disponibilité des fonctionnalités de reprise et de redondance
  • Opérateurs de requête

Similarités

Paramètres de requête et opérateurs

L’endpoint standard v1.1 statuses/filter propose quelques paramètres pouvant être transmis avec la requête pour filtrer le flux. Avec le flux filtré v2, vous utilisez à la place un ensemble d’opérateurs qui peuvent être combinés à l’aide de logique booléenne pour filtrer les Publications souhaitées. Les opérateurs disponibles incluent certains remplacements directs des paramètres standard v1.1 existants. 

Les paramètres de requête standard v1.1 suivants ont des opérateurs équivalents dans X API v2 :  

Standard	X API v2
follow - Une liste d’identifiants d’utilisateurs séparés par des virgules, indiquant les utilisateurs dont les Publications doivent être transmises dans le flux.	De nombreux opérateurs peuvent vous aider à trouver des Publications liées à des utilisateurs spécifiques : * @ * from: * to: * etc.
track - Une liste de phrases séparées par des virgules qui seront utilisées pour déterminer quelles Publications seront transmises dans le flux.	De nombreux opérateurs peuvent vous aider à trouver des Publications liées à des mots‑clés spécifiques : * keyword * “exact phrase match” * # * etc.

Prise en charge de l’historique d’édition des Publications et des métadonnées

Les deux versions fournissent des métadonnées qui décrivent l’historique des modifications. Consultez les Références de l’API de flux filtré et la page Principes de l’édition de Publications pour plus de détails. 

Différences

URLs des endpoints

• Endpoints standard v1.1 :
  • https://stream.x.com/1.1/statuses/filter.json
• Endpoint X API v2 :
  • https://api.x.com/2/tweets/search/stream
  • https://api.x.com/2/tweets/search/stream/rule

Exigences pour les Apps et les Projets

Les endpoints X API v2 exigent que vous utilisiez des identifiants issus d’une App développeur qui est associée à un Project lorsque vous authentifiez vos requêtes. Tous les endpoints X API v1.1 peuvent utiliser des identifiants provenant soit d’Apps autonomes, soit d’Apps associées à un Project.

Méthode d’authentification

L’endpoint standard prend en charge le contexte utilisateur OAuth 1.0a, alors que les endpoints de flux filtré X API v2 prennent en charge OAuth 2.0 App-Only (également appelé authentification « Application-only »). Pour effectuer des requêtes vers la version X API v2, vous devez utiliser un App Access Token pour authentifier vos requêtes.

Si vous n’avez plus l’App Access Token qui vous a été présenté lorsque vous avez créé votre App et votre app dans la Console de développement, vous pouvez en générer un nouveau en accédant à la page « Keys and tokens » de votre app dans la Console de développement. Si vous souhaitez générer un App Access Token par programmation, consultez ce guide OAuth 2.0 App-Only. 

Volume de règles et flux persistant

L’endpoint standard v1.1 prend en charge une seule règle pour filtrer la connexion de streaming. Pour modifier la règle, vous devez déconnecter le flux et soumettre une nouvelle requête avec les règles de filtrage révisées transmises en tant que paramètres. 

L’endpoint de flux filtré X API v2 vous permet d’appliquer plusieurs règles à un seul flux, ainsi que d’ajouter et de supprimer des règles de votre flux tout en maintenant la connexion de streaming. 

Format des données de réponse

L’une des plus grandes différences entre les versions d’endpoint standard v1.1 et X API v2 est la manière dont vous sélectionnez les champs retournés dans votre charge utile.

Pour les endpoints standard, vous recevez de nombreux champs de réponse par défaut, puis vous avez la possibilité d’utiliser des paramètres pour identifier quels champs ou ensembles de champs doivent être renvoyés dans la charge utile.

La version X API v2 ne renvoie par défaut que les champs id et text de la Publication. Pour demander des champs ou des objets supplémentaires, vous devrez utiliser les paramètres fields et expansions. Tous les champs de Publication que vous demandez à partir de ces endpoints seront renvoyés dans l’objet Publication principal. Tous les objets et champs étendus relatifs aux utilisateurs, médias, sondages ou lieux seront renvoyés dans un objet includes au sein de votre réponse. Vous pouvez ensuite faire correspondre tous les objets étendus à l’objet Publication en faisant correspondre les identifiants présents à la fois dans la Publication et dans l’objet étendu. 

Nous vous encourageons à en savoir plus sur ces nouveaux paramètres dans leurs guides respectifs, ou en lisant notre guide sur comment utiliser les champs et les expansions. 

Nous avons également préparé un guide de migration de format de données qui peut vous aider à faire correspondre les champs standard v1.1 aux nouveaux champs v2. Ce guide vous indiquera également le paramètre d’expansion et de champ spécifique que vous devrez transmettre avec votre requête v2 pour renvoyer des champs précis.   

En plus des changements concernant la façon dont vous demandez certains champs, X API v2 introduit également de nouveaux modèles JSON pour les objets renvoyés par les API, y compris les objets Publication et user.

• Au niveau racine JSON, les endpoints standard renvoient les objets Publication dans un tableau statuses, tandis que X API v2 renvoie un tableau data. 
• Au lieu de faire référence aux « statuses » Retweeted et Quoted, le JSON X API v2 fait référence aux Tweets Retweeted et Quoted. De nombreux champs hérités et obsolètes, tels que contributors et user.translator_type, sont supprimés. 
• Au lieu d’utiliser à la fois favorites (dans l’objet Publication) et favourites (dans l’objet user), X API v2 utilise le terme like. 
• X adopte la convention selon laquelle les valeurs JSON sans valeur (par exemple null) ne sont pas écrites dans la charge utile. Les attributs de Publication et de user ne sont inclus que s’ils ont des valeurs non nulles.   

Nous avons également introduit un nouveau jeu de champs dans l’objet Publication, notamment les éléments suivants :

• Un champ conversation_id
• Deux nouveaux champs annotations, notamment context et entities
• Plusieurs nouveaux champs metrics
• Un nouveau champ reply_setting, qui indique qui peut répondre à une Publication donnée

Paramètres de requête

Il existe également un ensemble de paramètres standard de requête filtered stream non pris en charge dans X API v2 :

Paramètre standard v1.1	Détails
locations - Une liste de paires longitude,latitude séparées par des virgules qui spécifient un ensemble de boîtes englobantes pour filtrer les Publications.	Nous n’avons pas encore publié d’opérateurs basés sur la localisation pour X API v2.
Delimited	Avec l’endpoint v1.1, définir cette valeur sur la longueur de la chaîne indique que les statuts doivent être délimités dans le flux, afin que les clients sachent combien d’octets lire avant la fin du message de statut. Cette fonctionnalité n’est pas disponible avec X API v2.
Stall_warnings	Avec l’endpoint v1.1, définir ce paramètre sur true entraîne la livraison de messages périodiques si le client risque d’être déconnecté. Avec X API v2, les avertissements de blocage sont envoyés par défaut, avec une nouvelle ligne envoyée périodiquement.

Disponibilité des fonctionnalités de reprise et de redondance

La version X API v2 de filtered stream introduit des fonctionnalités de reprise et de redondance qui peuvent vous aider à maximiser la disponibilité du streaming, ainsi qu’à récupérer les Publications qui auraient pu être manquées en raison d’une déconnexion ayant duré cinq minutes ou moins.

Les connexions redondantes vous permettent de vous connecter à un flux donné jusqu’à deux fois, ce qui peut aider à garantir que vous maintenez une connexion au flux en permanence, même si l’une de vos connexions échoue. 

Le paramètre backfill_minutes peut être utilisé pour récupérer jusqu’à cinq minutes de données manquées. 

Ces deux fonctionnalités ne sont disponibles que via l’Academic Research access. Vous pouvez en savoir plus sur cette fonctionnalité dans notre guide d’intégration sur les fonctionnalités de reprise et de redondance. 

Nouveaux opérateurs de requête

X API v2 introduit de nouveaux opérateurs pour prendre en charge deux nouvelles fonctionnalités : 

• Conversation IDs - Au fur et à mesure que les conversations se déroulent sur X, un ID de conversation sera disponible pour marquer les Publications qui font partie de la conversation. Toutes les Publications de la conversation auront leur conversation_id défini sur l’id de la Publication qui l’a démarrée. 
  • conversation_id :
• X Annotations fournissent des informations contextuelles sur les Publications et incluent des annotations d’entité et de contexte. Les entités sont composées de personnes, de lieux, de produits et d’organisations. Les contextes sont des domaines, ou des sujets, auxquels les entités mises en avant appartiennent. Par exemple, les personnes mentionnées dans une Publication peuvent avoir un contexte qui indique si elles sont athlètes, acteurs ou politiciens.
  • context : - correspond aux Publications qui ont été annotées avec un contexte d’intérêt.
  • entity : - correspond aux Publications qui ont été annotées avec une entité d’intérêt.

---

Exemples de code

Ajouter une règle au flux filtré (v2)

cURL

shellscript

curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"add": [{"value": "cat has:images", "tag": "cats with images"}]}'

Se connecter au flux filtré (v2)

cURL

shellscript

curl "https://api.x.com/2/tweets/search/stream?tweet.fields=created_at,author_id" \
  -H "Authorization: Bearer $BEARER_TOKEN"