Passer au contenu principal
Cet endpoint a été mis à jour pour inclure les métadonnées d’édition de Post. Pour en savoir plus sur ces métadonnées, consultez la page des fondamentaux “Modifier des Posts”.

​
Decahose stream

Enterprise Ceci est une API Enterprise disponible uniquement dans nos niveaux d’accès gérés. Pour utiliser cette API, vous devez d’abord créer un compte avec notre équipe commerciale Enterprise. En savoir plus Decahose fournit un échantillon aléatoire de 10 % du Firehose X en temps réel via une connexion de stream. Cela est réalisé au moyen d’un algorithme d’échantillonnage en temps réel qui sélectionne aléatoirement les data, tout en permettant une livraison à faible latence des data au fur et à mesure qu’elles sont envoyées dans le firehose par X. Vous trouverez ci-dessous certaines des fonctionnalités disponibles avec Decahose :
  • URL étendues et enrichies : - déroule entièrement les URL raccourcies et fournit des metadata supplémentaires (titre et description de page)
  • Partitionnement du stream - 2 partitions, chacune contenant 50 % du volume du stream Decahose
  • Fiabilité améliorée - diversité géographique des systèmes backend
Remarque : ces data sont livrées en bloc et ne prennent pas en charge de filtrage supplémentaire (par exemple, par mots-clés). ENTERPRISE

​
Diffusion en continu des likes

Ceci est une API Enterprise disponible uniquement dans le cadre de nos niveaux d’accès gérés. Pour utiliser cette API, vous devez d’abord créer un compte avec notre équipe commerciale Enterprise. En savoir plus Les likes offrent une visibilité sur les utilisateurs qui aiment des Posts et fournissent des décomptes précis. Les solutions Firehose et Decahose de Gnip peuvent délivrer les likes publics liés aux Posts fournis via Gnip. Cela permet d’obtenir, en temps réel, des métriques d’engagement public et d’audience associées à un Post.   Premiers pas avec les likes Lorsque vous vous préparez à consommer des données de likes, sachez que :
  • Les likes sont fournis via un stream indépendant et distinct
  • Historiquement, les likes étaient appelés « Favorites ». La charge utile au format natif enrichi conserve cette nomenclature
  • Les streams incluent uniquement les likes publics
    • Public signifie que l’utilisateur qui like, le créateur du Post et le Post sont tous publics sur la plateforme
  • Les likes sont très similaires aux Retweets et représentent un signal public d’engagement
  • Les éléments de la charge utile incluent :
    • Objet Post original
    • Objet Actor ayant créé le Post original
    • Objet Actor ayant effectué l’action de like
  • Seul le contenu original peut être liké
    • Les Retweets ne peuvent pas être likés. Un like sur un Retweet est appliqué au Post original
    • Les Tweets cités peuvent être likés
  • Les activités de like incluent les Gnip Enrichments applicables (lorsqu’ils sont achetés/appliqués)
  • Produits / fonctionnalités pris en charge
    • Les streams de likes prennent en charge le Backfill (lorsqu’il est acheté/appliqué)
    • Il n’y a pas de prise en charge du Replay pour les streams de likes
    • Il n’y a pas de prise en charge de Search ou Historical pour les likes
    • Il n’y a pas de projets immédiats visant à ajouter la prise en charge des likes à PowerTrack
Decahose Charge utile au format natif enrichi 
{
   "id":"43560406e0ad9f68374445f5f30c33fc",
   "created_at":"Thu Dec 01 22:27:39 +0000 2016",
   "timestamp_ms":1480631259353,
   "favorited_status":{
      "created_at":"Thu Dec 01 22:27:16 +0000 2016",
      "id":804451830033948672,
      "id_str":"804451830033948672",
      "text":"@kafammheppduman",
      "source":"\u003ca href=\"http:\/\/x.com\/download\/android\" rel=\"nofollow\"\u003eX pour Android\u003c\/a\u003e",
      "truncated":false,
      "in_reply_to_status_id":803694205163814912,
      "in_reply_to_status_id_str":"803694205163814912",
      "in_reply_to_user_id":2855759795,
      "in_reply_to_user_id_str":"2855759795",
      "in_reply_to_screen_name":"kafammheppduman",
      "user":{
         "id":2855759795,
         "id_str":"2855759795",
         "name":"delirdim kanka",
         "screen_name":"kafammheppduman",
         "location":"sanane",
         "url":"http:\/\/instagram.com\/kafammheppduman",
         "description":"Manit @GalatasaraySk \ud83d\udc9e",
         "translator_type":"none",
         "protected":false,
         "verified":false,
         "followers_count":3702,
         "friends_count":607,
         "listed_count":1,
         "favourites_count":113338,
         "statuses_count":389,
         "created_at":"Sat Nov 01 22:38:25 +0000 2014",
         "utc_offset":null,
         "time_zone":null,
         "geo_enabled":true,
         "lang":"tr",
         "contributors_enabled":false,
         "is_translator":false,
         "profile_background_color":"C0DEED",
         "profile_background_image_url":"",
         "profile_background_image_url_https":"",
         "profile_background_tile":false,
         "profile_link_color":"1DA1F2",
         "profile_sidebar_border_color":"C0DEED",
         "profile_sidebar_fill_color":"DDEEF6",
         "profile_text_color":"333333",
         "profile_use_background_image":true,
       "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg",
         "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg",
         "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/2855759795\/1480630085",
         "default_profile":true,
         "default_profile_image":false,
         "following":null,
         "follow_request_sent":null,
         "notifications":null
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":null,
      "is_quote_status":false,
      "retweet_count":0,
      "favorite_count":0,
      "entities":{
         "hashtags":[],
         "urls":[],
         "user_mentions":[
            {
               "screen_name":"kafammheppduman",
               "name":"delirdim kanka",
               "id":2855759795,
               "id_str":"2855759795",
               "indices":[
                  0,
                  16
               ]
            }
         ],
         "symbols":[]
      },
      "favorited":false,
      "retweeted":false,
      "filter_level":"low",
      "lang":"und"
   },
   "user":{
      "id":774146932365070336,
      "id_str":"774146932365070336",
      "name":"Uyuyan Adam",
      "screen_name":"saykoMenn",
      "location":"Tarsus, T\u00fcrkiye",
      "url":"http:\/\/connected2.me\/pmc1i",
      "description":null,
      "translator_type":"none",
      "protected":false,
      "verified":false,
      "followers_count":414,
      "friends_count":393,
      "listed_count":0,
      "favourites_count":9868,
      "statuses_count":370,
      "created_at":"Fri Sep 09 07:26:26 +0000 2016",
      "utc_offset":null,
      "time_zone":null,
      "geo_enabled":false,
      "lang":"tr",
      "contributors_enabled":false,
      "is_translator":false,
      "profile_background_color":"F5F8FA",
      "profile_background_image_url":"",
      "profile_background_image_url_https":"",
      "profile_background_tile":false,
      "profile_link_color":"1DA1F2",
      "profile_sidebar_border_color":"C0DEED",
      "profile_sidebar_fill_color":"DDEEF6",
      "profile_text_color":"333333",
      "profile_use_background_image":true,
      "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg",
      "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg",
      "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/774146932365070336\/1480283382",
      "default_profile":true,
      "default_profile_image":false,
      "following":null,
      "follow_request_sent":null,
      "notifications":null
   }
}
Payload de DELETE de like / « Unlike » 
{
   "delete":{
      "favorite":{
         "tweet_id":696615514970279937,
         "tweet_id_str":"696615514970279937",
         "user_id":2510287578,
         "user_id_str":"2510287578"
      },
      "timestamp_ms":"1480437031205"
   }
}

​
Guides

​
Récupération et redondance

Introduction  La diffusion en continu de volumes élevés de Posts en temps réel s’accompagne d’un ensemble de bonnes pratiques qui favorisent à la fois la fiabilité et la fidélité intégrale des données. Lors de la consommation de données en temps réel, maximiser le temps de connexion est un objectif fondamental. En cas de déconnexion, il est important de la détecter automatiquement et de se reconnecter. Après reconnexion, il est essentiel d’évaluer s’il existe des périodes nécessitant un rattrapage des données. Le composant qui gère ces aspects et consomme des Posts en temps réel n’est qu’une partie d’un système qui inclut des considérations de réseau, de datastore, de serveur et de stockage. Étant donnée la complexité de ces systèmes, une autre bonne pratique consiste à disposer de différents environnements de streaming, avec au minimum des streams distincts pour le développement/les tests et pour la production. Decahose est fourni avec un ensemble de fonctionnalités qui soutiennent ces efforts.
  1. Pour prendre en charge plusieurs environnements, nous pouvons déployer des Additional Streams pour votre compte. Ces streams sont indépendants les uns des autres et disposent d’un stream_label distinct pour les différencier.
  2. Pour contribuer au maintien de la connexion, chaque stream Decahose prend en charge les Redundant Connections. L’architecture la plus courante consiste à doter un stream de deux connexions, et côté client d’avoir deux consommateurs indépendants — idéalement sur des réseaux différents. Avec cette conception, il existe une redondance au niveau des réseaux côté client, des serveurs et des chemins vers le datastore. Notez qu’une copie complète des données est fournie sur chaque connexion et que le côté client doit tolérer et gérer les doublons.
  3. Un « heartbeat » est émis toutes les 10 secondes ; toutefois, avec le stream Decahose, le volume de données est suffisamment élevé pour que même une courte période (p. ex., quelques secondes) sans Posts puisse indiquer un problème de connexion. Par conséquent, à la fois un « silence de données » et l’absence de heartbeat peuvent servir à détecter une déconnexion.
Étant donné que des déconnexions surviendront, le stream Decahose propose des fonctionnalités dédiées de Recovery et de Backfill pour aider à récupérer les données manquées en raison de déconnexions et d’autres problèmes opérationnels.

​
Flux supplémentaires

Disposer de flux Decahose supplémentaires est un autre moyen d’améliorer la fiabilité de votre solution. Chaque flux supplémentaire est totalement indépendant, avec son propre endpoint. Chaque flux se voit attribuer son propre stream_label, et ce libellé, ainsi que le nom de votre compte, font partie de l’URL de ce flux. Voir l’exemple ci-dessous : https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json La convention la plus courante consiste à disposer d’un stream temps réel dédié à votre système de production, et d’un flux supplémentaire pour le développement et les tests. Avoir un flux de test/de développement permet aux clients Decahose de tester les mises à jour de leurs consommateurs clients. Bien que tout libellé (unique) puisse être attribué à un flux, une convention consiste à utiliser « prod » pour le flux de production, et « dev » ou « sandbox » pour un flux de développement supplémentaire. Le nombre de flux et leurs libellés uniques sont configurables par votre interlocuteur commercial. Connexions redondantes Une connexion redondante vous permet simplement d’établir plus d’une connexion simultanée au stream de données. Cela assure une redondance en vous permettant de vous connecter au même flux avec deux consommateurs distincts, recevant les mêmes données via les deux connexions. Ainsi, votre App dispose d’un basculement à chaud pour diverses situations, par exemple lorsqu’un stream est déconnecté ou lorsque le serveur principal de votre App tombe en panne. Le nombre de connexions autorisées pour un flux donné est configurable par votre interlocuteur commercial. Pour utiliser un stream redondant, connectez-vous simplement à la même URL que celle utilisée pour votre connexion principale. Les données de votre flux seront envoyées via les deux connexions, les deux connexions de stream étant représentées sur le tableau de bord du stream. Notez qu’à des fins de facturation, nous dédupliquons les décomptes d’activités que vous recevez via plusieurs connexions de sorte que vous ne soyez facturé qu’une seule fois pour chaque activité unique. Étant donné que Decahose comporte deux partitions, voici un exemple du fonctionnement du comptage des connexions : Connect to decahose partition=1 Connect to decahose partition=1 Connect to decahose partition=2 La situation ci-dessus donne un total de trois connexions — deux connexions à partition=1 et une connexion à partition=2. Normalement, vous souhaiterez le même nombre de connexions pour chaque partition ; cet exemple met donc en évidence une situation où la connexion redondante à partition=2 est tombée et nécessite une investigation supplémentaire. Récupération

​
Présentation 

Recovery est un outil de récupération de données (à ne pas utiliser pour la collecte principale) qui offre un accès en continu à une fenêtre glissante de 5 jours des données historiques récentes de X. Il doit être utilisé pour récupérer des données lorsque votre application consommatrice manque des données dans le stream en temps réel, que ce soit en raison d’une brève déconnexion ou de toute autre situation où vous n’avez pas ingéré de données en temps réel pendant un certain temps.

​
Utilisation de Recovery 

Avec le stream Recovery, votre App peut envoyer des requêtes qui fonctionnent de la même manière que celles adressées aux streams en temps réel. Cependant, votre App doit spécifier dans l’URL des paramètres indiquant la fenêtre temporelle demandée. En d’autres termes, une requête Recovery demande à l’API « Posts de l’heure A à l’heure B ». Ces Posts sont ensuite livrés via votre connexion de streaming d’une manière qui imite le stream en temps réel, mais à un rythme légèrement inférieur au temps réel. Voir ci-dessous un exemple : “https://stream-data-api.x.com/stream/powertrack/accounts/someAccountName/publishers/twitter/powertrack.json?startTime=2023-07-05T17:09:12.070Z” Les Posts sont livrés en commençant par la première (la plus ancienne) minute de la période spécifiée, puis en continuant chronologiquement jusqu’à la dernière minute. À ce moment-là, un message « Recovery Request Completed » est envoyé via la connexion, et la connexion est ensuite fermée par le serveur. Si votre requête commence à une heure de la journée où peu ou pas de résultats correspondants se sont produits, il y aura probablement un certain laps de temps avant la livraison des premiers résultats — les data seront livrées lorsque Recovery rencontrera des correspondances dans la portion de l’archive en cours de traitement à ce moment-là. Lorsque aucun résultat n’est disponible à livrer, le stream continuera d’envoyer des retours chariot, ou « battements de cœur », via la connexion pour éviter l’expiration de votre session. Recovery est conçu comme un outil pour récupérer facilement les data manquées en raison de courtes déconnexions, et non pour de très longues périodes comme une journée entière. Si vous devez récupérer des data sur de longues périodes, nous recommandons de diviser les requêtes plus longues en fenêtres temporelles plus courtes (par exemple deux heures) afin de réduire le risque d’être déconnecté en cours de requête en raison de la volatilité d’Internet ou pour d’autres raisons, et d’offrir une meilleure visibilité sur l’avancement des requêtes longues.

​
Disponibilité des données

Vous pouvez utiliser la fonctionnalité Recovery pour récupérer les données manquées au cours des dernières 24 heures si vous ne parvenez pas à vous reconnecter avec la fenêtre de rattrapage de 5 minutes. La fonctionnalité de récupération en stream vous permet de bénéficier d’une fenêtre de rattrapage étendue de 24 heures. Recovery vous permet de « récupérer » la période de données manquées. Un stream de récupération est lancé lorsque vous effectuez une requête de connexion en utilisant les paramètres de requête ‘start_time’ et ‘end_time’. Une fois connecté, Recovery re‑diffuse la période indiquée, puis se déconnecte.   Vous pouvez effectuer 2 requêtes simultanées vers Recovery en même temps, c’est‑à‑dire « deux jobs de récupération ». Recovery fonctionne techniquement de la même manière que le rattrapage, sauf qu’une heure de début et une heure de fin sont définies. Une période de récupération correspond à une seule plage temporelle.

​
Rattrapage (Backfill)

Pour demander un rattrapage, vous devez ajouter le paramètre backfillMinutes=N à votre requête de connexion, où N est le nombre de minutes (1-5, nombres entiers uniquement) à rattraper lors de l’établissement de la connexion. Par exemple, si vous êtes déconnecté pendant 90 secondes, vous devez ajouter backfillMinutes=2 à votre requête de connexion. Étant donné que cette requête fournira un rattrapage de 2 minutes, y compris pour les 30 secondes précédant votre déconnexion, votre App consommatrice doit tolérer les données en double. Un exemple d’URL de requête de connexion Decahose, demandant un rattrapage de 5 minutes vers la partition 1, est : https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1&backfillMinutes=5 NOTES :
  • Vous pouvez choisir d’utiliser systématiquement « backfillMinutes=5 » lors de la connexion, puis de gérer les données en double fournies.
  • Si vous êtes déconnecté plus de cinq minutes, vous pouvez récupérer les données à l’aide de Recovery.
Récupération après déconnexion Redémarrer et se rétablir après une déconnexion implique plusieurs étapes :
  • Déterminer la durée de la période de déconnexion.
    • 5 minutes ou moins ?
      • Si Backfill est activé pour le stream, préparez la requête de connexion avec le paramètre « backfillMinutes » approprié.
    • Plus de 5 minutes ?
      • Si vous disposez d’un stream de Recovery, effectuez une requête de Recovery pour la période de déconnexion (idéalement avec votre jeu de règles temps réel actuel, en utilisant l’API Rules si nécessaire).
  • Demander une nouvelle connexion.
Lorsque vous rencontrez des déconnexions ou des interruptions, voici des stratégies pour atténuer l’impact et vous rétablir dans ce scénario :
  1. Mettre en œuvre le rattrapage (Backfill) Le rattrapage vous permet de vous reconnecter à partir d’un point antérieur à la déconnexion d’un stream et couvre des déconnexions jusqu’à 5 minutes. Il s’active en incluant un paramètre dans la requête de connexion.
  2. Consommer un stream redondant depuis un autre emplacement Si le stream redondant peut être acheminé vers le même environnement de production en direct, avec déduplication des données, vous éviterez le besoin de récupération sauf si le stream normal ET le stream redondant subissent simultanément une interruption ou une déconnexion. Si le stream redondant ne peut pas être diffusé en direct dans l’environnement de production, il peut être écrit dans un magasin de données « d’urgence » séparé. Ainsi, en cas de déconnexions ou d’interruptions sur la connexion de stream principale, votre système disposera de données pour compléter votre base de données principale pendant la période où des données manquent.
  3. Mettre en œuvre Recovery Lorsque des déconnexions ou des interruptions affectent à la fois le stream principal et le stream redondant, utilisez Decahose Recovery pour récupérer toute donnée manquée. L’API fournit une fenêtre glissante couvrant 5 jours d’archives, à utiliser de préférence en demandant au plus une heure de cette fenêtre à la fois, puis en la diffusant. Cette opération se fait en parallèle du stream temps réel. Notez que nous n’avons pas de solution pour récupérer des données Decahose au-delà de la fenêtre de 5 jours fournie par Recovery ; il est donc important d’utiliser un stream redondant pour vous assurer de disposer d’une copie complète des données de votre côté en cas d’interruption significative.
Lorsque vous détectez des volumes de données stockées anormaux – Méthodes possibles pour détecter des données manquantes alors qu’aucune déconnexion ni interruption ne s’est produite…
  1. Compter les Posts entrants Votre système doit compter le nombre brut de Posts reçus dès le tout début de votre App d’ingestion, puis offrir un moyen de comparer ces nombres au nombre de Posts qui atteignent votre magasin de données final. Toute différence peut être surveillée et alerter votre équipe de problèmes entraînant la perte de données après leur réception.
  2. Analyser les volumes stockés anormaux Vous pouvez également analyser les volumes de données stockées dans votre base de données finale pour détecter des baisses anormales. Cela peut aussi indiquer des problèmes, bien qu’il existe probablement des circonstances où des baisses de volume sont normales (par exemple, si la plateforme X est indisponible et que les personnes ne peuvent pas créer de Posts pendant un certain temps).

​
Référence de l’API

​
Flux Decahose

Aller à sur cette page Méthodes Authentification GET /{stream-type}/:stream API Replay

​
Méthodes

MéthodeDescription
GET /{stream-type}/:streamSe connecter au stream de données

​
Authentification

Toutes les requêtes adressées aux Volume Stream APIs doivent utiliser l’authentification HTTP Basic, construite à partir d’une combinaison valide d’adresse e‑mail et de mot de passe utilisée pour vous connecter à votre compte sur console.gnip.com. Les informations d’identification doivent être transmises dans l’en‑tête Authorization pour chaque requête. Assurez‑vous donc que votre client ajoute l’en‑tête HTTP “Authorization: Basic” (avec des identifiants encodés via HTTPS) à toutes les requêtes API.

​
GET :stream

Établit une connexion persistante au stream Firehose, via laquelle les données en temps réel seront livrées.

​
Spécifications de la requête

Méthode de requêteHTTP GET
Type de connexionKeep-Alive

À préciser dans l’en-tête de la requête.
URLDisponible sur la page d’aide de l’API du stream dans votre tableau de bord, selon la structure suivante :

Decahose :

https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1
Partition (obligatoire)partition=\{#} - Le partitionnement est désormais requis pour consommer l’intégralité du stream. Vous devez vous connecter au stream avec le paramètre de partition renseigné. Nombre de partitions par stream :

* Decahose : 2 partitions
CompressionGzip. Pour vous connecter au stream avec la compression Gzip, envoyez simplement un en-tête Accept-Encoding dans la requête de connexion. L’en-tête doit être le suivant :

Accept-Encoding: gzip
Encodage des caractèresUTF-8
Format de réponseJSON. L’en-tête de votre requête doit spécifier le format JSON pour la réponse.
Limite de taux10 requêtes par 60 secondes.
Paramètre BackfillSi vous avez acheté un stream avec Backfill activé, vous devez ajouter le paramètre “backfillMinutes” à la requête GET pour l’activer.
Délai d’expiration de lectureConfigurez un délai d’expiration de lecture sur votre client et assurez-vous qu’il est supérieur à 30 secondes.
Prise en charge des modifications de TweetTous les objets Tweet incluront des metadata d’édition de Tweet décrivant l’historique des modifications du Tweet. Consultez la page de référence “Edit Tweets” pour plus de détails.

​
Réponses

Les réponses suivantes peuvent être renvoyées par l’API pour ces requêtes. La plupart des codes d’erreur sont renvoyés avec une chaîne contenant des détails supplémentaires dans le corps. Pour les réponses différentes de 200, les clients doivent tenter de se reconnecter.
StatutTexteDescription
200SuccèsLa connexion a été ouverte avec succès et de nouvelles activités seront envoyées au fur et à mesure de leur arrivée.
401Non autoriséL’authentification HTTP a échoué en raison d’identifiants invalides. Connectez-vous à console.gnip.com avec vos identifiants pour vérifier que vous les utilisez correctement dans votre requête.
406Non acceptableEn général, cela se produit lorsque votre client n’inclut pas correctement les en-têtes pour accepter l’encodage gzip depuis le stream, mais cela peut aussi survenir dans d’autres circonstances.

Contiendra un message JSON similaire à « Cette connexion requiert la compression. Pour l’activer, envoyez un en-tête ‘Accept-Encoding: gzip’ dans votre requête et préparez-vous à décompresser le stream lors de sa lecture côté client. »
429Limite de taux atteinteVotre App a dépassé la limite des requêtes de connexion.
503Service indisponibleProblème de serveur X. Reconnectez-vous en appliquant une temporisation exponentielle (exponential backoff). Si aucun avis concernant ce problème n’a été publié sur la X API Status Page, contactez le support (ou l’assistance d’urgence) si vous ne parvenez pas à vous connecter après 10 minutes.

​
Exemple de requête curl

L’exemple de requête suivant utilise curl en ligne de commande. Notez toutefois que ces requêtes peuvent également être envoyées dans le langage de programmation de votre choix : 
curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/firehose/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition={#}"

​
API Replay

L’API Replay complète de manière essentielle les streams Volume en temps réel. Replay est un outil de récupération de données qui offre un accès en streaming à une fenêtre glissante des données historiques récentes de X.
⌘I