DescribeStream Usalo per ottenere dati di streaming Ottieni blocchi di dati da un file di flusso Gestione degli errori derivanti dalla consegna AWS IoT MQTT basata su file

Utilizzo della distribuzione di file AWS IoT MQTT basata sui dispositivi

Per avviare il processo di trasferimento dei dati, un dispositivo deve ricevere un set di dati iniziale, che includa almeno un ID di flusso. È possibile utilizzare un AWS IoT Lavori per pianificare le attività di trasferimento dei dati per i dispositivi includendo il set di dati iniziale nel documento del processo. Quando un dispositivo riceve il set di dati iniziale, dovrebbe avviare l'interazione con la consegna AWS IoT MQTT basata sui file. Per scambiare dati con consegna AWS IoT MQTT basata su file, un dispositivo deve:

Utilizzare il MQTT protocollo per abbonarsi aMQTTargomenti basati sulla distribuzione dei file.
Invia richieste e attendi di ricevere le risposte utilizzando MQTT i messaggi.

Facoltativamente, è possibile includere un ID del file di flusso e una versione di flusso nel set di dati iniziale. L'invio di un ID del file di flusso a un dispositivo può semplificare la programmazione del firmware/software del dispositivo, poiché elimina la necessità di creare una richiesta DescribeStream dal dispositivo per ottenere questo ID. Il dispositivo può specificare la versione del flusso in una richiesta GetStream per applicare un controllo di coerenza nel caso in cui il flusso sia stato aggiornato in modo imprevisto.

DescribeStream Usalo per ottenere dati di streaming

AWS IoT MQTTla distribuzione basata su file consente DescribeStream API di inviare dati in streaming a un dispositivo. I dati di stream restituiti da questa API funzionalità includono l'ID dello stream, la versione dello stream, la descrizione dello stream e un elenco di file di stream, ognuno dei quali ha un ID di file e la dimensione del file in byte. Con queste informazioni, un dispositivo può selezionare file arbitrari per avviare il processo di trasferimento dei dati.

Nota

Non è necessario utilizzare il DescribeStream API se il dispositivo riceve tutti i file di stream richiesti IDs nel set di dati iniziale.

Attenersi ai seguenti passaggi per effettuare una richiesta DescribeStream.

Iscriversi al filtro argomento $aws/things/ThingName/streams/StreamId/description/json “accettato”.
Iscriversi al filtro argomento $aws/things/ThingName/streams/StreamId/rejected/json “rifiutato”.
Pubblicare una richiesta DescribeStream inviando un messaggio a $aws/things/ThingName/streams/StreamId/describe/json.
Se la richiesta è stata accettata, il dispositivo riceve una risposta DescribeStream sul filtro argomento “accettato”.
Se la richiesta è stata rifiutata, il dispositivo riceve la risposta di errore nel filtro argomento “rifiutato”.

Nota

Se sostituisci json con cbor negli argomenti e nei filtri per argomento mostrati, il dispositivo riceve i messaggi nel CBOR formato, che è più compatto diJSON.

DescribeStream richiesta

Una DescribeStream richiesta tipica in è JSON simile all'esempio seguente.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039"
}

(Facoltativo) “c” è il campo token client.

Il token client non può superare i 64 byte. Un token client di dimensioni superiori a 64 byte causerà una risposta di errore e un messaggio di errore InvalidRequest.

DescribeStream risposta

Una DescribeStream risposta in è JSON simile all'esempio seguente.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039",
    "s": 1,
    "d": "This is the description of stream ABC.",
    "r": [
        {
            "f": 0,
            "z": 131072
        },
        {
            "f": 1,
            "z": 51200
        }
    ]
}

"c” è il campo token client. Questo viene restituito se è stato dato nella richiesta DescribeStream. Utilizza il token client per associare la risposta alla sua richiesta.
"s” è la versione del flusso come numero intero. È possibile utilizzare questa versione per eseguire un controllo di coerenza con le richieste GetStream.
"r” contiene un elenco dei file nel flusso.
- "f” è l'ID del file di flusso come numero intero.
- "z” è la dimensione del file di flusso in numero di byte.
“d” contiene la descrizione del flusso.

Ottieni blocchi di dati da un file di flusso

È possibile utilizzare il in GetStream API modo che un dispositivo possa ricevere file di streaming in blocchi di dati di piccole dimensioni, in modo che possa essere utilizzato da quei dispositivi che hanno vincoli sull'elaborazione di blocchi di grandi dimensioni. Per ricevere un intero file di dati, potrebbe essere necessario inviare o ricevere più richieste e risposte fino a quando tutti i blocchi di dati non vengono ricevuti ed elaborati.

GetStream richiesta

Attenersi ai seguenti passaggi per effettuare una richiesta GetStream.

Iscriversi al filtro argomento $aws/things/ThingName/streams/StreamId/data/json “accettato”.
Iscriversi al filtro argomento $aws/things/ThingName/streams/StreamId/rejected/json “rifiutato”.
Pubblicare una richiesta GetStream all'argomento $aws/things/ThingName/streams/StreamId/get/json.
Se la richiesta è stata accettata, il dispositivo riceverà una o più risposte GetStream sul filtro argomento “accettato”. Ogni messaggio di risposta contiene informazioni di base e un payload di dati per un singolo blocco.
Ripetere i passaggi 3 e 4 per ricevere tutti i blocchi di dati. È necessario ripetere questi passaggi se la quantità di dati richiesti è superiore a 128 KB. È necessario programmare il dispositivo per utilizzare più richieste GetStream per ricevere tutti i dati richiesti.
Se la richiesta è stata rifiutata, il dispositivo riceverà la risposta di errore nel filtro argomento “rifiutato”.

Nota

Se sostituisci «json» con «cbor» negli argomenti e nei filtri degli argomenti mostrati, il dispositivo riceverà messaggi in un CBOR formato più compatto di. JSON
AWS IoT MQTTla distribuzione basata su file limita la dimensione di un blocco a 128 KB. Se si effettua una richiesta per un blocco superiore a 128 KB, la richiesta non verrà eseguita correttamente.
È possibile effettuare una richiesta per più blocchi la cui dimensione totale è superiore a 128 KB (ad esempio, se si effettua una richiesta di 5 blocchi da 32 KB ciascuno per un totale di 160 KB di dati). In questo caso, la richiesta non ha esito negativo, ma il dispositivo deve effettuare più richieste per ricevere tutti i dati richiesti. Il servizio invierà blocchi aggiuntivi man mano che il dispositivo effettua richieste aggiuntive. Si consiglia di continuare con una nuova richiesta solo dopo che la risposta precedente è stata correttamente ricevuta ed elaborata.
Indipendentemente dalla dimensione totale dei dati richiesti, è consigliabile programmare il dispositivo per avviare i tentativi quando i blocchi non vengono ricevuti o non vengono ricevuti correttamente.

Una GetStream richiesta tipica è JSON simile all'esempio seguente.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "s": 1,
    "f": 0,
    "l": 4096,
    "o": 2,
    "n": 100,
    "b": "..."
}

[facoltativo] “c” è il campo token client.

Il token client non può superare i 64 byte. Un token client di dimensioni superiori a 64 byte causerà una risposta di errore e un messaggio di errore InvalidRequest.
[facoltativo] “s” è il campo della versione di flusso (un numero intero).

MQTTla distribuzione basata su file applica un controllo di coerenza basato su questa versione richiesta e sull'ultima versione di streaming nel cloud. Se la versione del flusso inviata da un dispositivo in una richiesta GetStream non corrisponde alla versione più recente del flusso nel cloud, il servizio invia una risposta di errore e un messaggio di errore VersionMismatch. In genere, un dispositivo riceve la versione di flusso prevista (più recente) nel set di dati iniziale o nella risposta a DescribeStream.
"f” è l'ID del file di flusso (un numero intero compreso tra 0 e 255).

L'ID del file stream è necessario quando si crea o si aggiorna uno stream utilizzando AWS CLI oSDK. Se un dispositivo richiede un file di flusso con un ID che non esiste, il servizio invia una risposta di errore e un messaggio di errore ResourceNotFound.
"l” è la dimensione del blocco dati in byte (un numero intero compreso tra 256 e 131.072).

Fare riferimento a Crea una bitmap per una richiesta GetStream per istruzioni su come utilizzare i campi bitmap per specificare quale parte del file di flusso verrà restituita nella risposta GetStream. Se un dispositivo specifica una dimensione di blocco fuori intervallo, il servizio invia una risposta di errore e un messaggio di errore BlockSizeOutOfBounds.
[facoltativo] “o” è l'offset del blocco nel file di flusso (un numero intero compreso tra 0 e 98.304).

Fare riferimento a Crea una bitmap per una richiesta GetStream per istruzioni su come utilizzare i campi bitmap per specificare quale parte del file di flusso verrà restituita nella risposta GetStream. Il valore massimo di 98.304 è basato su un limite di dimensioni del file di flusso di 24 MB e 256 byte per la dimensione minima del blocco. Se il valore non viene specificato, viene usato il valore predefinito 0.
[facoltativo] “n” è il numero di blocchi richiesti (un numero intero compreso tra 0 e 98.304).

Il campo “n” specifica (1) il numero di blocchi richiesti, o (2) quando viene utilizzato il campo bitmap (“b”), un limite al numero di blocchi che verranno restituiti dalla richiesta bitmap. Questo secondo utilizzo è facoltativo. Se non è definito, il valore predefinito è 131072/DataBlockSize.
[facoltativo] “b” è una bitmap che rappresenta i blocchi richiesti.

Utilizzando una bitmap, il dispositivo può richiedere blocchi non consecutivi, il che rende più comoda la gestione dei tentativi in seguito a un errore. Fare riferimento a Crea una bitmap per una richiesta GetStream per istruzioni su come utilizzare i campi bitmap per specificare quale parte del file di flusso verrà restituita nella risposta GetStream. Per questo campo, converti la bitmap in una stringa che rappresenta il valore della bitmap in notazione esadecimale. La bitmap deve essere inferiore a 12.288 byte.

Importante

Una delle opzioni "n" o "b" deve essere specificata. Se nessuna delle due opzioni è specificata, la richiesta GetStream potrebbe non essere valida quando la dimensione del file è inferiore a 131072 byte (128 KB).

GetStream risposta

Una GetStream risposta è JSON simile a questo esempio per ogni blocco di dati richiesto.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "f": 0,
    "l": 4096,
    "i": 2,
    "p": "..."
}

"c” è il campo token client. Questo viene restituito se è stato dato nella richiesta GetStream. Utilizza il token client per associare la risposta alla sua richiesta.
“f” è l'ID del file di flusso a cui appartiene il payload del blocco di dati corrente.
“l” è la dimensione del payload del blocco dati in byte.
“i” è l'ID del blocco di dati contenuto nel payload. I blocchi di dati sono numerati a partire da 0.
“p” contiene il payload del blocco dati. Questo campo è una stringa, che rappresenta il valore del blocco di dati in codifica Base64.

Crea una bitmap per una richiesta GetStream

È possibile utilizzare il campo bitmap (b) in una richiesta GetStream per ottenere blocchi non consecutivi da un file di flusso. Questo aiuta i dispositivi con RAM capacità limitata a gestire i problemi di distribuzione della rete. Un dispositivo può richiedere solo i blocchi che non sono stati ricevuti o non sono stati ricevuti correttamente. La bitmap determina quali blocchi del file di flusso verranno restituiti. Per ogni bit impostato su 1 nella bitmap, verrà restituito un blocco corrispondente del file di flusso.

Di seguito è riportato un esempio di come specificare una bitmap e i relativi campi di supporto in una richiesta GetStream. Ad esempio, desideri ricevere un file di flusso in blocchi di 256 byte (la dimensione del blocco). Pensa a ogni blocco di 256 byte come a un numero che specifica la sua posizione nel file, a partire da 0. Quindi il blocco 0 è il primo blocco di 256 byte nel file, il blocco 1 è il secondo e così via. Desideri richiedere i blocchi 20, 21, 24 e 43 dal file.

Offset di blocco

Poiché il primo blocco è il numero 20, specifica l'offset (campo o) come 20 per risparmiare spazio nella bitmap.

Numero di blocchi

Per garantire che il dispositivo non riceva più blocchi di quanti ne possa gestire con risorse di memoria limitate, è possibile specificare il numero massimo di blocchi da restituire in ogni messaggio inviato tramite recapito MQTT basato su file. Tieni presente che questo valore viene ignorato se la bitmap stessa specifica un numero inferiore a questo numero di blocchi o se la dimensione totale dei messaggi di risposta inviati tramite la consegna MQTT basata su file supera il limite di servizio di 128 KB per richiesta. GetStream

Bitmap di blocco

La bitmap stessa è una matrice di byte non firmati espressi in notazione esadecimale e inclusi nella richiesta GetStream come rappresentazione della stringa del numero. Ma per costruire questa stringa, iniziamo pensando alla bitmap come una lunga sequenza di bit (un numero binario). Se un bit in questa sequenza è impostato su 1, il blocco corrispondente dal file di flusso verrà inviato nuovamente al dispositivo. Per questo esempio, vogliamo ricevere i blocchi 20, 21, 24 e 43, quindi dobbiamo impostare i bit 20, 21, 24 e 43 nella nostra bitmap. Possiamo usare l'offset del blocco per risparmiare spazio, quindi dopo aver sottratto l'offset da ogni numero di blocco, vogliamo impostare i bit 0, 1, 4 e 23, come nell'esempio seguente.


 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1

Prendendo un byte (8 bit) alla volta, questo è convenzionalmente scritto come: “0b00010011”, “0b00000000” e “0b10000000”. Il bit 0 viene visualizzato nella nostra rappresentazione binaria alla fine del primo byte e il bit 23 all'inizio dell'ultimo. Questo può creare confusione a meno che non si conoscano le convenzioni. Il primo byte contiene i bit 7-0 (in questo ordine), il secondo byte contiene i bit 15-8, il terzo byte contiene i bit 23-16 e così via. Nella notazione esadecimale, questo si converte in “0x130080”.

Suggerimento

È possibile convertire il binario standard in notazione esadecimale. Prendi quattro cifre binarie alla volta e convertile nel loro equivalente esadecimale. Ad esempio, “0001” diventa “1”, “0011” diventa “3” e così via.

Blocca la suddivisione bitmap per la creazione di una stringa nella richiesta. GetStream

Mettendo tutto insieme, il risultato JSON per la nostra GetStream richiesta è il seguente.


{
    "c" : "1",       
    "s" : 1,         
    "l" : 256,       
    "f" : 1,         
    "o" : 20,        
    "n" : 32,       
    "b" : "130080"
}

"c” è il campo token client.
"s" è la versione del flusso prevista.
“l” è la dimensione del payload del blocco dati in byte.
"f" è l'ID dell'indice del file di origine.
"o" è l'offset del blocco.
"n" è il numero di blocchi.
"b" è la blockId bitmap mancante a partire dall'offset. Questo valore deve essere codificato base64.

Gestione degli errori derivanti dalla consegna AWS IoT MQTT basata su file

Una risposta di errore che viene inviata a un dispositivo per entrambi DescribeStream e GetStream APIs contiene un token client, un codice di errore e un messaggio di errore. Una tipica risposta di errore è simile a quella nell'esempio seguente.


{
    "o": "BlockSizeOutOfBounds", 
    "m": "The block size is out of bounds", 
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380" 
}

“o” è il codice che indica il motivo dell’errore. Consulta i codici di errore più avanti in questa sezione per maggiori dettagli.
“m” è il messaggio di errore che contiene i dettagli dell'errore.
“c” è il campo token client. Questo può essere restituito se è stato dato nella richiesta DescribeStream. Utilizza il token client per associare la risposta alla sua richiesta.

Il campo token client non è sempre incluso in una risposta di errore. Quando il token client fornito nella richiesta non è valido o non è corretto, non viene restituito nella risposta di errore.

Nota

Per compatibilità con le versioni precedenti, i campi nella risposta agli errori potrebbero essere in forma non abbreviata. Ad esempio, il codice di errore potrebbe essere indicato dai campi «code» o «o» e il campo del token client può essere designato dai campi clientToken "" o «c». È consigliabile utilizzare il modulo abbreviazione mostrato sopra.

InvalidTopic: L'MQTTargomento del messaggio di streaming non è valido.
InvalidJson: La richiesta Stream non è un JSON documento valido.
InvalidCbor: La richiesta Stream non è un CBOR documento valido.
InvalidRequest: La richiesta è generalmente identificata come non corretta. Per ulteriori informazioni, vedere il messaggio di errore.
Non autorizzato: La richiesta non è autorizzata ad accedere ai file di dati di flusso nel supporto di archiviazione, come Amazon S3. Per ulteriori informazioni, vedere il messaggio di errore.
BlockSizeOutOfBounds: La dimensione del blocco è fuori intervallo. Fare riferimento alla sezione "distribuzione di file MQTT basata» in AWS IoT Core Service Quotas.
OffsetOutOfBounds: L'offset è fuori intervallo. Fare riferimento alla sezione "distribuzione di file MQTT basata» in AWS IoT Core Service Quotas.
BlockCountLimitExceeded: Il numero dei blocchi di richiesta è fuori intervallo. Fare riferimento alla sezione "distribuzione di file MQTT basata» in AWS IoT Core Service Quotas.
BlockBitmapLimitExceeded: La dimensione della bitmap richiesta è fuori intervallo. Fare riferimento alla sezione "distribuzione di file MQTT basata» in AWS IoT Core Service Quotas.
ResourceNotFound: Il flusso, i file, le versioni del file o i blocchi richiesti non sono stati trovati. Consulta il messaggio di errore per ulteriori dettagli.
VersionMismatch: La versione dello stream nella richiesta non corrisponde alla versione dello stream nella funzionalità di distribuzione dei file MQTT basata. Ciò indica che i dati del flusso sono stati modificati da quando la versione del flusso è stata inizialmente ricevuta dal dispositivo.
ETagMismatch: La S3 ETag nello stream non corrisponde alla versione ETag dell'oggetto S3 più recente.
InternalError: Si è verificato un errore interno nella consegna di file MQTT basata.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Gestisci uno stream

Un esempio di caso d'uso in Free RTOS OTA