Utilizzare i dati in stream

​

Creazione di un client per consumare dati in streaming

Quando si utilizza un endpoint di streaming, è opportuno seguire alcune buone pratiche generali per ottimizzarne l’uso.    

​

Progettazione del client

Quando si crea una soluzione con l’endpoint filter stream, è necessario un client in grado di:

1. Stabilire una connessione di streaming HTTPS all’endpoint filter stream.
2. Inviare asincronamente richieste POST all’endpoint delle regole del filter stream per aggiungere ed eliminare regole dallo stream.
3. Gestire bassi volumi di dati – mantenere la connessione di streaming, rilevare gli Oggetti Post e i segnali di keep-alive.
4. Gestire alti volumi di dati – disaccoppiare l’ingestione dello stream dall’elaborazione aggiuntiva utilizzando processi asincroni e assicurarsi che i buffer lato client vengano svuotati regolarmente.
5. Gestire il monitoraggio del consumo di volume lato client.
6. Rilevare le disconnessioni dello stream, valutarle e riconnettersi automaticamente allo stream.  

​

Connessione a un endpoint di streaming

Stabilire una connessione agli endpoint di streaming di X API v2 significa effettuare una richiesta HTTP di lunga durata e analizzare la risposta in modo incrementale. In sostanza, la si può considerare come lo scaricamento di un file infinitamente lungo tramite HTTP. Una volta stabilita la connessione, il server di X invierà eventi Post attraverso la connessione finché questa rimarrà aperta.  

​

Consumo dei dati

Nota che i singoli campi degli oggetti JSON non sono ordinati e che non tutti i campi sono sempre presenti. Analogamente, le attività distinte non vengono recapitate in ordine e si possono incontrare messaggi duplicati. Tieni presente che nel tempo possono essere aggiunti nuovi tipi di messaggi e inviati tramite lo stream.

Pertanto, il tuo client deve tollerare:

• Campi in qualsiasi ordine
• Campi imprevisti o mancanti
• Post non ordinati
• Messaggi duplicati
• Nuovi tipi di messaggi arbitrari che arrivano nello stream in qualsiasi momento

Oltre ai dati pertinenti dei Post e ai parametri dei fields richiesti, i seguenti tipi di messaggi possono essere recapitati su una connessione stream. Nota che questo elenco potrebbe non essere esaustivo: altri oggetti potrebbero essere introdotti negli stream. Assicurati che il parser sia tollerante a formati di messaggio imprevisti.  

​

Buffering 

Gli endpoint di streaming invieranno i data non appena sono disponibili, il che in molti casi può comportare volumi elevati. Se il server di X non può scrivere subito nuovi data nello stream (ad esempio, se il tuo client non legge abbastanza velocemente; vedi handling disconnections per maggiori informazioni), eseguirà il buffering dei contenuti lato server per consentire al tuo client di recuperare. Tuttavia, quando questo buffer è pieno, verrà avviata una disconnessione forzata per interrompere la connessione e i Post in buffer verranno eliminati e non reinviati. Vedi di seguito per maggiori dettagli.

Un modo per individuare quando la tua app sta restando indietro è confrontare il timestamp dei Post ricevuti con l’ora corrente e monitorare questo scostamento nel tempo.

Sebbene i backlog dello stream non possano essere completamente eliminati a causa della latenza potenziale e di eventuali problemi sulla rete pubblica, possono essere per lo più evitati con una corretta configurazione della tua app. Per ridurre al minimo il verificarsi di backlog:

• Assicurati che il tuo client legga lo stream abbastanza velocemente. In genere non dovresti eseguire alcuna elaborazione mentre leggi lo stream. Leggi lo stream e delega l’attività a un altro thread/process/data store per eseguire l’elaborazione in modo asincrono.
• Assicurati che il tuo data center abbia una banda in ingresso sufficiente per gestire grandi volumi di data sostenuti, nonché picchi significativamente maggiori (ad es. 5–10x il volume normale). Per filtered stream, il volume e la corrispondente larghezza di banda richiesta dalla tua parte dipendono interamente dai Post che le tue regole fanno corrispondere.  

​

Monitoraggio dell’utilizzo e gestione delle regole

Poiché le aspettative degli sviluppatori su quale sia un volume di dati “normale” per i loro stream variano, non abbiamo una raccomandazione generale relativa a una specifica percentuale di diminuzione/aumento o a un periodo di tempo.

Prendi in considerazione il monitoraggio dei volumi di dati del tuo stream per individuare deviazioni inattese. Una diminuzione del volume può essere sintomatica di un problema diverso da una disconnessione dello stream. In una situazione del genere, lo stream continuerebbe a ricevere il segnale di keep-alive e probabilmente anche alcuni nuovi dati di attività. Tuttavia, un numero significativamente ridotto di Post dovrebbe spingerti a verificare se ci sia qualcosa che stia causando la diminuzione del volume di dati in ingresso alla tua applicazione o rete; controlla la pagina di stato per eventuali avvisi correlati.

Per impostare questo tipo di monitoraggio, puoi tracciare il numero di nuovi Post che ti aspetti di vedere in un determinato intervallo di tempo. Se il volume di dati di uno stream scende ben al di sotto della soglia specificata e non si riprende entro un periodo stabilito, dovrebbero essere attivati avvisi e notifiche. Potresti anche voler monitorare un forte aumento del volume di dati, in particolare se stai modificando le regole in un filtered stream o se si verifica un evento che genera un picco nell’attività dei Post.

È importante notare che i Post consegnati tramite filtered stream vengono conteggiati nel volume mensile totale dei Post e dovresti monitorare e regolare il consumo per ottimizzare. Se il volume è elevato, prendi in considerazione l’aggiunta dell’operatore sample: a ciascuna delle tue regole per ridurre dal 100% di corrispondenza a sample:50 o sample:25 quando necessario.

Inoltre, ti incoraggiamo a implementare misure all’interno della tua App che avvisino il tuo team se il volume supera una soglia preimpostata e a introdurre eventualmente altre misure, come l’eliminazione automatica delle regole che stanno facendo affluire troppi dati o la disconnessione completa dallo stream in circostanze estreme.  

​

Rispondere ai messaggi di sistema

Segnali di keep-alive Almeno ogni 20 secondi lo stream invierà un segnale di keep-alive, o heartbeat, sotto forma di ritorno carrello \r\n attraverso la connessione aperta per evitare che il client vada in timeout. L’applicazione client dovrebbe tollerare i caratteri \r\n nello stream.

Se il client implementa correttamente un timeout di lettura nella libreria HTTP, l’App potrà fare affidamento sul protocollo HTTP e sulla libreria HTTP per generare un evento se, entro questo periodo, non vengono letti dati, e non sarà necessario monitorare esplicitamente il carattere \r\n.

Questo evento sarà tipicamente il lancio di un’eccezione o un altro tipo di evento, a seconda della libreria HTTP utilizzata. Si raccomanda vivamente di avvolgere i metodi HTTP con gestori di errori/eventi per rilevare questi timeout. In caso di timeout, l’applicazione dovrebbe tentare di riconnettersi.

Messaggi di errore Gli endpoint di streaming v2 possono anche fornire messaggi di errore nello stream. Di seguito è riportato il formato di base di questi messaggi, insieme ad alcuni esempi. Tieni presente che i messaggi forniti potrebbero cambiare, con l’introduzione di nuovi messaggi. Le applicazioni client devono tollerare payload di messaggi di sistema soggetti a modifiche.

Nota che i messaggi di errore conterranno link alla documentazione che descrive come risolvere il problema.

Formato del messaggio:

	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "Questo stream è stato disconnesso upstream per motivi operativi.",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}

Nota che i messaggi di errore che indicano una disconnessione forzata dovuta a un buffer pieno potrebbero non raggiungere il client, se l’accumulo che ha causato la disconnessione forzata ne impedisce la consegna. Di conseguenza, l’App non dovrebbe fare affidamento su questi messaggi per avviare una nuova connessione.