Verwendung der AWS IoT MQTT-basierten Dateibereitstellung auf Geräten

Um den Datenübertragungsprozess einzuleiten, muss ein Gerät einen ersten Datensatz erhalten, der mindestens eine Stream-ID enthält. Sie können einen Aufträge verwenden, um Datenübertragungsaufgaben für Ihre Geräte zu planen, indem Sie den ursprünglichen Datensatz in das Auftragsdokument aufnehmen. Wenn ein Gerät den ersten Datensatz empfängt, sollte es dann die Interaktion mit der AWS IoT MQTT-basierten Dateiübertragung starten. Um Daten mit AWS IoT MQTT-basierter Dateibereitstellung auszutauschen, sollte ein Gerät:

• Verwenden Sie das MQTT-Protokoll, um Themen der MQTT-basierten Dateiübertragung zu abonnieren.

• Senden Sie Anforderungen und warten Sie dann, bis Sie die Antworten mithilfe von MQTT-Nachrichten erhalten.

Sie können optional eine Stream-Datei-ID und eine Stream-Version in den ursprünglichen Datensatz aufnehmen. Das Senden einer Stream-Datei-ID an ein Gerät kann die Programmierung der Firmware/Software des Geräts vereinfachen, da dadurch keine DescribeStream-Anforderung vom Gerät gestellt werden muss, um diese ID zu erhalten. Das Gerät kann die Stream-Version in einer GetStream-Anforderung angeben, um eine Konsistenzprüfung zu erzwingen, falls der Stream unerwartet aktualisiert wurde.

Wird verwendet, um DescribeStream Stream-Daten abzurufen

AWS IoT Die MQTT-basierte Dateibereitstellung stellt die DescribeStream API zum Senden von Stream-Daten an ein Gerät bereit. Die von dieser API zurückgegebenen Stream-Daten umfassen die Stream-ID, die Stream-Version, die Stream-Beschreibung und eine Liste von Stream-Dateien, von denen jede eine Datei-ID und die Dateigröße in Byte hat. Mit diesen Informationen kann ein Gerät beliebige Dateien auswählen, um den Datenübertragungsprozess einzuleiten.

Anmerkung

Sie müssen die DescribeStream-API nicht verwenden, wenn Ihr Gerät alle erforderlichen Stream-Datei-IDs im ursprünglichen Datensatz empfängt.

Führen Sie diese Schritte aus, um eine DescribeStream-Anforderung zu stellen.

1. Abonnieren Sie den „Akzeptiert“-Themenfilter $aws/things/ThingName/streams/StreamId/description/json.

2. Abonnieren Sie den „Abgelehnt“-Themenfilter $aws/things/ThingName/streams/StreamId/rejected/json.

3. Veröffentlichen Sie eine DescribeStream-Anforderung, indem Sie eine Nachricht an $aws/things/ThingName/streams/StreamId/describe/json senden.

4. Wenn die Anforderung akzeptiert wurde, erhält Ihr Gerät eine DescribeStream-Antwort auf den Themenfilter „Akzeptiert“.

5. Wenn die Anforderung abgelehnt wurde, erhält Ihr Gerät die Fehlerantwort im Themenfilter „Abgelehnt“.

Anmerkung

Wenn Sie in den angezeigten Themen und Themenfiltern json durch cbor ersetzen, empfängt Ihr Gerät Nachrichten im CBOR-Format, das kompakter als JSON ist.

DescribeStream Anfrage

Eine typische DescribeStream-JSON-Anforderung sieht wie im folgenden Beispiel aus.

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

• (Optional) „c“ ist das Feld für das Client-Token.

  Das Client-Token darf nicht länger als 64 Bytes sein. Ein Client-Token, das länger als 64 Byte ist, verursacht eine Fehlerantwort und eine InvalidRequest-Fehlermeldung.

DescribeStream Antwort

Eine DescribeStream-Antwort in JSON ähnelt dem folgenden Beispiel.

{
    "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“ ist das Feld für das Client-Token. Es wird zurückgegeben, wenn es in der DescribeStream-Anforderung angegeben wurde. Verwenden Sie das Client-Token, um die Antwort der Anforderung zuzuordnen.

• "s" ist die Stream-Version als Ganzzahl. Sie können diese Version verwenden, um eine Konsistenzprüfung mit Ihren GetStream Anfragen durchzuführen.

• „r“ enthält eine Liste der Dateien im Stream.

  • „f“ ist die Stream-Datei-ID als Ganzzahl.

  • „z“ ist die Größe der Stream-Datei in Byte.

• „d“ enthält die Beschreibung des Streams.

Abrufen von Datenblöcken aus einer Stream-Datei

Sie können die GetStream-API verwenden, damit ein Gerät Stream-Dateien in kleinen Datenblöcken empfangen kann, sodass sie von Geräten verwendet werden kann, die Einschränkungen bei der Verarbeitung großer Blockgrößen haben. Um eine komplette Datendatei zu empfangen, muss ein Gerät möglicherweise mehrere Anforderungen und Antworten senden oder empfangen, bis alle Datenblöcke empfangen und verarbeitet sind.

GetStream Anfrage

Führen Sie diese Schritte aus, um eine GetStream-Anforderung zu stellen.

1. Abonnieren Sie den „Akzeptiert“-Themenfilter $aws/things/ThingName/streams/StreamId/data/json.

2. Abonnieren Sie den „Abgelehnt“-Themenfilter $aws/things/ThingName/streams/StreamId/rejected/json.

3. Veröffentlichen Sie eine GetStream-Anforderung zum Thema $aws/things/ThingName/streams/StreamId/get/json.

4. Wenn die Anforderung akzeptiert wurde, erhält Ihr Gerät eine oder mehrere GetStream Antworten auf den Themenfilter „Akzeptiert“. Jede Antwortnachricht enthält grundlegende Informationen und Nutzlastdaten für einen einzelnen Block.

5. Wiederholen Sie die Schritte 3 und 4, um alle Datenblöcke zu empfangen. Sie müssen diese Schritte wiederholen, wenn die angeforderte Datenmenge mehr als 128 KB beträgt. Sie müssen Ihr Gerät so programmieren, dass es mehrere GetStream-Anforderungen verwendet, damit alle angeforderten Daten empfangen werden.

6. Wenn die Anforderung abgelehnt wurde, erhält Ihr Gerät die Fehlerantwort im Themenfilter „Abgelehnt“.

Anmerkung

• Wenn Sie in den angezeigten Themen und Themenfiltern „json“ durch „cbor“ ersetzen, empfängt Ihr Gerät Nachrichten im CBOR-Format, das kompakter als das JSON-Format ist.

• AWS IoT Die MQTT-basierte Dateizustellung begrenzt die Größe eines Blocks auf 128 KB. Wenn Sie eine Anforderung für einen Block stellen, der mehr als 128 KB groß ist, schlägt die Anforderung fehl.

• Sie können eine Anforderung für mehrere Blöcke stellen, deren Gesamtgröße größer als 128 KB ist (wenn Sie beispielsweise eine Anforderung für 5 Blöcke mit jeweils 32 KB für insgesamt 160 KB an Daten stellen). In diesem Fall schlägt die Anfrage nicht fehl, aber Ihr Gerät muss mehrere Anfragen stellen, um alle angeforderten Daten zu erhalten. Der Service sendet zusätzliche Blöcke, wenn Ihr Gerät zusätzliche Anforderungen stellt. Wir empfehlen Ihnen, erst dann mit einer neuen Anforderungen fortzufahren, wenn die vorherige Antwort korrekt empfangen und verarbeitet wurde.

• Unabhängig von der Gesamtgröße der angeforderten Daten sollten Sie Ihr Gerät so programmieren, dass es Wiederholungsversuche einleitet, wenn Blöcke nicht oder nicht korrekt empfangen werden.

Eine typische GetStream-JSON-Anforderung sieht wie im folgenden Beispiel aus.

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

• [optional] „c“ ist das Feld für das Client-Token.

  Das Client-Token darf nicht länger als 64 Bytes sein. Ein Client-Token, das länger als 64 Byte ist, verursacht eine Fehlerantwort und eine InvalidRequest-Fehlermeldung.

• [optional] „s“ ist das Feld für die Stream-Version (eine Ganzzahl).

  Bei der MQTT-basierten Dateibereitstellung wird eine Konsistenzprüfung durchgeführt, die auf dieser angeforderten Version und der neuesten Stream-Version in der Cloud basiert. Wenn die von einem Gerät in einer GetStream-Anforderung gesendete Stream-Version nicht mit der neuesten Stream-Version in der Cloud übereinstimmt, sendet der Service eine Fehlerantwort und eine VersionMismatch-Fehlermeldung. In der Regel empfängt ein Gerät die erwartete (neueste) Stream-Version im ursprünglichen Datensatz oder in der Antwort auf DescribeStream.

• „f“ ist die Stream-Datei-ID (eine Ganzzahl im Bereich von 0 bis 255).

  Die Stream-Datei-ID ist erforderlich, wenn Sie einen Stream mit dem AWS CLI oder SDK erstellen oder aktualisieren. Wenn ein Gerät eine Stream-Datei mit einer ID anfordert, die nicht existiert, sendet der Service eine Fehlerantwort und eine ResourceNotFound-Fehlermeldung.

• „l“ ist die Datenblockgröße in Byte (eine Ganzzahl im Bereich von 256 bis 131.072).

  Informationen zu Erstellen Sie eine Bitmap für eine Anfrage GetStream für Anweisungen, wie die Bitmap-Felder verwendet werden, um festzulegen, welcher Teil der Stream-Datei in der GetStream-Antwort zurückgegeben werden soll. Wenn ein Gerät eine Blockgröße angibt, die außerhalb des zulässigen Bereichs liegt, sendet der Service eine Fehlerantwort und eine BlockSizeOutOfBounds-Fehlermeldung.

• [optional] „o“ ist der Offset des Blocks in der Stream-Datei (eine Ganzzahl im Bereich von 0 bis 98.304).

  Informationen zu Erstellen Sie eine Bitmap für eine Anfrage GetStream für Anweisungen, wie die Bitmap-Felder verwendet werden, um festzulegen, welcher Teil der Stream-Datei in der GetStream-Antwort zurückgegeben werden soll. Der Höchstwert von 98.304 basiert auf einer Größenbeschränkung von 24 MB für Stream-Dateien und 256 Byte für die minimale Blockgröße. Wenn nichts angegeben ist, beträgt der Standardwert 0.

• [optional] „n“ ist die Anzahl der angeforderten Blöcke (eine Ganzzahl im Bereich von 0 bis 98.304).

  Das Feld „n“ gibt entweder (1) die Anzahl der angeforderten Blöcke oder (2), wenn das Bitmap-Feld („b“) verwendet wird, eine Obergrenze für die Anzahl der Blöcke an, die von der Bitmap-Anforderung zurückgegeben werden. Diese zweite Verwendung ist optional. Wenn nicht definiert, ist sie standardmäßig DataBlockSize131072/.

• [optional] „b“ ist eine Bitmap, welche die angeforderten Blöcke darstellt.

  Mithilfe einer Bitmap kann Ihr Gerät nicht aufeinanderfolgende Blöcke anfordern, was die Handhabung von Wiederholungsversuchen nach einem Fehler komfortabler macht. Informationen zu Erstellen Sie eine Bitmap für eine Anfrage GetStream für Anweisungen, wie die Bitmap-Felder verwendet werden, um festzulegen, welcher Teil der Stream-Datei in der GetStream-Antwort zurückgegeben werden soll. Konvertieren Sie für dieses Feld die Bitmap in eine Zeichenfolge, die den Bitmap-Wert in hexadezimaler Schreibweise darstellt. Die Bitmap muss kleiner als 12.288 Byte sein.

Wichtig

Entweder „n“ oder „b“ sollte angegeben werden. Wenn keines von beiden festgelegt wurde, ist die GetStream Anforderung möglicherweise nicht gültig, wenn die Dateigröße weniger als 131.072 Byte (128 KB) beträgt.

GetStream Antwort

Eine GetStream-Antwort in JSON sieht für jeden angeforderten Datenblock wie in diesem Beispiel aus.

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

• „c“ ist das Feld für das Client-Token. Es wird zurückgegeben, wenn es in der GetStream-Anforderung angegeben wurde. Verwenden Sie das Client-Token, um die Antwort der Anforderung zuzuordnen.

• „f“ ist die ID der Stream-Datei, zu der die aktuelle Datenblock-Nutzlast gehört.

• „l“ ist die Größe der Datenblock-Nutzlast in Byte.

• „i“ ist die ID des Datenblocks, der in der Nutzlast enthalten ist. Datenblöcke werden beginnend mit 0 durchnummeriert.

• „p“ enthält die Nutzlast des Datenblocks. Dieses Feld ist eine Zeichenfolge, die den Wert des Datenblocks in Base64-Kodierung darstellt.

Erstellen Sie eine Bitmap für eine Anfrage GetStream

Sie können das Bitmap-Feld (b) in einer GetStream-Anforderung verwenden, um nicht aufeinanderfolgende Blöcke aus einer Stream-Datei abzurufen. Dies hilft Geräten mit begrenzter RAM-Kapazität, Probleme mit der Netzwerkbereitstellung zu lösen. Ein Gerät kann nur die Blöcke anfordern, die nicht oder nicht korrekt empfangen wurden. Die Bitmap bestimmt, welche Blöcke der Stream-Datei zurückgegeben werden. Für jedes Bit, das in der Bitmap auf 1 festgelegt ist, wird ein entsprechender Block der Stream-Datei zurückgegeben.

Hier sehen Sie ein Beispiel für die Angabe einer Bitmap und ihrer unterstützenden Felder in einer GetStream-Anforderung. Sie möchten beispielsweise eine Stream-Datei in Blöcken von 256 Byte (der Blockgröße) empfangen. Stellen Sie sich vor, dass jeder Block mit 256 Byte eine Zahl hat, die seine Position in der Datei angibt, beginnend bei 0. Block 0 ist also der erste Block mit 256 Byte in der Datei, Block 1 der zweite usw. Sie möchten die Blöcke 20, 21, 24 und 43 aus der Datei anfordern.

Block-Offset

Da der erste Block die Nummer 20 hat, geben Sie als Offset (Feld o) 20 an, um Platz in der Bitmap zu sparen.

Anzahl der Blöcke

Um sicherzustellen, dass Ihr Gerät nicht mehr Blöcke empfängt, als es mit begrenzten Speicherressourcen verarbeiten kann, können Sie die maximale Anzahl von Blöcken angeben, die in jeder Nachricht zurückgegeben werden sollen, die per MQTT-basierter Dateibereitstellung gesendet wird. Beachten Sie, dass dieser Wert nicht berücksichtigt wird, wenn die Bitmap selbst weniger als diese Anzahl von Blöcken angibt oder wenn dadurch die Gesamtgröße der per MQTT-basierter Dateibereitstellung gesendeten Antwortnachrichten das Service-Limit von 128 KB pro GetStream-Anforderung überschreiten würde.

Block-Bitmap

Die Bitmap selbst ist ein Array von Bytes ohne Vorzeichen, die in hexadezimaler Schreibweise ausgedrückt und in der GetStream-Anforderung als Zeichenkettendarstellung der Zahl enthalten sind. Aber um diese Zeichenfolge zu konstruieren, stellen wir uns die Bitmap zunächst als eine lange Folge von Bits (eine Binärzahl) vor. Wenn ein Bit in dieser Sequenz auf 1 festgelegt ist, wird der entsprechende Block aus der Stream-Datei an das Gerät zurückgesendet. In unserem Beispiel wollen wir die Blöcke 20, 21, 24 und 43 empfangen, also müssen wir die Bits 20, 21, 24 und 43 in unserer Bitmap setzen. Wir können den Block-Offset verwenden, um Platz zu sparen. Nachdem wir also den Offset von jeder Blocknummer subtrahiert haben, möchten wir die Bits 0, 1, 4 und 23 wie im folgenden Beispiel setzen.

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

Wenn wir jeweils ein Byte (8 Bit) nehmen, wird dies üblicherweise wie folgt geschrieben: „0b00010011“, „0b00000000“ und „0b10000000“. Bit 0 erscheint in unserer binären Darstellung am Ende des ersten Bytes und Bit 23 am Anfang des letzten Bytes. Das kann verwirrend sein, es sei denn, Sie kennen die Konventionen. Das erste Byte enthält die Bits 7-0 (in dieser Reihenfolge), das zweite Byte enthält die Bits 15-8, das dritte Byte enthält die Bits 23-16 und so weiter. In hexadezimaler Schreibweise wird dies in „0x130080“ umgewandelt.

Tipp

Sie können die standardmäßige Binärschreibweise in die hexadezimale Schreibweise konvertieren. Nehmen Sie jeweils vier Binärziffern und konvertieren Sie diese in ihre hexadezimale Entsprechung. Zum Beispiel wird aus „0001“ „1“, aus „0011“ wird „3“ und so weiter.

Zusammengenommen sieht das JSON für unsere GetStream-Anforderung wie folgt aus.

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

• „c“ ist das Feld für das Client-Token.

• „s“ ist die erwartete Stream-Version.

• „l“ ist die Größe der Datenblock-Nutzlast in Byte.

• „f“ ist die ID des Quelldatei-Indexes.

• „o“ ist der Block-Offset.

• „n“ ist die Anzahl der Blöcke.

• „b“ ist die fehlende blockId-Bitmap, beginnend mit dem Offset. Dieser Wert muss based64-codiert sein.

Behandlung von Fehlern bei der AWS IoT MQTT-basierten Dateizustellung

Eine Fehlerantwort, die sowohl für APIs als auch DescribeStream für GetStream-APIs an ein Gerät gesendet wird, enthält ein Client-Token, einen Fehlercode und eine Fehlermeldung. Eine typische Fehlerantwort sieht wie im folgenden Beispiel aus.

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

• „o“ ist der Fehlercode, der den Grund anzeigt, warum ein Fehler aufgetreten ist. Weitere Informationen finden Sie in den Fehlercodes weiter unten in diesem Abschnitt.

• „m“ ist die Fehlermeldung, die Einzelheiten des Fehlers anzeigt.

• „c“ ist das Feld für das Client-Token. Dies kann zurückgegeben werden, wenn es in der DescribeStream-Anforderung angegeben wurde. Sie können das Client-Token verwenden, um die Antwort der Anforderung zuzuordnen.

  Das Client-Token-Feld ist nicht immer in einer Fehlerantwort enthalten. Wenn das in der Anforderung angegebene Client-Token nicht gültig oder falsch formatiert ist, wird es in der Fehlerantwort nicht zurückgegeben.

Anmerkung

Aus Gründen der Abwärtskompatibilität können Felder in der Fehlerantwort nicht abgekürzt sein. Beispielsweise kann der Fehlercode entweder durch die Felder „Code“ oder „o“ und das Client-Token-Feld entweder durch die Felder „clientToken“ oder „c“ gekennzeichnet werden. Wir empfehlen Ihnen, die oben abgebildete Abkürzungsform zu verwenden.

InvalidTopic

Das MQTT-Thema der Stream-Nachricht ist ungültig.

InvalidJson

Die Stream-Anforderung ist kein gültiges JSON-Dokument.

InvalidCbor

Die Stream--Anforderung ist kein gültiges CBOR-Dokument.

InvalidRequest

Die Anforderung wird im Allgemeinen als falsch formatiert identifiziert. Weitere Informationen finden Sie in der Fehlermeldung.

Nicht autorisiert

Die Anforderung ist nicht berechtigt, auf die Stream-Daten-Dateien auf dem Speichermedium wie Amazon S3 zuzugreifen. Weitere Informationen finden Sie in der Fehlermeldung.

BlockSizeOutOfBounds

Die Blockgröße liegt außerhalb der Grenzen. Weitere Informationen finden Sie im Abschnitt „MQTT-basierte Dateibereitstellung“ unter AWS IoT Core Service Quotas.

OffsetOutOfBounds

Der Offset liegt außerhalb der Grenzen. Weitere Informationen finden Sie im Abschnitt „MQTT-basierte Dateibereitstellung“ unter AWS IoT Core Service Quotas.

BlockCountLimitExceeded

Die Anzahl der Anforderungsblöcke ist außerhalb des zulässigen Bereichs. Weitere Informationen finden Sie im Abschnitt „MQTT-basierte Dateibereitstellung“ unter AWS IoT Core Service Quotas.

BlockBitmapLimitExceeded

Die Größe der Anforderungsbitmap liegt außerhalb des gültigen Bereichs. Weitere Informationen finden Sie im Abschnitt „MQTT-basierte Dateibereitstellung“ unter AWS IoT Core Service Quotas.

ResourceNotFound

Der angeforderte Stream, die Dateien, Dateiversionen oder Blöcke wurden nicht gefunden. Weitere Details und Informationen finden Sie in der Fehlermeldung.

VersionMismatch

Die Stream-Version in der Anforderung stimmt nicht mit der Stream-Version in der MQTT-basierten Dateibereitstellung überein. Dies weist darauf hin, dass die Stream-Daten seit dem ersten Empfang der Stream-Version durch das Gerät geändert wurden.

E TagMismatch

Das S3-ETag im Stream stimmt nicht mit dem ETag der neuesten S3-Objektversion überein.

InternalError

Bei der MQTT-basierten Dateibereitstellung ist ein interner Fehler aufgetreten.