Vai al contenuto principale
Questo endpoint è stato aggiornato per includere i metadati di modifica dei Post. Scopri di più su questi metadati nella pagina dei fondamenti “Modifica dei Post”.

​
stream Decahose

Enterprise Questa è un’API Enterprise disponibile solo nei nostri livelli di accesso gestiti. Per utilizzare questa API, devi prima configurare un account con il nostro team vendite Enterprise. Scopri di più Il Decahose fornisce un campione casuale del 10% del Firehose in tempo reale di X tramite una connessione di streaming. Questo avviene tramite un algoritmo di campionamento in tempo reale che seleziona casualmente i data, garantendo al contempo la prevista consegna a bassa latenza dei data man mano che vengono inviati attraverso il Firehose da X. Di seguito sono riportate alcune delle funzionalità disponibili con Decahose:
  • URL espansi e migliorati: - espande completamente gli URL accorciati e fornisce ulteriori metadata (titolo e descrizione della pagina)
  • Partizionamento dello stream - 2 partizioni, ciascuna contenente il 50% del volume dello stream Decahose
  • Affidabilità migliorata - diversificazione geografica dei sistemi backend
Nota: questi data vengono forniti in blocco e non supportano filtri aggiuntivi (ad es. per parole chiave). ENTERPRISE

​
Streaming dei like

Questa è un’API Enterprise disponibile solo nei nostri livelli di accesso gestiti. Per utilizzare questa API, devi prima configurare un account con il nostro team commerciale Enterprise. Scopri di più I like offrono visibilità su chi mette like ai Post e forniscono conteggi accurati dei like. Firehose e Decahose di Gnip possono fornire i like pubblici relativi ai Post distribuiti tramite Gnip. Questo produce metriche di coinvolgimento pubblico e di audience in tempo reale associate a un Post.   Per iniziare con i like Mentre ti prepari a utilizzare i dati dei like, tieni presente che:
  • I like sono forniti tramite uno stream indipendente e separato
  • Storicamente i like erano chiamati “Favorites”. Il payload nel formato nativo arricchito mantiene questa nomenclatura
  • Gli stream includono solo like pubblici
    • Pubblico significa che l’utente che mette il like, il creatore del Post e il Post sono tutti pubblici sulla piattaforma
  • I like sono molto simili ai Retweet e rappresentano un segnale pubblico di coinvolgimento
  • Gli elementi del payload includono:
    • Oggetto Post originale
    • Oggetto Actor che ha creato il Post originale
    • Oggetto Actor che ha eseguito l’azione di like
  • Solo i contenuti originali possono ricevere like
    • I Retweet non possono ricevere like. Un like a un Retweet viene applicato al Post originale
    • I Tweet con citazione possono ricevere like
  • Le attività di like includono le Gnip Enrichments applicabili (ove acquistate/applicate)
  • Prodotti/Funzionalità supportati
    • Gli stream dei like supportano Backfill (ove acquistato/applicato)
    • Non esiste supporto Replay per gli stream dei like
    • Non esiste supporto Search o Historical per i like
    • Non ci sono piani immediati per aggiungere il supporto ai like in PowerTrack
Decahose Payload nel formato nativo arricchito 
{
   "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 per 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 DELETE del like / “Annulla like” 
{
   "delete":{
      "favorite":{
         "tweet_id":696615514970279937,
         "tweet_id_str":"696615514970279937",
         "user_id":2510287578,
         "user_id_str":"2510287578"
      },
      "timestamp_ms":"1480437031205"
   }
}

​
Guide

​
Ripristino e ridondanza

Introduzione  Con lo streaming di grandi volumi di Post in tempo reale, esiste un insieme di best practice che promuovono sia l’affidabilità sia la piena fedeltà dei dati. Quando si consumano dati in tempo reale, massimizzare il tempo di connessione è un obiettivo fondamentale. In caso di disconnessioni, è importante rilevarle automaticamente e riconnettersi. Dopo la riconnessione, è fondamentale valutare se ci siano periodi per cui effettuare il backfill dei dati. Il componente che gestisce questi aspetti e consuma Post in tempo reale è solo una parte di un sistema con esigenze di rete, datastore, server e storage. Data la complessità di questi sistemi, un’altra best practice è disporre di ambienti di streaming distinti, con almeno stream separati per sviluppo/test e produzione. Decahose include funzionalità che supportano questi obiettivi.
  1. Per supportare ambienti multipli, possiamo distribuire Additional Streams per il tuo account. Questi stream sono indipendenti tra loro e dispongono di uno stream_label diverso per facilitarne la distinzione.
  2. Per favorire il mantenimento della connessione, ogni stream Decahose supporta Redundant Connections. L’architettura più comune prevede che uno stream abbia due connessioni e, lato client, due consumer indipendenti — idealmente su reti diverse. Con questo design, si ottiene ridondanza tra reti lato client, server e percorsi del datastore. Nota che su ciascuna connessione viene fornita una copia completa dei dati e il lato client deve tollerare e gestire i duplicati.
  3. Un “heartbeat” viene inviato ogni 10 secondi; tuttavia, con lo stream Decahose il volume di dati è così elevato che anche una breve assenza di Post (ad es. pochi secondi) può indicare un problema di connessione. Pertanto, sia il “silenzio dei dati” sia l’assenza di un heartbeat possono essere usati per rilevare una disconnessione.
Poiché le disconnessioni sono inevitabili, lo stream Decahose dispone di funzionalità dedicate di Recovery e Backfill per aiutare a recuperare i dati persi a causa di disconnessioni e altri problemi operativi.

​
Stream aggiuntivi

Disporre di ulteriori stream Decahose è un altro modo per aumentare l’affidabilità della soluzione. Gli stream aggiuntivi sono completamente indipendenti e hanno un endpoint univoco. A ogni stream viene assegnato uno stream_label e questa etichetta, insieme al nome dell’account, fa parte dell’URL di quello stream. Vedi l’esempio seguente: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json La convenzione più comune è avere uno stream in tempo reale dedicato all’ambiente di produzione e uno stream aggiuntivo disponibile per sviluppo e test. Disporre di uno stream di test/sviluppo consente ai clienti Decahose di testare gli aggiornamenti dei consumer client. Sebbene a uno stream possa essere assegnata qualsiasi etichetta (univoca), una convenzione è utilizzare “prod” per lo stream di produzione e “dev” o “sandbox” per lo stream di sviluppo aggiuntivo. Il numero di stream e le rispettive etichette univoche sono configurabili dal referente del tuo account. Connessioni ridondanti Una connessione ridondante consente semplicemente di stabilire più connessioni simultanee allo stream di dati. Questo offre ridondanza permettendo di connettersi allo stesso stream con due consumer separati, ricevendo gli stessi dati su entrambe le connessioni. In tal modo, la tua App dispone di un hot failover per varie situazioni, ad esempio quando uno stream si disconnette o quando il server primario della tua App ha un guasto. Il numero di connessioni consentite per un determinato stream è configurabile dal referente del tuo account. Per utilizzare uno stream ridondante, connettiti allo stesso URL usato per la connessione primaria. I dati per il tuo stream verranno inviati su entrambe le connessioni, con entrambe le connessioni rappresentate nella dashboard dello stream. Nota: ai fini della fatturazione, deduplichiamo i conteggi delle attività ricevuti tramite più connessioni in modo che venga addebitata una sola volta ogni attività univoca. Poiché Decahose ha due partizioni, ecco un esempio di come funziona il conteggio delle connessioni: Connect to decahose partition=1 Connect to decahose partition=1 Connect to decahose partition=2 La situazione sopra comporta un totale di tre connessioni: due connessioni a partition=1 e una connessione a partition=2. Normalmente, vorresti lo stesso numero di connessioni per ciascuna partizione, quindi questo esempio evidenzia una situazione in cui la connessione ridondante a partition=2 è caduta e occorre indagare ulteriormente. Ripristino

​
Panoramica 

Recovery è uno strumento di ripristino dei dati (da non utilizzare per la raccolta primaria) che offre accesso in streaming a una finestra mobile di 5 giorni dei dati storici recenti di X. Va utilizzato per recuperare i dati quando l’applicazione che consuma i dati perde eventi dallo stream in tempo reale, sia per una breve disconnessione sia per qualsiasi altra situazione in cui non riesci a ingerire dati in tempo reale per un certo periodo.

​
Utilizzo di Recovery 

Con lo stream Recovery, la tua App può effettuare richieste che funzionano nello stesso modo delle richieste agli stream in tempo reale. Tuttavia, la tua App deve specificare nell’URL i parametri che indicano la finestra temporale richiesta. In altre parole, una richiesta Recovery chiede all’API “Post dal tempo A al tempo B”. Questi Post vengono quindi recapitati tramite la tua connessione di streaming in modo che imita lo stream in tempo reale, ma a una velocità leggermente inferiore al tempo reale. Vedi l’esempio seguente: “https://stream-data-api.x.com/stream/powertrack/accounts/someAccountName/publishers/twitter/powertrack.json?startTime=2023-07-05T17:09:12.070Z” I Post vengono recapitati a partire dal primo (più vecchio) minuto del periodo di tempo specificato, proseguendo in ordine cronologico fino all’ultimo minuto. A quel punto, viene inviato tramite la connessione un messaggio “Recovery Request Completed” e il server chiude la connessione. Se la tua richiesta inizia in un momento della giornata in cui si sono verificati pochi o nessun risultato corrispondente, è probabile che trascorra un certo periodo di tempo prima che vengano recapitati i primi risultati: i dati verranno recapitati quando Recovery troverà corrispondenze nella porzione dell’archivio che sta elaborando in quel momento. Quando non ci sono risultati disponibili da recapitare, lo stream continuerà a inviare ritorni a capo, o “heartbeat”, attraverso la connessione per evitare il timeout. Recovery è pensato come strumento per recuperare facilmente i dati persi a causa di brevi disconnessioni, non per periodi molto lunghi come un’intera giornata. Se si presenta la necessità di recuperare dati per lunghi periodi, consigliamo di suddividere le richieste più lunghe in finestre temporali più brevi (ad es. due ore) per ridurre la possibilità di essere disconnessi durante la richiesta a causa della volatilità di Internet o di altri motivi e per fornire maggiore visibilità sull’avanzamento delle richieste lunghe.

​
Disponibilità dei dati

Puoi utilizzare la funzionalità Recovery per recuperare i dati persi nelle ultime 24 ore se non riesci a riconnetterti entro la finestra di backfill di 5 minuti. La funzionalità di recovery dello stream consente una finestra di backfill estesa a 24 ore. Recovery ti permette di recuperare l’intervallo di tempo dei dati mancanti. Uno stream di recovery viene avviato quando invii una richiesta di connessione utilizzando i parametri di richiesta ‘start_time’ ed ‘end_time’. Una volta connesso, Recovery ri-streamerà l’intervallo indicato e poi si disconnetterà.   Puoi eseguire 2 richieste di recovery in parallelo, cioè due “job di recovery”. Recovery funziona tecnicamente come il backfill, tranne per il fatto che vengono definiti un orario di inizio e uno di fine. Un periodo di recovery riguarda un’unica fascia temporale.

​
Backfill

Per richiedere il backfill, devi aggiungere il parametro backfillMinutes=N alla richiesta di connessione, dove N è il numero di minuti (1-5, solo numeri interi) da recuperare al momento della connessione. Ad esempio, se ti disconnetti per 90 secondi, dovresti aggiungere backfillMinutes=2 alla richiesta di connessione. Poiché questa richiesta fornirà il backfill per 2 minuti, includendo i 30 secondi precedenti alla disconnessione, la tua consumer app deve tollerare dati duplicati. Un esempio di URL di richiesta di connessione Decahose, che richiede un backfill di 5 minuti sulla partizione 1, è: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1&backfillMinutes=5 NOTE:
  • Puoi scegliere di usare sempre “backfillMinutes=5” quando ti connetti, gestendo poi gli eventuali dati duplicati forniti.
  • Se rimani disconnesso per più di cinque minuti, puoi recuperare i dati utilizzando Recovery.
Ripristino dopo una disconnessione Il riavvio e il ripristino dopo una disconnessione prevedono diversi passaggi:
  • Determinare la durata del periodo di disconnessione.
    • 5 minuti o meno?
      • Se hai il Backfill abilitato per lo stream, prepara la richiesta di connessione con il parametro “backfillMinutes” appropriato.
    • Più di 5 minuti?
      • Se disponi di un Recovery stream, effettua una richiesta di Recovery per il periodo di tempo in cui sei stato disconnesso (idealmente con l’attuale set di regole in tempo reale, utilizzando la Rules API se necessario).
  • Richiedere una nuova connessione.
Quando si verificano disconnessioni o downtime, ecco alcune strategie per mitigare e ripristinare in questo scenario:
  1. Implementare il backfill Il backfill consente di riconnetterti a partire da un punto precedente alla disconnessione da uno stream e copre disconnessioni fino a 5 minuti. Si implementa includendo un parametro nella richiesta di connessione.
  2. Consumare uno stream ridondante da un’altra posizione Se lo stream ridondante può essere inviato nello stesso ambiente live, con deduplicazione dei dati, eliminerai la necessità di recovery a meno che SIA lo stream normale SIA quello ridondante non subiscano contemporaneamente downtime o disconnessioni. Se lo stream ridondante non può essere trasmesso in live nell’ambiente di produzione, può essere scritto in un archivio dati “di emergenza” separato. In tal caso, in caso di disconnessioni o downtime sulla connessione dello stream primario, il sistema avrà dati disponibili per colmare il database primario per il periodo in cui mancano dati.
  3. Implementare Recovery Quando disconnessioni o downtime interessano sia lo stream primario sia quello ridondante, utilizza Decahose Recovery per recuperare i dati mancanti. L’API fornisce una finestra mobile che copre 5 giorni dell’archivio; è preferibile utilizzarla richiedendo non più di un’ora alla volta e trasmettendo i dati in streaming, in parallelo allo stream in tempo reale. Nota che non disponiamo di soluzioni per recuperare dati Decahose oltre la finestra di 5 giorni fornita da Recovery, pertanto è importante utilizzare uno stream ridondante per assicurarti di avere una copia completa dei dati dalla tua parte in caso di downtime significativo.
Quando rilevi volumi di dati memorizzati anomali — Possibili modi per individuare dati mancanti in assenza di disconnessioni o downtime…
  1. Contare i Post in ingresso Il tuo sistema dovrebbe contare il numero grezzo di Post ricevuti all’inizio della tua App di ingestione e fornire un modo per confrontare tali numeri con il numero di Post che raggiunge l’archivio dati finale. Eventuali differenze possono essere monitorate e segnalare al tuo team problemi che causano la perdita di dati dopo la ricezione.
  2. Analizzare i volumi memorizzati anomali Potresti anche voler analizzare i volumi di dati memorizzati nel database finale per individuare cali anomali. Questo può indicare problemi, anche se è probabile che vi siano circostanze in cui cali di volume sono normali (ad esempio, se la piattaforma X non è disponibile e le persone non possono creare Post per un certo periodo di tempo).

​
Riferimenti API

​
stream Decahose

Vai a sezione in questa pagina Metodi Autenticazione GET /{stream-type}/:stream API di Replay

​
Metodi

MetodoDescrizione
GET /{stream-type}/:streamConnetti allo stream di data

​
Autenticazione

Tutte le richieste alle Volume Stream API devono utilizzare l’autenticazione HTTP Basic, costruita a partire da una combinazione valida di indirizzo email e password usata per accedere al tuo account su console.gnip.com. Le credenziali devono essere inviate nell’intestazione Authorization per ogni richiesta. Verifica quindi che il tuo client aggiunga l’intestazione HTTP “Authorization: Basic” (con credenziali codificate su HTTPS) a tutte le richieste API.

​
GET :stream

Stabilisce una connessione persistente allo stream Firehose, tramite la quale i dati in tempo reale verranno recapitati.

​
Specifiche della richiesta

Metodo della richiestaHTTP GET
Tipo di connessioneKeep-Alive

Questo va specificato nell’header della richiesta.
URLDisponibile nella pagina di aiuto dell’API dello stream nel tuo dashboard, con la seguente struttura:

Decahose:

https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1
Partizione (obbligatoria)partition=\{#} - Il partizionamento è ora obbligatorio per consumare l’intero stream. Dovrai connetterti allo stream specificando il parametro partition. Di seguito il numero di partizioni per stream:

* Decahose: 2 partizioni
CompressioneGzip. Per connetterti allo stream utilizzando la compressione Gzip, invia semplicemente un header Accept-Encoding nella richiesta di connessione. L’header dovrebbe essere il seguente:

Accept-Encoding: gzip
Codifica dei caratteriUTF-8
Formato della rispostaJSON. L’header della richiesta dovrebbe specificare il formato JSON per la risposta.
Limite di velocità10 richieste ogni 60 secondi.
Parametro BackfillSe hai acquistato uno stream con Backfill abilitato, devi aggiungere il parametro “backfillMinutes” alla richiesta GET per abilitarlo.
Timeout di letturaImposta un timeout di lettura nel tuo client e assicurati che sia superiore a 30 secondi.
Supporto per le modifiche ai TweetTutti gli oggetti Tweet includeranno i metadati di modifica del Tweet che descrivono la cronologia delle modifiche del Tweet. Consulta la pagina dei fondamenti “Edit Tweets” per maggiori dettagli.

​
Risposte

Le seguenti risposte possono essere restituite dall’API per queste richieste. La maggior parte dei codici di errore è accompagnata da una stringa con dettagli aggiuntivi nel body. Per risposte diverse da 200, i client dovrebbero tentare di riconnettersi.
StatusTextDescription
200SuccessLa connessione è stata aperta correttamente e le nuove attività verranno inviate man mano che arrivano.
401UnauthorizedL’autenticazione HTTP non è riuscita a causa di credenziali non valide. Accedi a console.gnip.com con le tue credenziali per verificare di usarle correttamente nella tua richiesta.
406Not AcceptableIn genere, si verifica quando il client non include correttamente le intestazioni per accettare la codifica gzip dallo stream, ma può verificarsi anche in altre circostanze.

Conterrà un messaggio JSON simile a: “Questa connessione richiede la compressione. Per abilitare la compressione, invia un’intestazione ‘Accept-Encoding: gzip’ nella tua richiesta ed essere pronto a decomprimere lo stream mentre viene letto lato client.”
429Rate LimitedLa tua App ha superato il limite sulle richieste di connessione.
503Service UnavailableProblema del server di Twitter. Riconnettiti usando un backoff esponenziale. Se non è stato pubblicato alcun avviso su questo problema sulla X API Status Page, contatta l’assistenza o l’emergenza se non riesci a connetterti dopo 10 minuti.

​
Esempio di richiesta curl

La seguente richiesta di esempio viene eseguita utilizzando cURL da riga di comando. Tieni presente, tuttavia, che queste richieste possono anche essere inviate con il linguaggio di programmazione che preferisci: 
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 è un complemento importante agli stream Volume in tempo reale. Replay è uno strumento di ripristino dei dati che fornisce accesso in streaming a una finestra scorrevole dei dati storici recenti di X.
⌘I