Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # 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. **Topics** + [Beispiele für Schatten-Dokumente](#device-shadow-document-syntax) + [Dokumenteigenschaften](#document-structure) + [Delta-Status](#delta-state) + [Versioning von Schattendokumenten](#versioning) + [Client-Tokens in Schattendokumenten](#client-token) + [Eigenschaften des leeren Schattendokuments](#device-shadow-empty-fields) + [Array-Werte in Schattendokumenten](#device-shadow-arrays) ## Beispiele für Schatten-Dokumente Der Device Shadow-Dienst verwendet diese Dokumente in UPDATE-, GET- und DELETE-Vorgängen mithilfe der [REST-API](device-shadow-rest-api.md) oder [ Pub/Sub MQTT-Nachrichten](device-shadow-mqtt.md). **Topics** + [Anfragestatusdokument](#device-shadow-example-request-json) + [Antwortstatusdokumente](#device-shadow-example-response-json) + [Fehlerantwortdokument](#device-shadow-example-error-json) + [Antwortdokument für die Schattennamenliste](#device-shadow-list-json) ### 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, deren Aktualisierung im Gerät angefordert wurde. + `reported` – Die vom Gerät gemeldeten Zustandseigenschaften und -werte. + `clientToken` – Falls verwendet, können Sie die Anfrage und die entsprechende Antwort anhand des Client-Tokens 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 } ``` #### /Dokumente, Antwortstatusdokument ``` { "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` – Enthält nach einer erfolgreichen Aktualisierung den `state` des Objekts vor dem Update. + `current` – Enthält nach einer erfolgreichen Aktualisierung den `state` des Objekts nach dem Update. + `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. + `metadata` –`desired` Enthält für jedes Attribut in den Abschnitten und `reported` die Zeitstempel, sodass Sie feststellen können, wann der Status aktualisiert wurde. + `timestamp`— Datum und Uhrzeit der Epoche, zu der die Antwort generiert wurde. AWS IoT + `clientToken` – Liegt nur dann vor, wenn bei der Veröffentlichung einer gültigen JSON im Thema `/update` ein Client-Token verwendet wurde. + `version` – Die aktuelle Version des Dokuments für den Geräteschatten, freigegeben in AWS IoT. 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`— Datum und Uhrzeit der Generierung der Antwort. AWS IoT 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](device-shadow-error-messages.md). ### 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`— Datum und Uhrzeit der Generierung der Antwort AWS IoT. ## Dokumenteigenschaften Ein Geräteschatten-Dokument besitzt die folgenden Eigenschaften: `state` `desired` Den gewünschte Status des Geräts. Anwendungen können diesen Teil des Dokuments beschreiben, um den Status eines Geräts zu aktualisieren, ohne direkt mit diesem verbunden zu sein. `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. Metadaten zählen nicht zur Dokumentengröße für Service Limits oder Preise. Weitere Informationen finden Sie unter [Service Limits AWS IoT](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot). `timestamp` Gibt an, von wann die Nachricht gesendet wurde AWS IoT. 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](#device-shadow-document-syntax). ## 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 Nullwerte besitzen. Das folgende Array ist z. B. ungültig und wird abgelehnt. ``` { "desired" : { "colors" : [ null, "RED", "GREEN" ] } } ```