Concepts clés
Cibles et mots-clés sont deux choses différentes
Une cible est un compte que vous surveillez ; vous recevez tout ce qu'il fait, ou seulement les types d'événement que vous choisissez. Un mot-clé est une requête que vous surveillez sur l'ensemble de X ; vous recevez les publications de n'importe qui dès qu'elles y correspondent, sous forme d'événements search.match. Les cibles sont identifiées par leur nom d'utilisateur, les mots-clés par le texte de la requête, et une clé peut en détenir autant qu'elle veut de chaque, dans la limite des plafonds de son offre.
Un compte, c'est son identifiant, pas son nom d'utilisateur
Vous surveillez un compte, identifié par son identifiant X numérique (id d'un Target). Un compte peut changer de nom d'utilisateur (screen_name) ou de nom affiché à tout moment : vous continuez à recevoir ses événements, les suivants portent le nouveau nom dans target.screen_name, et un événement profile.screen_name ou profile.name vous indique le changement. Indexez vos données sur id. Partout où l'API attend un compte, vous pouvez le désigner par son user_id, son nom actuel ou un nom qu'il a eu avant.
Livraison en deux phases : création, puis mise à jour
Certains événements de publication sont livrés en deux trames. La première, op: "create", porte l'essentiel — l'identifiant de la publication, l'auteur et le texte — pour que vous puissiez agir immédiatement. Un instant plus tard, le même identifiant d'événement arrive à nouveau avec op: "update", cette fois avec les médias, l'original cité ou auquel on répond, les compteurs et le reste. Les événements complets dès leur première observation n'ont pas de seconde trame ; GET /v1/meta/event-types indique quels types peuvent en avoir une.
create. Si vous avez besoin de la publication entière, attendez l'update portant le même id. Dans les deux cas, indexez votre stockage sur id et laissez un update ultérieur écraser ce que vous avez conservé. Le type ne change entre les deux trames que d'une seule façon : un premier tweet.create avec kind_final: false peut devenir tweet.quote. Si vous traitez différemment publications originales et citations, classez une telle trame une fois son update arrivé.Au moins une fois, jamais exactement une fois
Chaque compte surveillé est observé par plusieurs chemins indépendants à la fois, de sorte qu'un chemin défaillant ne vous coûte rien. Le premier à signaler un changement donné l'emporte et devient l'événement ; les autres sont enregistrés comme corroboration plutôt que livrés à nouveau. Après une reconnexion, en revanche, vous pouvez voir un événement que vous avez déjà. Dédupliquez sur id.
Position et rejeu
Chaque événement porte un sid — sa position dans notre journal. Conservez le dernier que vous avez traité ; à la reconnexion, passez-le en ?last_id= et nous envoyons tout ce qui le suit avant de reprendre le direct. Le journal conserve 24 heures, et une reconnexion rejoue au plus 5 000 événements. Les cibles ou mots-clés que vous ajoutez pendant qu'un socket est ouvert s'y mettent à circuler sous 30 secondes ; vous n'avez pas besoin de vous reconnecter.