Dokumente des Device Shadow-Services - AWS IoT

Dokumente des Device Shadow-Services

Der Device Shadow-Service befolgt alle Regeln der JSON-Spezifikation. Werte, Objekte und Arrays werden im Geräteschatten-Dokument gespeichert.

Beispiele für Schatten-Dokumente

Der Device Shadow-Service verwendet bei den Operationen UPDATE, GET und DELETE mithilfe der REST-API oder MQTT- Pub/Sub-Nachrichten die folgenden Dokumente.

Anfragestatusdokument

Ein Anfragestatusdokument hat das folgende Format:

{ "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer1, "attribute2": "string1", ... "attributeN": boolean1 } }, "clientToken": "token", "version": version }
  • state — Aktualisierungen betreffen lediglich die angegebenen Felder. In der Regel verwenden Sie entweder die desired- oder die reported-Eigenschaft, aber nicht beide, in derselben Anforderung.

    • desired: Die Statuseigenschaften und -werte, die im Gerät aktualisiert werden sollen.

    • reported — Die vom Gerät gemeldeten Zustandseigenschaften und -werte.

  • clientToken: Wenn diese Option verwendet wird, können Sie die Anforderung und die entsprechende Antwort durch das Client-Token abgleichen.

  • version — Bei Verwendung verarbeitet der Device Shadow-Service nur dann die Aktualisierung, wenn die angegebene Version mit seiner neuesten Version übereinstimmt.

Antwortstatusdokumente

Antwortstatusdokumente haben je nach Antworttyp das folgende Format.

Antwortstatusdokument „/accepted“

{ "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "timestamp": timestamp, "clientToken": "token", "version": version }

Antwortstatusdokument „/delta“

{ "state": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 } }, "metadata": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "timestamp": timestamp, "clientToken": "token", "version": version }

Antwortstatusdokument „/documents“

{ "previous" : { "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer1, "attribute2": "string1", ... "attributeN": boolean1 } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "reported": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "version": version-1 }, "current": { "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "reported": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "version": version }, "timestamp": timestamp, "clientToken": "token" }

Eigenschaften des Antwortstatusdokuments

  • previous: Nach einer erfolgreichen Aktualisierung enthält state das Objekt vor dem Update.

  • current: Nach einer erfolgreichen Aktualisierung enthält das state Objekt nach der Aktualisierung.

  • state

    • reported — Liegt nur dann vor, wenn ein Objekt Daten im reported-Abschnitt gemeldet hat, und enthält nur Felder, die im Anfragestatusdokument enthalten waren.

    • desired — Liegt nur dann vor, wenn ein Gerät Daten im desired-Abschnitt gemeldet hat, und enthält nur Felder, die im Anfragestatusdokument enthalten waren.

    • delta — Liegt nur dann vor, wenn sich die desired-Daten von den aktuellen reported-Daten des Schattens unterscheiden.

  • metadata — Enthält für jedes Attribut in den Abschnitten desired (Soll) und reported (gemeldet) die Zeitstempel, sodass Sie feststellen können, wann der Status aktualisiert wurde.

  • timestamp — Das Epoche-Datum und die Epoche-Uhrzeit, zu der die Antwort mittels AWS IoT erzeugt wurde.

  • clientToken — Liegt nur dann vor, wenn bei der Veröffentlichung einer gültigen JSON im Thema /update (/Aktualisierung) ein Client-Token verwendet wurde.

  • version — Die aktuelle Versionsnummer des Dokuments für den Geräteschatten, der in AWS IoT freigegeben wird. Sie erhöht sich zur vorherigen Versionsnummer des Dokuments um die Zahl eins.

Fehlerantwortdokument

Ein Fehlerantwortdokument hat das folgende Format:

{ "code": error-code, "message": "error-message", "timestamp": timestamp, "clientToken": "token" }
  • code — Einen HTTP-Antwortcode, der auf die Art des Fehlers hinweist.

  • message — Eine Textnachricht mit zusätzlichen Informationen.

  • timestamp — Das Datum und Uhrzeit, zu der die Antwort mittels AWS IoT erzeugt wurde. Diese Eigenschaft ist nicht in allen Fehlerantwortdokumenten vorhanden.

  • clientToken — Liegt nur dann vor, wenn ein Client-Token in der veröffentlichten Nachricht verwendet wurde.

Weitere Informationen finden Sie unter Device Shadow-Fehlermeldungen.

Antwortdokument für die Schattennamenliste

Ein Antwortdokument für die Schattennamenliste hat das folgende Format:

{ "results": [ "shadowName-1", "shadowName-2", "shadowName-3", "shadowName-n" ], "nextToken": "nextToken", "timestamp": timestamp }
  • results — Das Array von Schattennamen.

  • nextToken — Der Token-Wert, der in nach Seiten organisierten Anforderungen verwendet wird, um die nächste Seite in der Sequenz abzurufen. Diese Eigenschaft ist nicht vorhanden, wenn keine weiteren Schattennamen zurückgegeben werden sollen.

  • timestamp — Das Datum und Uhrzeit, zu der die Antwort mittels AWS IoT erzeugt wurde.

Dokumenteigenschaften

Ein Geräteschatten-Dokument besitzt die folgenden Eigenschaften:

state
desired

Den gewünschte Status des Geräts. Anwendungen können in diesen Teil des Dokuments schreiben, um den Status eines Geräts zu aktualisieren, ohne direkt mit diesem verbunden sein zu müssen.

reported

Der gemeldete Status des Geräts. Geräte schreiben in diesen Teil des Dokuments, um ihren neuen Status zu melden. Apps lesen diesen Teil des Dokuments, um den zuletzt gemeldeten Zustand des Geräts zu bestimmen.

metadata

Informationen über die im Abschnitt state (Status) des Dokuments gespeicherten Daten. Dazu zählen Zeitstempel, in Epoche-Uhrzeit, für das jeweilige Attribut im Abschnitt state (Status), anhand derer Sie den Zeitpunkt ermitteln können, zu dem sie aktualisiert wurden.

Anmerkung

Metadaten zählen nicht zur Dokumentengröße für Service Limits oder Preise. Weitere Informationen finden Sie unter Service Limits AWS IoT.

timestamp

Gibt an, wann die Nachricht von AWS IoT gesendet wurde. Durch Verwendung des Zeitstempels in der Nachricht und der Zeitstempel für einzelne Attribute im Abschnitt desired oder reported kann ein Gerät das Alter einer Eigenschaft bestimmen, selbst wenn das Gerät über keine interne Uhr verfügt.

clientToken

Eine für das Gerät einmalige Zeichenfolge, die es Ihnen ermöglicht, Anfragen in einer MQTT-Umgebung Antworten zuzuordnen.

version

Die Dokumentversion. Jedes Mal, wenn das Dokument aktualisiert wird, erhöht sich diese Versionsnummer. Wird verwendet, um sicherzustellen, dass die Versionsnummer des aktualisierten Dokuments die neueste ist.

Weitere Informationen finden Sie unter Beispiele für Schatten-Dokumente.

Delta-Status

Der Delta-Status ist ein virtueller Typ eines Status, in dem der Unterschied zwischen dem Status desired (Soll) Status und dem Status reported (gemeldet) enthalten ist. Felder im Abschnitt desired (Soll), die nicht im Abschnitt reported (gemeldet) enthalten sind, sind im Delta enthalten. Felder, die im Abschnitt reported (gemeldet) und nicht im Abschnitt desired (Soll) enthalten sind, sind nicht im Delta enthalten. Das Delta enthält Metadaten und seine Werte entsprechen den Metadaten im Feld desired (Soll). Beispiel:

{ "state": { "desired": { "color": "RED", "state": "STOP" }, "reported": { "color": "GREEN", "engine": "ON" }, "delta": { "color": "RED", "state": "STOP" } }, "metadata": { "desired": { "color": { "timestamp": 12345 }, "state": { "timestamp": 12345 }, "reported": { "color": { "timestamp": 12345 }, "engine": { "timestamp": 12345 } }, "delta": { "color": { "timestamp": 12345 }, "state": { "timestamp": 12345 } } }, "version": 17, "timestamp": 123456789 } }

Wenn die verschachtelten Objekte differieren, enthält das Delta den Pfad bis hin zum Stammverzeichnis.

{ "state": { "desired": { "lights": { "color": { "r": 255, "g": 255, "b": 255 } } }, "reported": { "lights": { "color": { "r": 255, "g": 0, "b": 255 } } }, "delta": { "lights": { "color": { "g": 255 } } } }, "version": 18, "timestamp": 123456789 }

Der Device Shadow-Service berechnet das Delta, indem er jedes einzelne Feld im Status desired (Soll) durchläuft und mit dem Status reported (gemeldet) abgleicht.

Arrays werden wie Werte behandelt. Stimmt ein Array im Abschnitt desired (Soll) nicht mit dem Array im Abschnitt reported (gemeldet) überein, dann wird das gesamte "Soll”-Array in das Delta kopiert.

Versioning von Schattendokumenten

Der Device Shadow-Service unterstützt das Versioning für jede Aktualisierungsnachricht, sowohl Anforderung als auch Antwort. Dies bedeutet, dass bei jeder Aktualisierung eines Schattens die Version des JSON-Dokuments erhöht wird. Dies gewährleistet Folgendes:

  • Ein Client kann eine Fehlermeldung empfangen, wenn versucht wird, einen Schatten mit einer älteren Versionsnummer zu überschreiben. Der Client wurde darüber informiert, dass eine neue Synchronisation erfolgen muss, bevor ein Geräteschatten aktualisiert werden kann.

  • Ein Client kann entscheiden, bei einer erhaltenen Nachricht nicht tätig zu werden, wenn die Nachricht über eine niedrigere Version verfügt als die vom Client gespeicherte Version.

Ein Client kann den Versionsabgleich umgehen, indem er keine Version in das Schattendokument aufnimmt.

Client-Tokens in Schattendokumenten

Bei MQTT-basiertem Messaging können Sie einen Client-Token verwenden, um zu überprüfen, ob derselbe Client-Token in einer Anfrage und Antwort auf eine Anfrage enthalten ist. Dies stellt sicher, dass Antwort und Anfrage miteinander verknüpft sind.

Anmerkung

Das Client-Token darf nicht länger als 64 Bytes sein. Ein Client-Token, das länger als 64 Bytes ist, verursacht eine 400er-Antwort (Bad Request) und die Fehlermeldung Invalid clientToken (Ungültiges Client-Token).

Eigenschaften des leeren Schattendokuments

Die Eigenschaften reported und desired in einem Schattendokument können leer sein oder weggelassen werden, wenn sie nicht für den aktuellen Schattenstatus gelten. Ein Schattendokument enthält beispielsweise nur dann eine desired-Eigenschaft, wenn es einen gewünschten Status hat. Der folgende Code ist ein gültiges Beispiel für ein Statusdokument ohne desired-Eigenschaft:

{ "reported" : { "temp": 55 } }

Die reported-Eigenschaft kann auch leer sein, z. B. wenn der Schatten nicht vom Gerät aktualisiert wurde:

{ "desired" : { "color" : "RED" } }

Wenn eine Aktualisierung bewirkt, dass die Eigenschaft desired oder reported null wird, wird diese aus dem Dokument entfernt. Nachfolgend wird gezeigt, wie Sie die desired-Eigenschaft entfernen, indem Sie sie auf null festlegen. Sie können dies beispielsweise tun, wenn ein Gerät seinen Status aktualisiert.

{ "state": { "reported": { "color": "red" }, "desired": null } }

Ein Schattendokument kann auch keine desired- oder reported-Eigenschaft haben, wodurch das Schattendokument leer wird. Dies ist ein Beispiel für ein leeres, aber gültiges Schattendokument.

{ }

Array-Werte in Schattendokumenten

Schatten unterstützen zwar Arrays, können diese jedoch so als normale Werte behandeln, dass bei einer Aktualisierung eines Arrays das gesamte Array ersetzt wird. Es ist nicht möglich, einen Teil eines Arrays zu aktualisieren.

Ursprungszustand:

{ "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] } }

Aktualisieren:

{ "desired" : { "colors" : ["RED"] } }

Endzustand:

{ "desired" : { "colors" : ["RED"] } }

Arrays können keine Null-Werte besitzen. Das folgende Array ist z. B. ungültig und wird abgelehnt.

{ "desired" : { "colors" : [ null, "RED", "GREEN" ] } }