Streaming dei dati con aschannel (v2)

aggiornato

aschannel è un endpoint di streaming che consente ai clienti di recuperare i risultati di ciascuna attività inoltrata, in tempo reale, man mano che vengono generati. Le API di streaming differiscono dalle API regolari in quanto una connessione viene mantenuta aperta a tempo indeterminato e i messaggi vengono inviati immediatamente al client quando diventano disponibili.

I clienti si iscrivono a uno o più account utilizzando asmaster o richiedono i dati direttamente tramite asapi e i risultati verranno trasmessi al client in tempo reale una volta disponibili.

Connessione al canale

Una connessione ad aschannel può essere effettuata usando il seguente comando:

$ curl \
    -X GET \
    -H "Authorization: Token <TOKEN>" \
    -d "stream=<STREAM>" \
    https://aschannel.reincubate.com/stream/

Dove <TOKEN> è il token del client e <STREAM> l'ID del flusso del client. Questo ID viene fornito dall'endpoint asapi quando viene inoltrata un'attività e si tratta di un valore costante legato al token di un client.

Risoluzione dei codici di risposta HTTP

Quando ci si connette ad ASChannel, nell'intestazione della risposta verrà inviato un codice di risposta HTTP. La tabella seguente descrive i loro significati.

Stato Testo Descrizione
200 ok Va tutto bene.
400 Brutta richiesta La richiesta è malformata.
401 non autorizzato Il token client non è valido.
503 Servizio non disponibile aschannel non è attualmente disponibile: controlla status.reincubate.com

Interpretazione del flusso

Ogni messaggio di aschannel è diviso in due parti: un'intestazione e un carico utile. L'intestazione contiene metadati relativi al messaggio, mentre il carico utile contiene il messaggio stesso. Potrebbe trattarsi di un messaggio di sistema o dei dati richiesti dal cliente. Sia l'intestazione che il payload terminano con un ritorno a capo e una nuova riga, e ognuno di essi è preceduto da un numero che indica la lunghezza del seguente pezzo di dati.

<HEADER_LENGTH>\r\n
<HEADER>\r\n
<PAYLOAD_LENGTH>\r\n
<PAYLOAD>\r\n

Sia <HEADER_LENGTH> che <PAYLOAD_LENGTH> sono numeri interi ed entrambi rappresentano la lunghezza del campo successivo, incluso \r\n . L'intestazione è sempre codificata JSON, ma il formato del payload varia a seconda del tipo. Di conseguenza, si potrebbe consumare messaggi dall'aschannel con Python in questo modo:

buf = response.raw
while not buf.closed:
    header_length = buf.readline()
    header = buf.read(header_length)
    payload_length = buf.readline()
    payload = buf.read(payload_length)

    handle_payload(header, payload)

Al primo collegamento, la risposta sarà simile a questa e la connessione rimarrà aperta:

66
{ "type": "system",
  "id": "cff35e74-c709-4374-348e-03ea9a2cee61"}
45
{ "message": "Message streaming has begun."}

Qui, 66 e 45 sono rispettivamente la lunghezza dell'intestazione e la lunghezza del carico utile. Riconnettersi con la stessa chiave da un altro terminale darà questo:

66
{ "type": "system",
  "id": "ad17c5a5-c658-4736-876e-cf7901be7292"}
155
{ "message": "A new HTTP connection has been opened using your your authentication details, culling old connections.",
  "error": "CULLING_OLD_CONNECTIONS"
}

Interpretazione di payload chunked

Qualsiasi carico utile superiore a pochi kilobyte verrà suddiviso in blocchi più piccoli, che un cliente deve ricomporre per formare il payload originale. Le intestazioni conterranno campi denominati chunk , total_chunks e chunk_size . Queste intestazioni possono essere presenti anche quando c'è solo un singolo blocco.

Ad esempio, un risultato chunked per un'attività di login risulterebbe in un output come di seguito:

123
{ "chunk": 1,
  "total_chunks": 1,
  "type": "log-in",
  "task_id": "2a24db6c-6870-4a27-a45a-a5c172d8ec98",
  "chunk_size": 16384
}
51
{ "message": "Log-in successful",
  "success": true
}

Ricezione dei risultati dell'attività

Di seguito è riportato un esempio di risposta di un messaggio da un'attività fetch_data sul servizio icloud :

137
{ "stream": "<STREAM>",
  "task_id": "<TASK_ID>",
  "chunk": 1,
  "total_chunks": 1,
  "chunk_size": 16384,
  "type": "<PAYLOAD_TYPE>"
}
288
{ "sms": [{
    "conversation_id": "+447910000000",
    "from_me": false,
    "handle": "vodafone",
    "attachments": [],
    "deleted": false,
    "type": "SMS",
    "date": "2016-09-16 11:52:53.000000",
    "text": "Welcome to Vodafone!",
    "group_handles": null,
    "id": 1
  }]
}

Qui, <TASK_ID> è lo stesso <TASK_ID> indicato da asapi quando l'attività è stata inviata. <PAYLOAD_TYPE> descrive la natura del payload e verrà descritto utilizzando lo slug dell'azione inviata tramite asapi .

Ricezione di messaggi di sistema

Di tanto in tanto, ricloud potrebbe aver bisogno di trasmettere messaggi di sistema al client. Questi sono sempre identificati dal campo del type di intestazione impostato sul system . Per esempio:

16
{ "type": "system"
}
97
{ "code": "client-too-slow",
  "message": "The client is reading data too slowly. Disconnecting."
}

Sono possibili i seguenti valori del code messaggio di sistema:

Risposta Sommario
reconnect Riconnessione richiesta
CULLING_OLD_CONNECTIONS Connessione simultanea
WARNING_SLOW_CONNECTION Avviso di buffer
CLOSING_SLOW_CONNECTION Il cliente è troppo lento

Riconnessione richiesta

Il canale può richiedere al client di riconnettersi, in tal caso il client dovrebbe aprire una nuova connessione all'endpoint fornito il prima possibile.

Connessione simultanea

Il canale consente solo una singola connessione aperta per client, se un client apre una nuova connessione il vecchio verrà ucciso con questo messaggio.

Avviso di buffer

I client possono essere disconnessi per non aver consumato i messaggi alla velocità con cui vengono forniti. Saranno avvisati se cadono indietro, a partire da quando il buffer interno raggiunge una soglia predefinita del 40% dei loro messaggi trattenuti per loro.

Il cliente è troppo lento

Questo messaggio viene inviato quando la connessione viene interrotta quando il consumo dei messaggi è troppo lento.

Se il client ha un backlog di attività e consuma prontamente i messaggi, corrono il rischio di essere ripetutamente disconnessi e quindi di perdere molti o tutti i risultati delle attività. Una volta che un client si riconnette, verranno trasmessi solo i risultati delle attività completate dopo la disconnessione.

Come possiamo aiutare?

Il nostro team di supporto è qui per aiutarti!

I nostri orari di ufficio sono dal lunedì al venerdì, dalle 9:00 alle 17:00 GMT. L'ora è attualmente 5:07 PM GMT.

Miriamo a rispondere a tutti i messaggi entro un giorno lavorativo.

Vai alla sezione di supporto › Contatta il team aziendale ›
Il nostro fantastico team di supporto

© 2008 - 2019 Reincubate Ltd. Tutti i diritti riservati. Registrato in Inghilterra e Galles #5189175, VAT GB151788978. Reincubate® è un marchio registrato. Termini e Condizioni. Raccomandiamo 2FA. Costruito con a Londra.