Passer au contenu principal

​
Créer un client pour consommer des données en streaming

Lorsque vous utilisez un endpoint de streaming, il existe quelques bonnes pratiques générales à prendre en compte pour en optimiser l’utilisation.    

​
Conception du client

Lors de la création d’une solution avec l’endpoint de flux filtré, vous aurez besoin d’un client capable de :
  1. Établir une connexion de streaming HTTPS vers l’endpoint de flux filtré.
  2. Envoyer des requêtes POST de manière asynchrone à l’endpoint des règles de flux filtré pour ajouter et supprimer des règles du flux.
  3. Gérer de faibles volumes de données – maintenir la connexion de streaming, détecter les objets Publication et les signaux de keep-alive.
  4. Gérer de forts volumes de données – découpler l’ingestion du flux du traitement supplémentaire à l’aide de processus asynchrones, et s’assurer que les tampons côté client sont régulièrement vidés.
  5. Gérer le suivi de la consommation de volume côté client.
  6. Détecter les déconnexions du flux, évaluer et se reconnecter automatiquement au flux.  

​
Connexion à un endpoint de streaming

Établir une connexion à des endpoints de streaming de X API v2 implique d’effectuer une requête HTTP de très longue durée et d’analyser la réponse de manière incrémentielle. Conceptuellement, vous pouvez voir cela comme le téléchargement d’un fichier infiniment long via HTTP. Une fois la connexion établie, le serveur X enverra des événements de Publication par le biais de cette connexion tant que celle-ci reste ouverte.  

​
Consommation des données

Notez que les champs individuels des objets JSON ne sont pas ordonnés et que tous les champs ne seront pas présents dans toutes les circonstances. De même, les activités distinctes ne sont pas livrées dans un ordre particulier et vous pouvez recevoir des messages en double. Gardez à l’esprit qu’au fil du temps, de nouveaux types de messages peuvent être ajoutés et envoyés via le flux. Ainsi, votre client doit tolérer :
  • Des champs apparaissant dans n’importe quel ordre
  • Des champs inattendus ou manquants
  • Des Publications dans un ordre non trié
  • Des messages en double
  • De nouveaux types de messages arbitraires arrivant sur le flux à tout moment
En plus des données pertinentes des Publications et des paramètres de champs demandés, les types de messages suivants peuvent être transmis sur une connexion de flux. Notez que cette liste peut ne pas être exhaustive — des objets supplémentaires peuvent être introduits dans les flux. Assurez-vous que votre analyseur gère correctement des formats de messages inattendus.  

​
Mise en mémoire tampon

Les endpoints de streaming vous enverront des données dès qu’elles seront disponibles, ce qui peut, dans de nombreux cas, générer des volumes élevés. Si le serveur X ne peut pas écrire immédiatement de nouvelles données dans le flux (par exemple si votre client ne lit pas assez vite, voir gestion des déconnexions pour plus d’informations), il mettra le contenu en mémoire tampon de son côté pour permettre à votre client de rattraper son retard. Cependant, lorsque ce tampon est plein, une déconnexion forcée sera initiée pour fermer la connexion, et les Publications en mémoire tampon seront supprimées et ne seront pas renvoyées. Voir ci-dessous pour plus de détails. Une façon d’identifier les moments où votre app prend du retard est de comparer l’horodatage des Publications reçues avec l’heure actuelle, et de suivre cette différence dans le temps. Même si les accumulations de flux ne peuvent jamais être complètement éliminées en raison de la latence potentielle et des à-coups sur l’Internet public, elles peuvent être largement réduites grâce à une configuration appropriée de votre app. Pour minimiser la survenue de ces accumulations :
  • Assurez-vous que votre client lit le flux suffisamment vite. En général, vous ne devez effectuer aucun traitement réel pendant la lecture du flux. Lisez le flux et déléguez l’activité à un autre thread/processus/stockage de données pour effectuer votre traitement de manière asynchrone.
  • Assurez-vous que votre data center dispose d’une bande passante entrante suffisante pour gérer de grands volumes de données soutenus ainsi que des pics nettement plus importants (par exemple 5 à 10 fois le volume normal). Pour le flux filtré, le volume et la bande passante correspondante nécessaires de votre côté dépendent entièrement des Publications que vos règles capturent.  

​
Suivi d’utilisation et gestion des règles

Étant donné que les attentes des développeurs concernant ce que devrait être un volume de données « normal » pour leurs flux varient, nous n’avons pas de recommandation générale pour un pourcentage spécifique de diminution/augmentation ni pour une période donnée.  Nous vous recommandons de surveiller les volumes de données de votre flux afin de détecter des écarts inattendus. Une diminution du volume de données peut être symptomatique d’un problème différent d’une déconnexion du flux. Dans une telle situation, un flux continuerait de recevoir le signal keep-alive et probablement certaines nouvelles données d’activité. Cependant, une baisse significative du nombre de Publications doit vous amener à rechercher si quelque chose provoque la diminution du volume de données entrantes vers votre application ou votre réseau, et à consulter la page de statut pour toute notification associée. Pour mettre en place une telle surveillance, vous pouvez suivre le nombre de nouvelles Publications que vous vous attendez à voir dans un laps de temps défini. Si le volume de données d’un flux tombe suffisamment en dessous du seuil spécifié et ne se rétablit pas dans une période définie, alors des alertes et notifications doivent être déclenchées. Vous pouvez également surveiller une forte augmentation du volume de données, en particulier si vous êtes en train de modifier des règles dans un flux filtré, ou si un événement se produit et entraîne un pic de l’activité des Publications. Il est important de noter que les Publications livrées via un flux filtré comptent dans le volume mensuel total de Publications, et vous devez suivre et ajuster la consommation afin de l’optimiser. Si le volume est élevé, envisagez d’ajouter un opérateur sample: à chacune de vos règles pour réduire la correspondance de 100 % à sample:50 ou sample:25 lorsque cela est nécessaire. En outre, nous vous encourageons à mettre en place, au sein de votre App, des mécanismes qui avertiront votre équipe si le volume dépasse un seuil prédéfini, et éventuellement à introduire d’autres mesures, telles que la suppression automatisée des règles qui renvoient trop de données, ou la déconnexion complète du flux dans des circonstances extrêmes.  

​
Répondre aux messages système

Signaux de maintien en vie Au moins toutes les 20 secondes, le flux enverra un signal de maintien en vie, ou battement (heartbeat), sous la forme d’un retour chariot \r\n via la connexion ouverte afin d’empêcher votre client d’expirer (timeout). Votre application cliente doit être tolérante à la présence des caractères \r\n dans le flux. Si votre client implémente correctement un délai d’expiration de lecture (read timeout) dans votre bibliothèque HTTP, votre app pourra s’appuyer sur le protocole HTTP et sur votre bibliothèque HTTP pour déclencher un événement si aucune donnée n’est lue pendant cette période, et vous n’aurez pas besoin de surveiller explicitement le caractère \r\n. Cet événement sera généralement une exception levée ou un autre type d’événement selon la bibliothèque HTTP utilisée. Il est fortement recommandé d’entourer vos méthodes HTTP de gestionnaires d’erreurs/événements afin de détecter ces délais d’expiration. En cas de délai d’expiration, votre application doit essayer de se reconnecter. Messages d’erreur Les endpoints de streaming v2 peuvent également envoyer, dans le flux, des messages d’erreur. Vous trouverez ci-dessous le format de base de ces messages, ainsi que quelques exemples. Veuillez noter que les messages envoyés sont susceptibles d’évoluer et que de nouveaux messages peuvent être introduits. Les applications clientes doivent être tolérantes aux modifications des charges utiles des messages système. Notez que les messages d’erreur contiendront un lien vers la documentation décrivant comment résoudre le problème. Format des messages : 
	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "Ce flux a été déconnecté en amont pour des raisons opérationnelles.",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}
Notez que les messages d’erreur indiquant une déconnexion forcée due à un tampon plein peuvent ne jamais parvenir à votre client si l’engorgement ayant provoqué cette déconnexion forcée l’en empêche. Par conséquent, votre App ne doit pas compter sur ces messages pour déclencher une reconnexion.