AWS IoT
Entwicklerhandbuch

Dokumente des Device Shadow-Service

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

Dokumenteigenschaften

Ein Geräteschatten-Dokument besitzt die folgenden Eigenschaften:

state
desired

Den Sollstatus des Geräts. Anwendungen können in diesen Teil des Dokuments schreiben, um den Status eines Geräts zu aktualisieren, ohne dafür mit einem Gerät direkt verbunden sein zu müssen.

reported

Den gemeldeten Status des Geräts. Geräte schreiben in diesen Teil des Dokuments, um ihren neuen Status zu melden. Anwendungen lesen diesen Teil des Dokuments, um den Status eines Gerätes zu ermitteln.

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 übertragen wurde. Anhand des Zeitstempels in der Nachricht und der Zeitstempel für die einzelnen Attribute im Abschnitt desired (Soll) bzw. reported (gemeldet) kann ein Gerät feststellen, wie alt ein aktualisiertes Element ist, selbst wenn dieses keine interne Uhr besitzt.

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 Syntax des Schattendokuments.

Versioning eines Geräteschattens

Der Device Shadow-Service unterstützt das Versioning zu jeder Aktualisierungsnachricht (sowohl Anfrage als auch Antwort), was bedeutet, dass sich mit jeder Aktualisierung eines Geräteschattens die Versionsnummer des JSON-Dokuments erhöht. 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.

In manchen Fällen kann ein Client den Versionsabgleich umgehen, indem er keine Version sendet.

Client-Token

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 wird eine 400er-Antwort (Bad Request) und die Fehlermeldung Ungültiges Client-Token.

Beispieldokument

Hier sehen Sie ein Beispiel für ein Schattendokument:

{ "state" : { "desired" : { "color" : "RED", "sequence" : [ "RED", "GREEN", "BLUE" ] }, "reported" : { "color" : "GREEN" } }, "metadata" : { "desired" : { "color" : { "timestamp" : 12345 }, "sequence" : { "timestamp" : 12345 } }, "reported" : { "color" : { "timestamp" : 12345 } } }, "version" : 10, "clientToken" : "UniqueClientToken", "timestamp": 123456789 }

Leere Abschnitte

Ein Schattendokument enthält nur dann einen Abschnitt desired (Soll), wenn es über einen Sollstatus verfügt. Das folgende Dokument ist ein gültiges Statusdokument ohne einen Abschnitt desired (Soll):

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

Der Abschnitt reported (gemeldet) kann auch leer sein:

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

Sorgt eine Aktualisierung dafür, dass der Abschnitt desired (Soll) bzw. der Abschnitt reported (gemeldet) ungültig wird, wird der Abschnitt aus dem Dokument entfernt. Um den Abschnitt desired (Soll) aus einen Dokument zu entfernen (z. B. in Reaktion auf eine Statusaktualisierung eines Geräts), stellen Sie den Abschnitt "Soll” aufnull (Null) ein:

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

Es ist auch möglich, dass ein Schattendokument keinen Abschnitt desired (Soll) bzw. reported (gemeldet) enthält. In diesem Fall ist das Schattendokument leer. Dies ist beispielsweise ein gültiges Dokument:

{ }

Arrays

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" ] } }