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.
# AWS IoT Device Shadow-Dienst
Der AWS IoT Device Shadow-Dienst fügt AWS IoT Dingobjekten Schatten hinzu. Durch Schatten kann der Status eines Geräts Apps und anderen Diensten zur Verfügung gestellt werden, unabhängig davon, ob das Gerät mit dem Gerät verbunden ist AWS IoT oder nicht. AWS IoT Dingobjekte können mehrere benannte Schatten haben, sodass Ihre IoT-Lösung mehr Optionen für die Verbindung Ihrer Geräte mit anderen Apps und Diensten bietet.
AWS IoT Ding-Objekte haben keine Schatten, bis sie explizit erstellt werden. Schatten können mithilfe der AWS IoT Konsole erstellt, aktualisiert und gelöscht werden. Geräte, andere Webclients und Services können Schatten erstellen, aktualisieren und löschen mithilfe von MQTT und den [reservierten MQTT-Themen](reserved-topics.md#reserved-topics-shadow); HTTP mithilfe der [Geräteschatten-REST-API](device-shadow-rest-api.md); und der [AWS CLI für AWS IoT](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html) Da Schatten AWS in der Cloud gespeichert werden, können sie Gerätestatusdaten von Apps und anderen Cloud-Diensten sammeln und melden, unabhängig davon, ob das Gerät verbunden ist oder nicht.
## Verwendung von Schatten
Schatten bieten einen zuverlässigen Datenspeicher für Geräte, Anwendungen und andere Cloud-Services, um Daten gemeinsam zu nutzen. Sie ermöglichen es Geräten, Anwendungen und anderen Cloud-Services, eine Verbindung herzustellen und zu trennen, ohne den Status eines Geräts zu verlieren.
Geräte, Apps und andere Cloud-Dienste sind zwar mit ihnen verbunden AWS IoT, können aber über deren Schatten auf den aktuellen Status eines Geräts zugreifen und diesen kontrollieren. Eine App kann beispielsweise eine Änderung des Gerätestatus anfordern, indem sie einen Schatten aktualisiert. AWS IoT veröffentlicht eine Nachricht, die auf die Änderung des Geräts hinweist. Das Gerät empfängt diese Nachricht, aktualisiert seinen Status so, dass er übereinstimmt, und veröffentlicht eine Nachricht mit dem aktualisierten Status. Der Geräteschatten-Service spiegelt diesen aktualisierten Status im entsprechenden Schatten wider. Die Anwendung kann das Update des Schattens abonnieren oder den Schatten nach seinem aktuellen Status abfragen.
Wenn ein Gerät offline geht, kann eine App immer noch mit AWS IoT den Schatten des Geräts kommunizieren. Wenn das Gerät erneut eine Verbindung herstellt, erhält es den aktuellen Status seiner Schatten. Das Gerät kann seinen Status so aktualisieren, dass er mit dem seiner Schatten übereinstimmt, und dann eine Nachricht mit dem aktualisierten Status veröffentlichen. Wenn eine Anwendung offline ist und sich der Gerätestatus ändert, während sie offline ist, hält das Gerät den Schatten aktualisiert, damit die Anwendung die Schatten nach seinem aktuellen Status abfragen kann, wenn sie erneut eine Verbindung herstellt.
Wenn die Geräte häufig offline sind und Sie die Geräte so konfigurieren möchten, dass sie Deltameldungen empfangen, nachdem sie wieder eine Verbindung hergestellt haben, können Sie die Funktion für persistente Sitzungen verwenden. Weitere Informationen zum Ablauf der persistenten Sitzung finden Sie unter [Ablauffrist für persistente Sitzungen](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits).
### Auswählen der Verwendung benannter oder unbenannter Schatten
Der Geräteschatten-Service unterstützt benannte und unbenannte (klassische) Schatten. Ein Objekt kann mehrere benannte Schatten und nicht mehr als einen unbenannten, klassischen Schatten haben. Das Objekt kann auch einen reservierten benannten Schatten haben, der ähnlich wie ein benannter Schatten funktioniert, außer dass Sie seinen Namen nicht aktualisieren können. Weitere Informationen finden Sie unter [Reservierter benannter Schatten](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow).
Ein Objekt kann sowohl benannte als auch unbenannte Schatten gleichzeitig haben. Die API, die für den jeweiligen Zugriff verwendet wird, unterscheidet sich jedoch leicht. Daher ist es möglicherweise effizienter, zu entscheiden, welcher Schattentyp für Ihre Lösung am besten geeignet ist, und nur diesen Typ zu verwenden. Weitere Informationen zur API für den Zugriff auf die Schatten finden Sie unter [Schatten-Themen](reserved-topics.md#reserved-topics-shadow).
Mit benannten Schatten können Sie verschiedene Ansichten des Status eines Objekts erstellen. Beispielsweise könnten Sie ein Objekt mit vielen Eigenschaften in Schatten mit logischen Eigenschaftengruppen unterteilen, die jeweils durch einen Schattennamen gekennzeichnet sind. Sie können den Zugriff auf Eigenschaften auch einschränken, indem Sie sie in verschiedene Schatten gruppieren und Richtlinien verwenden, um den Zugriff zu steuern. Weitere Informationen zu Richtlinien, die mit Geräteschatten verwendet werden können, finden Sie unter [Aktionen, Ressourcen und Bedingungsschlüssel für](https://docs.aws.amazon.com//service-authorization/latest/reference/list_awsiot.html) AWS IoT und [AWS IoT Core Richtlinien](https://docs.aws.amazon.com//iot/latest/developerguide/iot-policies.html).
Die klassischen, unbenannten Schatten sind einfacher, aber etwas stärker eingeschränkt als die benannten Schatten. Jedes AWS IoT Objekt kann nur einen unbenannten Schatten haben. Wenn Sie erwarten, dass Ihre IoT-Lösung nur einen begrenzten Bedarf an Schattendaten hat, sollten Sie auf diese Weise mit der Verwendung von Schatten beginnen. Wenn Sie jedoch der Meinung sind, dass Sie in Zukunft weitere Schatten hinzufügen möchten, sollten Sie von Anfang an benannte Schatten verwenden.
Die Flottenindizierung unterstützt unbenannte Schatten und benannte Schatten unterschiedlich. Weitere Informationen finden Sie unter [Verwalten der Flottenindizierung](managing-fleet-index.md).
### Zugreifen auf Schatten
Jeder Schatten verfügt über ein reserviertes [MQTT-Thema](reserved-topics.md#reserved-topics-shadow) und eine [HTTP-URL](device-shadow-rest-api.md), die die `get`-, `update`- und `delete`-Aktionen für den Schatten unterstützt.
Schatten verwenden [JSON-Schattendokumente](device-shadow-document.md) zum Speichern und Abrufen von Daten. Das Dokument eines Schattens enthält eine Statuseigenschaft, die die folgenden Aspekte des Gerätezustands beschreibt:
+ `desired`
Apps geben die gewünschten Status der Geräteeigenschaften an, indem sie das `desired`-Objekt aktualisieren.
+ `reported`
Geräte melden ihren aktuellen Status im `reported`-Objekt.
+ `delta`
AWS IoT meldet Unterschiede zwischen dem gewünschten und dem gemeldeten Zustand des `delta` Objekts.
Die in einem Schatten gespeicherten Daten werden durch die Statuseigenschaft des Nachrichtentexts der Aktualisierungsaktion bestimmt. Nachfolgende Aktualisierungsaktionen können die Werte eines vorhandenen Datenobjekts ändern und Schlüssel und andere Elemente im Zustandsobjekt des Schattens hinzufügen und löschen. Weitere Informationen zum Zugriff auf Schatten finden Sie unter [Verwenden von Schatten in Geräten](device-shadow-comms-device.md) und [Verwenden von Schatten in Apps und Services](device-shadow-comms-app.md).
**Wichtig**
Die Berechtigung, Aktualisierungsanforderungen zu stellen, sollte auf vertrauenswürdige Apps und Geräte beschränkt sein. Dadurch wird verhindert, dass die Statuseigenschaft des Schattens unerwartet geändert wird. Andernfalls sollten die Geräte und Apps, die den Schatten verwenden, so konzipiert werden, dass sie erwarten, dass sich die Schlüssel in der Statuseigenschaft ändern.
### Verwenden von Schatten in Geräten, Apps und anderen Cloudservices
Die Verwendung von Schatten in Geräten, Apps und anderen Cloudservices erfordert Konsistenz und Koordination zwischen all diesen Services. Der AWS IoT Device Shadow-Dienst speichert den Shadow-Status, sendet Nachrichten, wenn sich der Shadow-Status ändert, und reagiert auf Nachrichten, die seinen Status ändern. Die Geräte, Apps und anderen Cloud-Services in Ihrer IoT-Lösung müssen ihren Status verwalten und den Status des Geräteschattens konsistent halten.
Die Schattenstatusdaten sind dynamisch und können von Geräten, Apps und anderen Cloud-Services mit Berechtigung zum Zugriff auf den Schatten geändert werden. Aus diesem Grund ist es wichtig zu berücksichtigen, wie jedes Gerät, jede App und jeder andere Cloud-Service mit dem Schatten interagiert. Beispiel:
+ *Geräte* sollten nur in die `reported`-Eigenschaft des Schattenstatus schreiben, wenn Statusdaten an den Schatten übertragen werden.
+ *Apps und andere Cloud-Services* sollten nur in die `desired`-Eigenschaft schreiben, wenn Statusänderungsanforderungen über den Schatten an das Gerät übermittelt werden.
**Wichtig**
Die in einem Schattendatenobjekt enthaltenen Daten sind unabhängig von anderen Schatten und anderen Objekteigenschaften, z. B. den Attributen eines Objekts und dem Inhalt von MQTT-Nachrichten, die das Gerät eines Objekts veröffentlichen könnte. Ein Gerät kann jedoch bei Bedarf dieselben Daten in verschiedenen MQTT-Themen und -Schatten melden.
Ein Gerät, das mehrere Schatten unterstützt, muss die Konsistenz der Daten aufrechterhalten, die es in den verschiedenen Schatten meldet.
### Nachrichtenreihenfolge
Es gibt keine Garantie dafür, dass Nachrichten des AWS IoT Dienstes in einer bestimmten Reihenfolge auf dem Gerät ankommen. Das folgende Szenario zeigt, was in diesem Fall passiert.
Ursprüngliches Statusdokument:
```
{
"state": {
"reported": {
"color": "blue"
}
},
"version": 9,
"timestamp": 123456776
}
```
Aktualisierung 1:
```
{
"state": {
"desired": {
"color": "RED"
}
},
"version": 10,
"timestamp": 123456777
}
```
Aktualisierung 2:
```
{
"state": {
"desired": {
"color": "GREEN"
}
},
"version": 11,
"timestamp": 123456778
}
```
Endgültiges Statusdokument:
```
{
"state": {
"reported": {
"color": "GREEN"
}
},
"version": 12,
"timestamp": 123456779
}
```
Dies führt zu zwei Delta-Nachrichten:
```
{
"state": {
"color": "RED"
},
"version": 11,
"timestamp": 123456778
}
```
```
{
"state": {
"color": "GREEN"
},
"version": 12,
"timestamp": 123456779
}
```
Das Gerät kann diese Nachrichten ohne feste Reihenfolge erhalten. Da der Status in diesen Nachrichten kumulativer Natur ist, kann ein Gerät Nachrichten, die eine Versionsnummer enthalten, die älter ist als die, die es verfolgt, sicher verwerfen. Erhält das Gerät das Delta für die Version 12 vor der Version 11 kann es die Nachricht zur Version 11 sicher verwerfen.
### Kürzen von Shadow-Nachrichten
Um die Größe der Schatten-Nachrichten, die an Ihr Gerät gesendet werden, zu reduzieren, legen Sie eine Regel fest, mit der nur die Felder, die Ihr Gerät benötigt, ausgewählt und die Nachricht in einem MQTT-Thema, das Ihr Gerät überwacht, erneut veröffentlicht werden.
Die Regel wird in der JSON vorgegeben und sollte wie folgt aussehen:
```
{
"sql": "SELECT state, version FROM '$aws/things/+/shadow/update/delta'",
"ruleDisabled": false,
"actions": [
{
"republish": {
"topic": "${topic(3)}/delta",
"roleArn": "arn:aws:iam:123456789012:role/my-iot-role"
}
}
]
}
```
Mit der SELECT-Anweisung wird festgelegt, welche Felder der Nachricht im vorgegebenen Topic erneut veröffentlicht werden. Der Platzhalter "\$1” wird verwendet, um allen Schattennamen zu entsprechen. Mit der Regel wird festgelegt, dass alle passenden Nachrichten im vorgegebenen Topic erneut veröffentlicht werden sollen. In diesem Fall wird die Funktion `"topic()"` verwendet, um das Thema anzugeben, in dem erneut eine Veröffentlichung erfolgen soll. `topic(3)` ermittelt den Objektnamen im Ursprungs-Thema. Weitere Informationen zum Erstellen von Regeln finden Sie unter [Regeln für AWS IoT](iot-rules.md).
# Verwenden von Schatten in Geräten
In diesem Abschnitt wird die Gerätekommunikation mit Shadows mithilfe von MQTT-Nachrichten beschrieben, der bevorzugten Methode für Geräte zur Kommunikation mit dem AWS IoT Device Shadow-Dienst.
Shadow-Kommunikation emuliert ein request/response Modell, das das Publish/Subscribe-Kommunikationsmodell von MQTT verwendet. Jede Schattenaktion besteht aus einem Anforderungsthema, einem Thema für erfolgreiche Antworten (`accepted`) und einem Thema für Fehlerantworten (`rejected`).
Informationen dazu, ob Apps und Services feststellen können, ob ein Gerät verbunden ist, finden Sie unter [Erkennt, ob ein Gerät angeschlossen ist](device-shadow-comms-app.md#thing-connection).
**Wichtig**
Da MQTT ein publish/subscribe Kommunikationsmodell verwendet, sollten Sie die Antwortthemen abonnieren, *bevor* Sie ein Anforderungsthema veröffentlichen. Wenn Sie dies nicht tun, erhalten Sie keine Antwort auf die Anfrage, die Sie veröffentlichen.
Wenn Sie einen [AWS IoT Device SDK](iot-sdks.md)zum Aufrufen des Device Shadow-Dienstes verwenden APIs, wird dies für Sie erledigt.
Die Beispiele in diesem Abschnitt verwenden eine verkürzte Form des Themas, wobei sich der Begriff entweder auf einen benannten oder einen unbenannten Schatten beziehen *ShadowTopicPrefix* kann, wie in dieser Tabelle beschrieben.
Schatten können benannt oder unbenannt sein (klassisch). Die jeweils verwendeten Themen unterscheiden sich nur durch das Themenpräfix. In dieser Tabelle wird das Themenpräfix angezeigt, das von jedem Schattentyp verwendet wird.
| *ShadowTopicPrefix* Wert | Schattentyp |
| --- | --- |
| \$1aws/things/thingName/shadow | Unbenannter (klassischer) Schatten |
| \$1aws/things/thingName/shadow/name/shadowName | Benannter Schatten |
**Wichtig**
Stellen Sie sicher, dass die Verwendung der Schatten durch Ihre App oder Ihren Service konsistent ist und von den entsprechenden Implementierungen auf Ihren Geräten unterstützt wird. Bedenken Sie beispielsweise, wie Schatten erstellt, aktualisiert und gelöscht werden. Berücksichtigen Sie auch, wie Updates auf dem Gerät und in den Apps oder Services behandelt werden, die über einen Schatten auf das Gerät zugreifen. Ihr Design sollte klar angeben, wie der Zustand des Geräts aktualisiert und gemeldet wird und wie Ihre Apps und Services mit dem Gerät und seinen Schatten interagieren.
Um ein vollständiges Thema zu erstellen, wählen Sie `ShadowTopicPrefix` als Schattentyp aus, auf den Sie verweisen möchten. Ersetzen Sie `thingName` und `shadowName` mit den entsprechenden Werten, wenn zutreffend. Fügen Sie anschließend den Themen-Stub an wie in der folgenden Tabelle dargestellt. Denken Sie daran, dass bei Themen zwischen Groß- und Kleinschreibung unterschieden wird.
Weitere Informationen zu den reservierten Themen für Schatten finden Sie unter [Schatten-Themen](reserved-topics.md#reserved-topics-shadow).
## Initialisierung des Geräts bei der ersten Verbindung zu AWS IoT
Nachdem sich ein Gerät bei registriert hat AWS IoT, sollte es diese MQTT-Nachrichten für die Shadows abonnieren, die es unterstützt.
| Thema | Bedeutung | Aktion, die ein Gerät ausführen sollte, wenn dieses Thema empfangen wird |
| --- | --- | --- |
| `ShadowTopicPrefix/delete/accepted` | Die `delete` Anfrage wurde akzeptiert und der Shadow wurde AWS IoT gelöscht. | Die Aktionen, die für den gelöschten Schatten erforderlich sind, z. B. das Beenden der Veröffentlichung von Aktualisierungen. |
| `ShadowTopicPrefix/delete/rejected` | Die `delete` Anfrage wurde von abgelehnt AWS IoT und der Shadow wurde nicht gelöscht. Der Nachrichtentext enthält die Fehlerinformationen. | Reagieren Sie auf die Fehlermeldung im Nachrichtentext. |
| `ShadowTopicPrefix/get/accepted` | Die `get` Anfrage wurde von akzeptiert AWS IoT, und der Nachrichtentext enthält das aktuelle Shadow-Dokument. | Die Aktionen, die erforderlich sind, um das Statusdokument im Nachrichtentext zu verarbeiten. |
| `ShadowTopicPrefix/get/rejected` | Die `get` Anfrage wurde von abgelehnt AWS IoT, und der Nachrichtentext enthält die Fehlerinformationen. | Reagieren Sie auf die Fehlermeldung im Nachrichtentext. |
| `ShadowTopicPrefix/update/accepted` | Die `update` Anfrage wurde von akzeptiert AWS IoT, und der Nachrichtentext enthält das aktuelle Schattendokument. | Bestätigen Sie, dass die aktualisierten Daten im Nachrichtentext mit dem Gerätestatus übereinstimmen. |
| `ShadowTopicPrefix/update/rejected` | Die `update` Anfrage wurde von abgelehnt AWS IoT, und der Nachrichtentext enthält die Fehlerinformationen. | Reagieren Sie auf die Fehlermeldung im Nachrichtentext. |
| `ShadowTopicPrefix/update/delta` | Das Schattendokument wurde durch eine Anfrage an aktualisiert AWS IoT, und der Nachrichtentext enthält die angeforderten Änderungen. | Aktualisieren Sie den Gerätestatus so, dass er mit dem gewünschten Status im Nachrichtentext übereinstimmt. |
| `ShadowTopicPrefix/update/documents` | Eine Aktualisierung des Schattens wurde kürzlich abgeschlossen, und der Nachrichtentext enthält das aktuelle Schattendokument. | Bestätigen Sie, dass der aktualisierte Status im Nachrichtentext mit dem Gerätestatus übereinstimmt. |
Nach dem Abonnieren der Nachrichten in der obigen Tabelle für jeden Schatten sollte das Gerät testen, ob die Schatten, die es unterstützt, bereits erstellt wurden, indem es ein `/get`-Thema in jedem Schatten veröffentlicht. Wenn eine `/get/accepted`-Nachricht empfangen wird, enthält der Nachrichtentext das Schattendokument, mit dem das Gerät seinen Status initialisieren kann. Wenn eine `/get/rejected`-Nachricht empfangen wird, sollte der Schatten erstellt werden, indem eine `/update`-Nachricht mit dem aktuellen Gerätestatus veröffentlicht wird.
Nehmen wir zum Beispiel an, Sie haben ein Objekt `My_IoT_Thing`, das keine klassischen oder benannten Schatten hat. Wenn Sie jetzt eine `/get`-Anfrage zum reservierten Thema `$aws/things/My_IoT_Thing/shadow/get` veröffentlichen, erhält das `$aws/things/My_IoT_Thing/shadow/get/rejected` Thema einen Fehler, da das Objekt keine Schatten hat. Um diesen Fehler zu beheben, veröffentlichen Sie zunächst eine `/update`-Nachricht, indem Sie das `$aws/things/My_IoT_Thing/shadow/update` Thema mit dem aktuellen Gerätestatus verwenden, z. B. die folgende Payload.
```
{
"state": {
"reported": {
"welcome": "aws-iot",
"color": "yellow"
}
}
}
```
Für das Objekt wird jetzt ein klassischer Schatten erstellt, und die Nachricht wird auf dem `$aws/things/My_IoT_Thing/shadow/update/accepted`-Thema veröffentlicht. Wenn Sie zu dem Thema `$aws/things/My_IoT_Thing/shadow/get` veröffentlichen, wird eine Antwort auf das `$aws/things/My_IoT_Thing/shadow/get/accepted`-Thema mit dem Gerätestatus zurückgegeben.
Bei benannten Schatten müssen Sie zuerst den benannten Schatten erstellen oder ein Update mit dem Schatten-Namen veröffentlichen, bevor Sie die GET-Anfrage verwenden können. Um beispielsweise einen benannten Schatten `namedShadow1` zu erstellen, müssen Sie zunächst die Informationen zum Gerätestatus für das Thema veröffentlichen`$aws/things/My_IoT_Thing/shadow/name/namedShadow1/update`. Um die Statusinformationen abzurufen, verwenden Sie die `/get`-Anfrage für den benannten Schatten, `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/get`.
## Nachrichten werden verarbeitet, während das Gerät angeschlossen ist AWS IoT
Solange ein Gerät verbunden ist AWS IoT, kann es **/update/delta-Meldungen** empfangen und sollte den Gerätestatus an die Änderungen in seinem Schatten anpassen, indem es:
1. Lesen aller empfangenen **/update/delta**-Nachrichten und entsprechende Anpassung des Gerätestatus.
1. Veröffentlichen einer **/update**-Nachricht mit einem `reported`-Nachrichtentext, der den aktuellen Status des Geräts hat, wenn sich der Gerätestatus ändert.
Solange ein Gerät angeschlossen ist, sollte es diese Meldungen veröffentlichen, wenn angezeigt.
| Indikation | Thema | Nutzlast |
| --- | --- | --- |
| Der Zustand des Geräts hat sich geändert. | `ShadowTopicPrefix/update` | Ein Schattendokument mit der `reported`-Eigenschaft. |
| Das Gerät wird möglicherweise nicht mit dem Schatten synchronisiert. | `ShadowTopicPrefix/get` | (empty) |
| Eine Aktion auf dem Gerät zeigt an, dass ein Schatten vom Gerät nicht mehr unterstützt wird, z. B. wenn das Gerät entfernt oder ersetzt wird. | `ShadowTopicPrefix/delete` | (empty) |
## Nachrichten werden verarbeitet, wenn das Gerät wieder eine Verbindung herstellt mit AWS IoT
Wenn ein Gerät mit einem oder mehreren Schatten eine Verbindung herstellt AWS IoT, sollte es seinen Status mit dem aller Schatten synchronisieren, die es unterstützt, und zwar wie folgt:
1. Lesen aller empfangenen **/update/delta**-Nachrichten und entsprechende Anpassung des Gerätestatus.
1. Veröffentlichen einer **/update**-Nachricht mit einem `reported`-Nachrichtentext, der den aktuellen Status des Geräts hat.
# Verwenden von Schatten in Apps und Services
In diesem Abschnitt wird beschrieben, wie eine App oder ein Dienst mit dem AWS IoT Device Shadow-Dienst interagiert. In diesem Beispiel wird davon ausgegangen, dass die App oder der Service nur mit dem Schatten und darüber dem Gerät interagiert. In diesem Beispiel sind keine Verwaltungsaktionen enthalten, z. B. das Erstellen oder Löschen von Schatten.
In diesem Beispiel wird die REST-API des AWS IoT Device Shadow-Dienstes verwendet, um mit Schatten zu interagieren. Im Gegensatz zu dem in verwendeten Beispiel[Verwenden von Schatten in Geräten](device-shadow-comms-device.md), das ein publish/subscribe communications model, this example uses the request/response Kommunikationsmodell der REST-API verwendet. Das bedeutet, dass die App oder der Dienst eine Anfrage stellen muss, bevor sie eine Antwort von erhalten kann AWS IoT. Ein Nachteil dieses Modells ist jedoch, dass es keine Benachrichtigungen unterstützt. Wenn Ihre App oder Ihr Dienst zeitnahe Benachrichtigungen über Änderungen des Gerätestatus benötigt, sollten Sie die Protokolle MQTT oder MQTT über WSS in Betracht ziehen, die das publish/subscribe Kommunikationsmodell unterstützen, wie unter beschrieben. [Verwenden von Schatten in Geräten](device-shadow-comms-device.md)
**Wichtig**
Stellen Sie sicher, dass die Verwendung der Schatten Ihrer App oder Ihres Services mit den entsprechenden Implementierungen in Ihren Geräten konsistent ist und von diesen unterstützt wird. Berücksichtigen Sie beispielsweise, wie Schatten erstellt, aktualisiert und gelöscht werden und wie Updates auf dem Gerät und in den Apps oder Services, die auf den Schatten zugreifen, gehandhabt werden. In Ihrem Design sollte klar angegeben werden, wie der Zustand des Geräts aktualisiert und gemeldet wird und wie Ihre Apps und Services mit dem Gerät und seinen Schatten interagieren.
Die URL der REST-API für einen benannten Schatten lautet:
```
https://endpoint/things/thingName/shadow?name=shadowName
```
und für einen unbenannten Schatten:
```
https://endpoint/things/thingName/shadow
```
Wobei:
Endpunkt
Der vom CLI-Befehl zurückgegebene Endpunkt:
```
aws iot describe-endpoint --endpoint-type IOT:Data-ATS
```
thingName
Der Name des Objekts, zu dem der Schatten gehört
shadowName
Der Name des benannten Schattens. Dieser Parameter wird mit unbenannten Schatten nicht verwendet.
## Initialisierung der App oder des Dienstes bei der Verbindung zu AWS IoT
Wenn die App zum ersten Mal eine Verbindung herstellt AWS IoT, sollte sie eine HTTP-GET-Anfrage an den URLs Schatten senden, den sie verwendet, um den aktuellen Status der Schatten abzurufen, die sie verwendet. Dies ermöglicht es, die App oder den Service mit dem Schatten zu synchronisieren.
## Der Verarbeitungsstatus ändert sich, während die App oder der Dienst verbunden ist AWS IoT
Solange die App oder der Dienst verbunden ist AWS IoT, kann sie den aktuellen Status regelmäßig abfragen, indem sie eine HTTP-GET-Anfrage an die URLs von ihr verwendeten Shadows sendet.
Wenn ein Endbenutzer mit der App oder dem Dienst interagiert, um den Status des Geräts zu ändern, kann die App oder der Dienst eine HTTP-POST-Anfrage an den URLs Shadow senden, mit dem sie den `desired` Status des Shadows aktualisiert. Diese Anforderung gibt die Änderung zurück, die akzeptiert wurde, aber Sie müssen möglicherweise den Schatten abfragen, indem Sie HTTP-GET-Anforderungen vornehmen, bis das Gerät den Schatten mit seinem neuen Status aktualisiert hat.
## Erkennt, ob ein Gerät angeschlossen ist
Um festzustellen, ob ein Gerät derzeit verbunden ist, schließen Sie eine `connected`-Eigenschaft in das Schattendokument ein und verwenden eine MQTT Last Will and Testament (LWT)-Meldung, um die `connected`-Eigenschaft auf `false` festzulegen, wenn ein Gerät aufgrund eines Fehlers getrennt wird.
**Anmerkung**
MQTT-LWT-Nachrichten, die an AWS IoT reservierte Themen (Themen, die mit \$1 beginnen) gesendet werden, werden vom AWS IoT Device Shadow-Dienst ignoriert. Sie werden jedoch von abonnierten Clients und von der AWS IoT Rules Engine verarbeitet, sodass Sie eine LWT-Nachricht erstellen müssen, die an ein nicht reserviertes Thema gesendet wird, und eine Regel, die die MQTT-LWT-Nachricht als Shadow-Update-Nachricht für das reservierte Update-Thema des Shadows erneut veröffentlicht. `ShadowTopicPrefix/update`
**So senden Sie dem Device Shadow-Service eine LWT-Nachricht**
1. Erstellen Sie eine Regel, die die MQTT LWT-Nachricht im reservierten Thema erneut veröffentlicht. Das folgende Beispiel ist eine Regel, die auf Nachrichten zu dem `my/things/myLightBulb/update`-Thema wartet und sie erneut in `$aws/things/myLightBulb/shadow/update` veröffentlicht.
```
{
"rule": {
"ruleDisabled": false,
"sql": "SELECT * FROM 'my/things/myLightBulb/update'",
"description": "Turn my/things/ into $aws/things/",
"actions": [
{
"republish": {
"topic": "$$aws/things/myLightBulb/shadow/update",
"roleArn": "arn:aws:iam:123456789012:role/aws_iot_republish"
}
}
]
}
}
```
1. Wenn das Gerät eine Verbindung herstellt AWS IoT, registriert es eine LWT-Nachricht zu einem nicht reservierten Thema, damit die Regel zur erneuten Veröffentlichung diese erkennt. In diesem Beispiel ist dieses Thema `my/things/myLightBulb/update`, und die verbundene Eigenschaft wird auf `false` festgelegt.
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Nach der Verbindung veröffentlicht das Gerät eine Nachricht zu seinem Shadow-Update-Thema, `$aws/things/myLightBulb/shadow/update`, um seinen aktuellen Status zu melden, einschließlich der Einstellung seiner `connected`-Eigenschaft auf `true`.
```
{
"state": {
"reported": {
"connected":"true"
}
}
}
```
1. Bevor das Gerät die Verbindung ordnungsgemäß trennt, veröffentlicht es eine Nachricht zu seinem Schattenaktualisierungsthema, `$aws/things/myLightBulb/shadow/update`, um seinen neuesten Status zu melden, einschließlich der Einstellung seiner `connected`-Eigenschaft auf `false`.
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Wenn das Gerät aufgrund eines Fehlers die Verbindung trennt, veröffentlicht der AWS IoT Message Broker die LWT-Nachricht des Geräts im Namen des Geräts. Die Regel zum erneuten Veröffentlichen erkennt diese Nachricht und veröffentlicht die Schattenaktualisierungsmeldung, um die `connected`-Eigenschaft des Geräteschattens zu aktualisieren.
**Anmerkung**
Aufgrund der asynchronen Verarbeitung von Verbindungsabbrüchen kann nicht garantiert werden, dass LWT-Nachrichten bei der Wiederherstellung der Verbindung in der richtigen Reihenfolge versendet werden. Es wird empfohlen, [Lebenszyklusereignisse](life-cycle-events.md) zu verwenden, um die Genauigkeit der Erkennung des Verbindungsstatus zu verbessern, da diese Ereignisse Attribute zur Verwaltung von Ereignissen bereitstellen. out-of-order
# Simulieren der Device Shadow-Servicekommunikation
In diesem Thema wird veranschaulicht, wie der Device Shadow-Service als Vermittler fungiert und es Geräten und Apps ermöglicht, einen Schatten zum Aktualisieren, Speichern und Abrufen des Status eines Geräts zu verwenden.
Um die in diesem Thema beschriebene Interaktion zu demonstrieren und sie weiter zu untersuchen, benötigen Sie ein AWS-Konto und ein System, auf dem Sie das ausführen können AWS CLI. Wenn Sie diese nicht haben, können Sie die Interaktion immer anhand der Codebeispiele untersuchen.
In diesem Beispiel steht die AWS IoT Konsole für das Gerät. Das AWS CLI steht für die App oder den Dienst, der über den Shadow auf das Gerät zugreift. Die AWS CLI Schnittstelle ist der API sehr ähnlich, mit AWS IoT der eine App möglicherweise kommuniziert. Das Gerät in diesem Beispiel ist eine intelligente Glühlampe, und die App zeigt den Status der Glühlampe an und kann ihren Status ändern.
## Einrichten der Simulation
Diese Verfahren initialisieren die Simulation, indem Sie die [AWS IoT -Konsole](https://console.aws.amazon.com/iot/home) öffnen, die Ihr Gerät simuliert, und das Befehlszeilenfenster, das Ihre App simuliert.
**So richten Sie Ihre Simulationsumgebung ein:**
1. Sie benötigen eine AWS-Konto , um die Beispiele aus diesem Thema selbst ausführen zu können. Wenn Sie noch keine haben AWS-Konto, erstellen Sie eine, wie unter beschrieben[Einrichten AWS-Konto](setting-up.md).
1. Öffnen Sie die [AWS IoT -Konsole](https://console.aws.amazon.com/iot/home) und wählen Sie im linken Menü **Test**, um den **MQTT-Client** zu öffnen.
1. Öffnen Sie in einem anderen Fenster ein Terminalfenster auf einem System, auf dem das AWS CLI installiert ist.
Sie sollten zwei Fenster geöffnet haben: eines mit der AWS IoT Konsole auf der **Testseite** und eines mit einer Befehlszeilenaufforderung.
## Initialisieren des Geräts
In dieser Simulation arbeiten wir mit einem Dingobjekt mit dem Namen SimShadow1 und seinem Schatten mit dem Namen *SimShadow1*. *mySimulatedThing*
**Erstellen des Objekts und seiner IoT-Richtlinie**
Um ein Objekt zu erstellen, gehen Sie in der **AWS IoT Konsole** wie folgt vor:
1. Wählen Sie **Verwalten** und dann **Things**.
1. Klicken Sie auf die Schaltfläche **Erstellen**, wenn Dinge aufgelistet sind, andernfalls klicken Sie auf Einzelne Sache **registrieren, um eine einzelne Sache** zu erstellen. AWS IoT
1. Geben Sie den Namen `mySimulatedThing` ein, behalten Sie die Standardeinstellungen für andere Einstellungen bei und klicken Sie dann auf **Weiter**.
1. Generieren Sie mithilfe der Zertifikatserstellung mit nur einem Klick die Zertifikate, mit denen die Verbindung des Geräts mit AWS IoT authentifiziert wird. Klicken Sie auf **Aktivieren**, um das Zertifikat zu aktivieren.
1. Sie können die Richtlinie `My_IoT_Policy` anhängen, die dem Gerät die Erlaubnis erteilt, die reservierten MQTT-Themen zu veröffentlichen und zu abonnieren. Genauere Anweisungen zum Erstellen AWS IoT eines Dings und zum Erstellen dieser Richtlinie finden Sie unter[Dies erstellt ein Objekt](create-iot-resources.md#create-aws-thing).
**Erstellen Sie einen benannten Schatten für das Objekt.**
Sie können einen benannten Schatten für ein Objekt erstellen, indem Sie eine Aktualisierungsanfrage für das Thema `$aws/things/mySimulatedThing/shadow/name/simShadow1/update`, wie unten beschrieben, veröffentlichen.
Oder, um einen benannten Schatten zu erstellen:
1. Wählen Sie in der **AWS IoT -Konsole** Ihr Objekt in der Liste der angezeigten Objekte aus und wählen Sie dann **Schatten**.
1. Wählen Sie **Schatten hinzufügen**, geben Sie den Namen `simShadow1` ein und wählen Sie dann **Erstellen**, um den benannten Schatten hinzuzufügen.
**Abonnieren und veröffentlichen Sie reservierte MQTT-Themen**
Abonnieren Sie in der Konsole die reservierten MQTT-Schatten-Themen. Diese Themen sind die Antworten auf die Aktionen `get`, `update` und `delete`, damit Ihr Gerät bereit ist, die Antworten zu empfangen, nachdem es eine Aktion veröffentlicht hat.
**So abonnieren Sie ein MQTT-Thema im **MQTT-Client**:**
1. Wählen Sie im **MQTT-Client** die Option **In einem Thema veröffentlichen** aus.
1. Geben Sie `get`, `update`, und `delete` Themen ein, die Sie abonnieren möchten. Kopieren Sie jeweils ein Thema aus der folgenden Liste, fügen Sie es in das Feld **Themenfilter** ein und klicken Sie dann auf **Abonnieren**. Die Themen müssten dann unter **Abonnements** aufgeführt werden.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/documents`
An diesem Punkt ist Ihr simuliertes Gerät bereit, die Themen zu erhalten, wie sie von AWS IoT veröffentlicht werden.
**So abonnieren Sie ein MQTT-Thema im **MQTT-Client**:**
Nachdem ein Gerät sich selbst initialisiert und die Antwortthemen abonniert hat, sollte Abfragen nach den unterstützten Schatten durchführen. Diese Simulation unterstützt nur einen Schatten, nämlich den Schatten, der ein Dingobjekt namens *SimShadow1* unterstützt. *mySimulatedThing*
**So rufen Sie den aktuellen Schattenstatus vom **MQTT-Client** ab:**
1. Wählen Sie im **MQTT-Client** die Option **Publish to a topic (In einem Thema veröffentlichen)** aus.
1. Geben Sie unter **Veröffentlichen** folgendes Thema ein und löschen Sie alle Inhalte aus dem Nachrichtentextfenster, in dem Sie das Thema für GET eingegeben haben. Sie können dann **In Thema veröffentlichen** auswählen, um die Anfrage zu veröffentlichen. `$aws/things/mySimulatedThing/shadow/name/simShadow1/get`.
Wenn Sie den benannten Schatten nicht erstellt haben, `simShadow1`, erhalten Sie eine Nachricht im `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected` Thema, und der `code` ist `404`, wie in diesem Beispiel, und da der Schatten nicht erstellt wurde, erstellen wir ihn als Nächstes.
```
{
"code": 404,
"message": "No shadow exists with name: 'simShadow1'"
}
```
**So erstellen Sie einen Schatten mit dem aktuellen Status des Geräts:**
1. Wählen Sie im **MQTT-Client** die Option **In einem Thema veröffentlichen** aus.
```
$aws/things/mySimulatedThing/shadow/name/simShadow1/update
```
1. Geben Sie im Nachrichtentextfenster, in dem Sie das Thema eingegeben haben, dieses Schattendokument ein, um anzuzeigen, dass das Gerät seine ID und seine aktuelle Farbe in RGB-Werten meldet. Wählen Sie **Veröffentlichen**, um die Anfrage zu veröffentlichen.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
Wenn Sie eine Nachricht zum Thema erhalten:
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`: Das bedeutet, dass der Schatten erstellt wurde und der Nachrichtentext das aktuelle Schattendokument enthält.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`: Überprüfen Sie den Fehler im Nachrichtentext.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`: Der Schatten ist bereits vorhanden und der Nachrichtentext hat den aktuellen Schattenstatus, wie in diesem Beispiel. Damit können Sie Ihr Gerät einstellen oder bestätigen, dass es mit dem Schattenstatus übereinstimmt.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591140517,
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
## Senden einer Aktualisierung von der App
In diesem Abschnitt wird anhand von demonstriert AWS CLI , wie eine App mit einem Schatten interagieren kann.
**Um den aktuellen Status des Schattens mit dem zu ermitteln AWS CLI**
Geben Sie in der Befehlszeile den folgenden Befehl ein.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Auf Windows-Plattformen können Sie `con` anstelle von `/dev/stdout` verwenden.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
Da der Schatten vorhanden ist und vom Gerät initialisiert wurde, um seinen aktuellen Zustand wiederzugeben, sollte das folgende Schattendokument zurückgegeben werden.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591141111
}
```
Die App kann diese Antwort verwenden, um die Darstellung des Gerätestatus zu initialisieren.
Wenn die App den Status aktualisiert, z. B. wenn ein Endbenutzer die Farbe unserer intelligenten Glühlampe zu Gelb ändert, sendet die App einen **update-thing-shadow**-Befehl. Dieser Befehl entspricht der `UpdateThingShadow`-REST-API.
**So aktualisieren Sie einen Schatten aus einer App:**
Geben Sie in der Befehlszeile den folgenden Befehl ein.
------
#### [ AWS CLI v2.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--cli-binary-format raw-in-base64-out \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
#### [ AWS CLI v1.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
Wenn dieser Befehl erfolgreich ist, sollte das folgende Schattendokument zurückgegeben werden.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
}
},
"version": 4,
"timestamp": 1591141596,
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
## Reaktion auf eine Aktualisierung im Gerät
Wenn Sie zum **MQTT-Client** in der AWS Konsole zurückkehren, sollten Sie die Meldungen sehen, die AWS IoT veröffentlicht wurden, um den im vorherigen Abschnitt ausgegebenen Aktualisierungsbefehl widerzuspiegeln.
**So zeigen Sie die Aktualisierungsmeldungen im **MQTT-Client an**:**
Wählen Sie im **MQTT-Client** aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta in der Spalte **Abonnements** die Option **\$1** aus. Wenn der Themenname abgeschnitten wird, können Sie ihn anhalten, um das vollständige Thema anzuzeigen. Im Themenprotokoll zu diesem Thema sollten Sie eine `/delta` Meldung sehen, die dieser ähnelt.
```
{
"version": 4,
"timestamp": 1591141596,
"state": {
"ColorRGB": [
255,
255,
0
]
},
"metadata": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
Ihr Gerät verarbeitet den Inhalt dieser Nachricht, um den Gerätestatus so festzulegen, dass er mit dem `desired`-Status in der Nachricht übereinstimmt.
Nachdem das Gerät den Status aktualisiert hat, sodass er dem `desired` Status in der Nachricht entspricht, muss es den neuen gemeldeten Status AWS IoT durch Veröffentlichung einer Aktualisierungsnachricht an den neuen Status zurücksenden. Dieses Verfahren simuliert dies im **MQTT-Client**.
**So aktualisieren Sie den Schatten vom Gerät aus:**
1. Wählen Sie im **MQTT-Client** die Option **Publish to a topic (In einem Thema veröffentlichen)** aus.
1. Geben Sie im Nachrichtentextfenster im Themenfeld über dem Nachrichtentext das Schattenthema ein, gefolgt von der `/update`-Aktion: `$aws/things/mySimulatedThing/shadow/name/simShadow1/update` und geben Sie im Nachrichtentext dieses aktualisierte Shadow-Dokument ein, das den aktuellen Status des Geräts beschreibt. Wählen Sie **Veröffentlichen**, um den aktualisierten Gerätestatus zu veröffentlichen.
```
{
"state": {
"reported": {
"ColorRGB": [255,255,0]
}
},
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Wenn die Nachricht erfolgreich von empfangen wurde AWS IoT, sollten Sie im **\$1 aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted** message log des **MQTT-Clients** eine neue Antwort mit dem aktuellen Status des Shadows sehen, wie in diesem Beispiel.
```
{
"state": {
"reported": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"reported": {
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Eine erfolgreiche Aktualisierung des gemeldeten Status des Geräts führt auch AWS IoT dazu, dass eine umfassende Beschreibung des Shadow-Status in einer Nachricht an das `update/documents` Thema gesendet wird, z. B. dieser Nachrichtentext, der auf das Shadow-Update zurückzuführen ist, das das Gerät im vorherigen Verfahren durchgeführt hat.
```
{
"previous": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 4
},
"current": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5
},
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
## Beobachten Sie das Update in der App
Die App kann jetzt den Schatten nach dem aktuellen Status abfragen, wie vom Gerät gemeldet.
**Um den aktuellen Status des Schattens abzurufen, verwenden Sie den AWS CLI**
1. Geben Sie in der Befehlszeile den folgenden Befehl ein.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Auf Windows-Plattformen können Sie `con` anstelle von `/dev/stdout` verwenden.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
1. Da der Schatten gerade vom Gerät aktualisiert wurde, um seinen aktuellen Zustand wiederzugeben, sollte er das folgende Schattendokument zurückgeben.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591143269
}
```
## Über die Simulation hinaus
Experimentieren Sie mit der Interaktion zwischen der AWS CLI (für die App) und der Konsole (für das Gerät), um Ihre IoT-Lösung zu modellieren.
# Interaktion mit Schatten
In diesem Thema werden die Nachrichten beschrieben, die jeder der drei Methoden zugeordnet sind, die AWS IoT für das Arbeiten mit Schatten bereitstellt. Zu diesen Methoden gehören die folgenden:
`UPDATE`
Erstellt einen Schatten, wenn er nicht vorhanden ist, oder aktualisiert den Inhalt eines vorhandenen Schattens mit den Statusinformationen, die im Nachrichtentext bereitgestellt werden. AWS IoT zeichnet mit jeder Aktualisierung einen Zeitstempel auf, um anzugeben, wann der Status zuletzt aktualisiert wurde. Wenn sich der Status des Shadows ändert, werden `/delta` Nachrichten AWS IoT an alle MQTT-Abonnenten gesendet, wobei der Unterschied zwischen den `desired` und den `reported` Zuständen angegeben wird. Geräte oder Apps, die eine `/delta`-Nachricht empfangen, können basierend auf dem Unterschied Aktionen durchführen. Bei einem Gerät kann z. B. der Status auf den Sollstatus oder bei einer Anwendung die Benutzeroberfläche aktualisiert werden, um die Änderung des Gerätestatus zu reflektieren.
`GET`
Ruft ein aktuelles Schattendokument ab, das den vollständigen Status des Schattens einschließlich Metadaten enthält.
`DELETE`
Löscht den Geräteschatten und seinen gesamten Inhalt.
Sie können ein gelöschtes Geräteschatten-Dokument nicht wiederherstellen, aber Sie können ein neues Geräteschatten-Dokument mit dem Namen eines gelöschten Geräteschatten-Dokuments erstellen. Wenn Sie ein Geräteschatten-Dokument erstellen, das denselben Namen hat wie eines, das innerhalb der letzten 48 Stunden gelöscht wurde, folgt die Versionsnummer des neuen Geräteschatten-Dokuments der Versionsnummer des gelöschten. Wenn ein Geräteschatten-Dokument länger als 48 Stunden gelöscht wurde, lautet die Versionsnummer eines neuen Geräteschatten-Dokuments mit demselben Namen 0.
## Protokollunterstützung
AWS IoT unterstützt [MQTT](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) und eine REST-API über HTTPS-Protokolle, um mit Schatten zu interagieren. AWS IoT bietet eine Reihe von reservierten Anfrage- und Antwortthemen für MQTT-Aktionen zum Veröffentlichen und Abonnieren. Geräte und Apps sollten die Antwortthemen abonnieren, bevor sie in einem Anfragethema veröffentlichen, um Informationen darüber zu erhalten, wie AWS IoT mit der Anfrage umgegangen wurde. Weitere Informationen erhalten Sie unter [MQTT-Themen für Geräteschatten](device-shadow-mqtt.md) und [Geräteschatten-REST-API](device-shadow-rest-api.md).
## Anforderungs- und Meldestatus
Wenn Sie Ihre IoT-Lösung mithilfe von AWS IoT Schatten entwerfen, sollten Sie festlegen, welche Apps oder Geräte Änderungen anfordern und welche diese implementieren. In der Regel implementiert und meldet ein Gerät Änderungen an den Schatten zurück, und Apps und Services reagieren auf Änderungen im Schatten und fordern Änderungen an. Ihre Lösung könnte davon abweichen, aber die Beispiele in diesem Thema gehen jedoch davon aus, dass die Client-App oder der Service Änderungen im Schatten anfordert und das Gerät die Änderungen durchführt und sie an den Schatten zurückmeldet.
## Aktualisieren eines Shadows
Ihre App oder Ihr Service kann den Status eines Schattens mithilfe der [UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow)-API oder durch Veröffentlichung im [/update](device-shadow-mqtt.md#update-pub-sub-topic)-Thema aktualisieren. Aktualisierungen betreffen lediglich die in der Anfrage angegebenen Felder.
### Aktualisieren eines Schattens, wenn ein Client eine Statusänderung anfordert
**Wenn ein Client eine Statusänderung in einem Schatten mithilfe des MQTT-Protokolls anfordert**
1. Der Client sollte über ein aktuelles Schattendokument verfügen, damit er die zu ändernden Eigenschaften identifizieren kann. Weitere Informationen zum Abrufen des aktuellen Schattendokuments finden Sie unter der Aktion /get.
1. Der Client abonniert diese MQTT-Themen:
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/rejected`
+ `$aws/things/thingName/shadow/name/shadowName/update/delta`
+ `$aws/things/thingName/shadow/name/shadowName/update/documents`
1. Der Client veröffentlicht ein `$aws/things/thingName/shadow/name/shadowName/update`-Anforderungsthema mit einem Statusdokument, das den gewünschten Status des Schattens enthält. Nur die zu ändernden Eigenschaften müssen in das Dokument aufgenommen werden. Dies ist ein Beispiel für ein Dokument mit dem gewünschten Status.
```
{
"state": {
"desired": {
"color": {
"r": 10
},
"engine": "ON"
}
}
}
```
1. Wenn die Aktualisierungsanfrage gültig ist, AWS IoT aktualisiert sie den gewünschten Status im Shadow und veröffentlicht Meldungen zu den folgenden Themen:
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/delta`
Die `/update/accepted`-Nachricht enthält ein [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted)-Schattendokument, und die `/update/delta`-Nachricht enthält ein [Antwortstatusdokument „/delta“](device-shadow-document.md#device-shadow-example-response-json-delta)-Schattendokument.
1. Wenn die Aktualisierungsanforderung nicht gültig ist, wird eine Nachricht mit dem `$aws/things/thingName/shadow/name/shadowName/update/rejected` Thema zusammen mit einem [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) Schattendokument AWS IoT veröffentlicht, das den Fehler beschreibt.
**Wenn ein Client eine Statusänderung in einem Schatten mithilfe der API anfordert**
1. Der Client ruft die `UpdateThingShadow`-API mit einem [Anfragestatusdokument](device-shadow-document.md#device-shadow-example-request-json)-Statusdokument als Nachrichtentext auf.
1. Wenn die Anfrage gültig war, wird ein HTTP-Erfolgsantwortcode und ein [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) Shadow-Dokument als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
AWS IoT veröffentlicht außerdem eine MQTT-Nachricht zu dem `$aws/things/thingName/shadow/name/shadowName/update/delta` Thema mit einem [Antwortstatusdokument „/delta“](device-shadow-document.md#device-shadow-example-response-json-delta) Shadow-Dokument für alle Geräte oder Clients, die es abonnieren.
1. Wenn die Anfrage nicht gültig war, wird ein HTTP-Fehlerantwortcode an [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
Wenn das Gerät den `/desired`-Status zum `/update/delta`-Thema erhält, nimmt es die gewünschten Änderungen im Gerät vor. Anschließend wird eine Nachricht an das `/update`-Thema gesendet, um den aktuellen Status an den Schatten zu melden.
### Aktualisieren eines Schattens, wenn ein Gerät seinen aktuellen Status meldet
**Wenn ein Gerät seinen aktuellen Status an den Schatten mithilfe des MQTT-Protokolls meldet**
1. Das Gerät sollte diese MQTT-Themen abonnieren, bevor Sie den Schatten aktualisieren:
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/rejected`
+ `$aws/things/thingName/shadow/name/shadowName/update/delta`
+ `$aws/things/thingName/shadow/name/shadowName/update/documents`
1. Das Gerät meldet seinen aktuellen Status, indem es eine Nachricht zum `$aws/things/thingName/shadow/name/shadowName/update`-Thema veröffentlicht, das den aktuellen Status meldet, wie etwa in diesem Beispiel.
```
{
"state": {
"reported" : {
"color" : { "r" : 10 },
"engine" : "ON"
}
}
}
```
1. Wenn das Update AWS IoT akzeptiert wird, veröffentlicht es eine Nachricht zu den `$aws/things/thingName/shadow/name/shadowName/update/accepted` Themen zusammen mit einem [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) Schattendokument.
1. Wenn die Aktualisierungsanforderung nicht gültig ist, wird eine Nachricht mit dem `$aws/things/thingName/shadow/name/shadowName/update/rejected` Thema zusammen mit einem [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) Schattendokument AWS IoT veröffentlicht, das den Fehler beschreibt.
**Wenn ein Gerät den aktuellen Status mithilfe der API an den Schatten meldet**
1. Das Gerät ruft die `UpdateThingShadow`-API mit einem [Anfragestatusdokument](device-shadow-document.md#device-shadow-example-request-json)-Statusdokument als Nachrichtentext auf.
1. Wenn die Anfrage gültig war, wird der Shadow AWS IoT aktualisiert und ein HTTP-Erfolgsantwortcode mit einem [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) Shadow-Dokument als Hauptteil der Antwortnachricht zurückgegeben.
AWS IoT veröffentlicht außerdem eine MQTT-Nachricht zum `$aws/things/thingName/shadow/name/shadowName/update/delta` Thema mit einem [Antwortstatusdokument „/delta“](device-shadow-document.md#device-shadow-example-response-json-delta) Shadow-Dokument für alle Geräte oder Clients, die es abonnieren.
1. Wenn die Anfrage nicht gültig war, wird ein HTTP-Fehlerantwortcode an [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
### Optimistische Sperre
Sie können die Version des Statusdokuments verwenden, um sicherzustellen, dass Sie die neueste Version eines Geräteschattendokuments aktualisieren. Geben Sie bei einer Aktualisierungsanfrage eine Version an, lehnt der Service die Anfrage mit einem Konflikt-Antwortcode HTTP 409 ab, wenn die aktuelle Version des Statusdokuments nicht der angegebenen Version entspricht. Der Konfliktreaktionscode kann auch in jeder API vorkommen, die Änderungen am `ThingShadow` vornimmt, darunter `DeleteThingShadow`:
Beispiel:
Ausgangsdokument:
```
{
"state": {
"desired": {
"colors": [
"RED",
"GREEN",
"BLUE"
]
}
},
"version": 10
}
```
Aktualisierung: (die Versionen stimmen nicht überein; die Anfrage wird abgelehnt)
```
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 9
}
```
Ergebnis:
```
{
"code": 409,
"message": "Version conflict",
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
Aktualisierung: (die Versionen stimmen überein; die Anfrage wird angenommen)
```
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 10
}
```
Endzustand:
```
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 11
}
```
## Abrufen eines Shadow-Dokuments
Sie können ein Schattendokument abrufen, indem Sie die [GetThingShadow](device-shadow-rest-api.md#API_GetThingShadow)-API verwenden oder indem Sie das [/get](device-shadow-mqtt.md#get-pub-sub-topic)-Thema abonnieren und dazu veröffentlichen. Hierdurch wird ein vollständiges Schattendokument einschließlich aller Unterschiede zwischen den Statusarten `desired` und `reported` abgerufen. Die Vorgehensweise für diese Aufgabe ist unabhängig davon, ob das Gerät oder ein Client die Anforderung durchführt.
**So rufen Sie ein Schattendokument mithilfe des MQTT-Protokolls ab:**
1. Das Gerät oder der Client sollte diese MQTT-Themen abonnieren, bevor der Schatten aktualisiert wird:
+ `$aws/things/thingName/shadow/name/shadowName/get/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/get/rejected`
1. Das Gerät oder der Client veröffentlicht eine Nachricht mit einem leeren Nachrichtentext zum `$aws/things/thingName/shadow/name/shadowName/get`-Thema.
1. Wenn die Anfrage erfolgreich ist, wird eine Nachricht zum `$aws/things/thingName/shadow/name/shadowName/get/accepted` Thema mit einem [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) im Nachrichtentext AWS IoT veröffentlicht.
1. Wenn die Anfrage nicht gültig war, AWS IoT veröffentlicht eine Nachricht zum `$aws/things/thingName/shadow/name/shadowName/get/rejected` Thema mit einem [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) im Nachrichtentext.
**So rufen Sie ein Schattendokument mithilfe einer REST-API ab:**
1. Das Gerät oder Client ruft die `GetThingShadow`-API mit einem leeren Nachrichtentext auf.
1. Wenn die Anfrage gültig ist, wird ein HTTP-Erfolgsantwortcode mit einem [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) Schattendokument als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
1. Wenn die Anfrage nicht gültig ist, wird ein HTTP-Fehlerantwortcode an [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
## Löschen von Schattendaten
Es gibt zwei Möglichkeiten, Schattendaten zu löschen: Sie können bestimmte Eigenschaften im Schattendokument löschen oder den Schatten vollständig löschen.
+ Um bestimmte Eigenschaften aus einem Schatten zu löschen, aktualisieren Sie den Schatten. Legen Sie jedoch den Wert der Eigenschaften, die Sie löschen möchten, auf `null` fest. Felder mit dem Wert `null` werden aus dem Schattendokument entfernt.
+ Um den gesamten Schatten zu löschen, verwenden Sie die [DeleteThingShadow](device-shadow-rest-api.md#API_DeleteThingShadow)-API oder veröffentlichen Sie zum [/delete](device-shadow-mqtt.md#delete-pub-sub-topic)-Thema.
**Anmerkung**
Durch das Löschen eines Shadows wird seine Versionsnummer nicht sofort auf Null zurückgesetzt. Er wird nach 48 Stunden auf null zurückgesetzt.
### Löschen einer Eigenschaft aus einem Schattendokument
**So löschen Sie eine Eigenschaft aus einem Schatten mithilfe des MQTT-Protokolls:**
1. Das Gerät oder der Client sollte über ein aktuelles Schattendokument verfügen, damit es/er die zu ändernden Eigenschaften identifizieren kann. Weitere Informationen zum Abrufen des aktuellen Schattendokuments finden Sie unter [Abrufen eines Shadow-Dokuments](#retrieving-device-shadow).
1. Das Gerät oder der Client abonniert diese MQTT-Themen:
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/rejected`
1. Das Gerät oder der Client veröffentlicht ein `$aws/things/thingName/shadow/name/shadowName/update`-Anforderungsthema mit einem Statusdokument, das den Eigenschaften des zu löschenden Schattens `null`-Werte zuweist. Nur die zu ändernden Eigenschaften müssen in das Dokument aufgenommen werden. Dies ist ein Beispiel für ein Dokument, das die `engine`-Eigenschaft löscht.
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. Wenn die Aktualisierungsanforderung gültig ist, AWS IoT werden die angegebenen Eigenschaften im Shadow gelöscht und eine Nachricht mit dem `$aws/things/thingName/shadow/name/shadowName/update/accepted` Thema mit einem [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) Shadow-Dokument im Nachrichtentext veröffentlicht.
1. Wenn die Aktualisierungsanforderung nicht gültig ist, wird eine Nachricht mit dem `$aws/things/thingName/shadow/name/shadowName/update/rejected` Thema zusammen mit einem [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) Schattendokument AWS IoT veröffentlicht, das den Fehler beschreibt.
**So löschen Sie eine Eigenschaft aus einem Schatten mithilfe der REST-API:**
1. Das Gerät oder der Client ruft die `UpdateThingShadow`-API mit einer [Anfragestatusdokument](device-shadow-document.md#device-shadow-example-request-json) auf die den Eigenschaften des zu löschenden Schattens `null`-Werte zuweist. Fügen Sie nur die Eigenschaften, die Sie löschen möchten, in das Dokument ein. Dies ist ein Beispiel für ein Dokument, das die `engine`-Eigenschaft löscht.
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. Wenn die Anfrage gültig war, wird ein HTTP-Erfolgsantwortcode und ein [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) Shadow-Dokument als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
1. Wenn die Anfrage nicht gültig war, wird ein HTTP-Fehlerantwortcode an [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
### Löschen eines Shadows
Im Folgenden werden einige Aspekte beschrieben, die beim Löschen des Schattens eines Geräts berücksichtigt werden sollten.
+ Wenn Sie den Schattenstatus des Geräts auf `null` festlegen, wird der Schatten nicht gelöscht. Die Schattenversion wird beim nächsten Update erhöht.
+ Das Löschen eines Geräteschattens löscht das Objekt nicht. Das Löschen eines Objekts löscht den entsprechenden Geräteschatten nicht.
+ Durch das Löschen eines Shadows wird seine Versionsnummer nicht sofort auf Null zurückgesetzt. Er wird nach 48 Stunden auf null zurückgesetzt.
**So löschen Sie einen Schatten mithilfe des MQTT-Protokolls:**
1. Das Gerät oder der Client abonniert diese MQTT-Themen:
+ `$aws/things/thingName/shadow/name/shadowName/delete/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/delete/rejected`
1. Das Gerät oder der Client veröffentlicht eine `$aws/things/thingName/shadow/name/shadowName/delete`-mit einem leeren Nachrichtenpuffer.
1. Wenn die Löschanforderung gültig ist, wird der Shadow AWS IoT gelöscht und eine Nachricht mit dem `$aws/things/thingName/shadow/name/shadowName/delete/accepted` Thema und einem abgekürzten [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) Shadow-Dokument im Nachrichtentext veröffentlicht. Dies ist ein Beispiel für eine akzeptierte Löschmeldung:
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Wenn die Aktualisierungsanforderung nicht gültig ist, wird eine Nachricht mit dem `$aws/things/thingName/shadow/name/shadowName/delete/rejected` Thema zusammen mit einem [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) Shadow-Dokument AWS IoT veröffentlicht, das den Fehler beschreibt.
**So löschen Sie einen Schatten mithilfe der REST-API:**
1. Das Gerät oder der Client ruft die `DeleteThingShadow`-API mit einem leeren Nachrichtenpuffer auf.
1. Wenn die Anfrage gültig war, werden ein HTTP-Erfolgsantwortcode [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) und ein abgekürztes [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted) Schattendokument im Nachrichtentext AWS IoT zurückgegeben. Dies ist ein Beispiel für eine akzeptierte Löschmeldung:
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Wenn die Anfrage nicht gültig war, wird ein HTTP-Fehlerantwortcode an [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json) als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
# Geräteschatten-REST-API
Ein Schatten stellt den folgenden URI für die Aktualisierung der Statusinformationen bereit:
```
https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow
```
Der Endpunkt ist spezifisch für Ihren AWS-Konto. Um Ihren Endpunkt zu finden, können Sie:
+ den Befehl [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) aus dem AWS CLI verwenden.
+ Verwenden Sie die AWS IoT Konsoleneinstellungen. In den **Einstellungen** ist der Endpunkt unter **Benutzerdefinierter Endpunkt** aufgeführt
+ Verwenden Sie die Seite mit den Details der AWS IoT Konsolenelemente. In der Konsole:
1. Öffnen Sie **Verwalten** und wählen Sie unter **Verwalten** die Option **Objekte** aus.
1. Wählen Sie in der Liste der Objekte das Objekt aus, für das Sie den Endpunkt-URI abrufen möchten.
1. Wählen Sie die Registerkarte **Geräteschatten** und wählen Sie Ihren Schatten aus. Sie können den Endpunkt-URI im Abschnitt **Geräteschatten-URL** der **Geräteschatten-Detailseite** einsehen.
Der Endpunkt hat folgendes Format:
```
identifier.iot.region.amazonaws.com
```
Die Shadow-REST-API folgt denselben protocols/port HTTPS-Zuordnungen wie unter beschrieben. [Gerätekommunikationsprotokolle](protocols.md)
**Anmerkung**
Um den zu verwenden APIs, müssen Sie den Dienstnamen für die Authentifizierung verwenden`iotdevicegateway`. Weitere Informationen finden Sie unter [Io TData Plane](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html).
**Topics**
+ [GetThingShadow](#API_GetThingShadow)
+ [UpdateThingShadow](#API_UpdateThingShadow)
+ [DeleteThingShadow](#API_DeleteThingShadow)
+ [ListNamedShadowsForThing](#API_ListNamedShadowsForThing)
Sie können die API auch verwenden, um einen benannten Schatten zu erstellen, indem Sie `name=shadowName` als Teil des Abfrageparameters der API angeben.
## GetThingShadow
Ruft das Schattengerät für das angegebene Objekt ab.
Das Antwort-Statusdokument enthält das Delta zwischen dem Status `desired` (Soll) und dem Status `reported` (gemeldet).
**Anforderung**
Die Anfrage enthält die Standard-HTTP-Kopfzeilen sowie das folgende URI:
```
HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
Der `name`-Abfrageparameter ist für unbenannte (klassische) Schatten nicht erforderlich.
**Antwort**
Bei erfolgreicher Anfrage enthält die Antwort die Standard-HTTP-Kopfzeilen sowie den folgenden Code und Text:
```
HTTP 200
Response Body: response state document
```
Weitere Informationen finden Sie im [Antwort-Statusdokumentenbeispiel](device-shadow-document.md#device-shadow-example-response-json).
**Autorisierung**
Für das Abrufen eine Schattens ist eine Richtlinie erforderlich, die es dem Aufrufer erlaubt, die Aktion `iot:GetThingShadow` durchzuführen. Der Geräteschatten-Service akzeptiert zwei Arten der Authentifizierung: die Signatur-Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Client-Zertifikat.
Es folgt ein Beispiel für eine Richtlinie, die es dem Aufrufer erlaubt, einen Geräteschatten abzurufen:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:GetThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## UpdateThingShadow
Aktualisiert das Schattengerät für das angegebene Objekt.
Aktualisierungen betreffen lediglich die im Anfragestatusdokument angegebenen Felder. Ein Feld mit dem Wert `null` (Null) wird aus dem Geräteschatten entfernt.
**Anforderung**
Die Anfrage enthält die Standard-HTTP-Kopfzeilen sowie das/den folgende(n) URI und Text:
```
HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document
```
Der `name`-Abfrageparameter ist für unbenannte (klassische) Schatten nicht erforderlich.
Weitere Informationen finden Sie im [Anfragestatusdokumentenbeispiel](device-shadow-document.md#device-shadow-example-request-json).
**Antwort**
Bei erfolgreicher Anfrage enthält die Antwort die Standard-HTTP-Kopfzeilen sowie den folgenden Code und Text:
```
HTTP 200
Response body: response state document
```
Weitere Informationen finden Sie im [Antwort-Statusdokumentenbeispiel](device-shadow-document.md#device-shadow-example-response-json).
**Autorisierung**
Für das Aktualisieren eines Schattens ist eine Richtlinie erforderlich, die es dem Aufrufer erlaubt, die Aktion `iot:UpdateThingShadow` durchzuführen. Der Geräteschatten-Service akzeptiert zwei Arten der Authentifizierung: die Signatur-Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Client-Zertifikat.
Es folgt ein Beispiel für eine Richtlinie, die es dem Aufrufer erlaubt, einen Geräteschatten zu aktualisieren:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:UpdateThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## DeleteThingShadow
Löscht das Schattengerät für das angegebene Objekt.
**Anforderung**
Die Anfrage enthält die Standard-HTTP-Kopfzeilen sowie das folgende URI:
```
HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
Der `name`-Abfrageparameter ist für unbenannte (klassische) Schatten nicht erforderlich.
**Antwort**
Bei erfolgreicher Anfrage enthält die Antwort die Standard-HTTP-Kopfzeilen sowie den folgenden Code und Text:
```
HTTP 200
Response body: Empty response state document
```
Beachten Sie, dass durch das Löschen eines Shadows seine Versionsnummer nicht auf 0 zurückgesetzt wird.
**Autorisierung**
Für das Löschen eine Geräteschattens ist eine Richtlinie erforderlich, die es dem Aufrufer erlaubt, die Aktion `iot:DeleteThingShadow` durchzuführen. Der Geräteschatten-Service akzeptiert zwei Arten der Authentifizierung: die Signatur-Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Client-Zertifikat.
Es folgt ein Beispiel für eine Richtlinie, die es dem Aufrufer erlaubt, einen Geräteschatten zu löschen:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DeleteThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## ListNamedShadowsForThing
Listet die Schatten für das angegebene Objekt auf.
**Anforderung**
Die Anfrage enthält die Standard-HTTP-Kopfzeilen sowie das folgende URI:
```
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
```
nextToken
Das Token zum Abruf des nächsten Ergebnissatzes.
Dieser Wert wird für nach Seiten organisierte Ergebnisse zurückgegeben und in dem Aufruf verwendet, der die nächste Seite zurückgibt.
pageSize
Die Anzahl der Schattennamen, die bei jedem Aufruf zurückgegeben werden sollen. Siehe auch `nextToken`.
thingName
Der Name des Objekts, für das die benannten Schatten aufgelistet werden sollen.
**Antwort**
Falls erfolgreich, enthält die Antwort die Standard-HTTP-Kopfzeilen sowie den folgenden Antwortcode und eine [Antwortdokument für die Schattennamenliste](device-shadow-document.md#device-shadow-list-json).
**Anmerkung**
Der unbenannte (klassische) Schatten wird in dieser Liste nicht angezeigt. Die Antwort ist eine leere Liste, wenn Sie nur einen klassischen Schatten haben oder wenn der von `thingName` Ihnen angegebene Schatten nicht existiert.
```
HTTP 200
Response body: Shadow name list document
```
**Autorisierung**
Für das Löschen eines Geräteschattens ist eine Richtlinie erforderlich, die es dem Aufrufer erlaubt, die Aktion `iot:ListNamedShadowsForThing` durchzuführen. Der Geräteschatten-Service akzeptiert zwei Arten der Authentifizierung: die Signatur-Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Client-Zertifikat.
Es folgt ein Beispiel für eine Richtlinie, die es dem Aufrufer erlaubt, die benannten Schatten eines Objekts zu aktualisieren:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:ListNamedShadowsForThing",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
# MQTT-Themen für Geräteschatten
Der Device Shadow-Service verwendet reservierte MQTT-Themen, um es Anwendungen und Geräten zu ermöglichen, die Statusinformationen für ein Gerät (Schatten) abzurufen, zu aktualisieren oder zu löschen.
Das Veröffentlichen in und Abonnieren von Schattengerätethemen erfordert eine themenbasierte Autorisierung. AWS IoT behält sich das Recht vor, der vorhandenen Themenstruktur neue Themen hinzuzufügen. Aus diesem Grund empfehlen wir, Abonnements mit Platzhaltern von Schattengeräte-Topics zu vermeiden. Vermeiden Sie es beispielsweise, Themenfilter zu abonnieren, `$aws/things/thingName/shadow/#` weil die Anzahl der Themen, die diesem Themenfilter entsprechen, zunehmen könnte, wenn neue Schattenthemen AWS IoT eingeführt werden. Beispiele für Nachrichten, die zu diesen Topics veröffentlichten wurden, finden Sie unter [Interaktion mit Schatten](device-shadow-data-flow.md).
Schatten können benannt oder unbenannt sein (klassisch). Die jeweils verwendeten Themen unterscheiden sich nur durch das Themenpräfix. In dieser Tabelle wird das Themenpräfix angezeigt, das von jedem Schattentyp verwendet wird.
| *ShadowTopicPrefix* Wert | Schattentyp |
| --- | --- |
| \$1aws/things/thingName/shadow | Unbenannter (klassischer) Schatten |
| \$1aws/things/thingName/shadow/name/shadowName | Benannter Schatten |
Um ein vollständiges Thema zu erstellen, wählen Sie die `ShadowTopicPrefix` für den Schattentyp aus, auf den Sie verweisen möchten, ersetzen Sie `thingName` und gegebenenfalls `shadowName` durch die entsprechenden Werte und fügen Sie diese dann an den Themen-Stub an, wie in den folgenden Abschnitten dargestellt.
Nachstehend finden Sie die MQTT-Themen, die für die Interaktion mit Schatten verwendet wurden.
**Topics**
+ [/get](#get-pub-sub-topic)
+ [/get/accepted](#get-accepted-pub-sub-topic)
+ [/update/rejected](#get-rejected-pub-sub-topic)
+ [/update](#update-pub-sub-topic)
+ [/update/delta](#update-delta-pub-sub-topic)
+ [/update/accepted](#update-accepted-pub-sub-topic)
+ [/update/documents](#update-documents-pub-sub-topic)
+ [/update/rejected](#update-rejected-pub-sub-topic)
+ [/delete](#delete-pub-sub-topic)
+ [/delete/accepted](#delete-accepted-pub-sub-topic)
+ [/delete/rejected](#delete-rejected-pub-sub-topic)
## /get
Veröffentlichen Sie eine leere Nachricht in diesem Thema, um den Geräteschatten abzurufen:
```
ShadowTopicPrefix/get
```
AWS IoT antwortet mit einer Veröffentlichung auf entweder [/get/accepted](#get-accepted-pub-sub-topic) oder[/update/rejected](#get-rejected-pub-sub-topic).
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get"
]
}
]
}
```
## /get/accepted
AWS IoT veröffentlicht ein Antwort-Shadow-Dokument zu diesem Thema, wenn der Shadow des Geräts zurückgegeben wird:
```
ShadowTopicPrefix/get/accepted
```
Weitere Informationen finden Sie unter [Antwortstatusdokumente](device-shadow-document.md#device-shadow-example-response-json).
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/accepted"
]
}
]
}
```
## /update/rejected
AWS IoT veröffentlicht ein Fehlerantwortdokument zu diesem Thema, wenn es den Schatten des Geräts nicht zurückgeben kann:
```
ShadowTopicPrefix/get/rejected
```
Weitere Informationen finden Sie unter [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json).
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/rejected"
]
}
]
}
```
## /update
Veröffentlichen Sie in diesem Thema ein Anfragestatusdokument, um den Geräteschatten zu aktualisieren:
```
ShadowTopicPrefix/update
```
Der Nachrichtentext enthält ein [partielles Anfragestatusdokument](device-shadow-document.md#device-shadow-example-request-json).
Ein Client, der versucht, den Status eines Geräts zu aktualisieren, sendet ein JSON-Anfragestatusdokument mit einer `desired`-Eigenschaft wie der folgenden:
```
{
"state": {
"desired": {
"color": "red",
"power": "on"
}
}
}
```
Ein Gerät, das seinen Schatten aktualisiert, würde ein JSON-Anfragestatusdokument mit der `reported`-Eigenschaft senden, z. B.:
```
{
"state": {
"reported": {
"color": "red",
"power": "on"
}
}
}
```
AWS IoT antwortet, indem es entweder [/update/accepted](#update-accepted-pub-sub-topic) oder veröffentlicht[/update/rejected](#update-rejected-pub-sub-topic).
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update"
]
}
]
}
```
## /update/delta
AWS IoT veröffentlicht ein Antwortstatusdokument zu diesem Thema, wenn es eine Änderung für den Shadow des Geräts akzeptiert, und das Antwortstatusdokument verschiedene Werte für `desired` und gibt `reported` an:
```
ShadowTopicPrefix/update/delta
```
Der Nachrichtenpuffer enthält eine [Antwortstatusdokument „/delta“](device-shadow-document.md#device-shadow-example-response-json-delta).
### Nachrichtentextdetails
+ Eine in `update/delta` veröffentlichte Nachricht umfasst nur die gewünschten Attribute, die sich zwischen dem Abschnitt `desired` (Soll) und dem Abschnitt `reported` (gemeldet) Abschnitt unterscheiden. Sie enthält alle diese Attribute, unabhängig davon, ob diese in der Nachricht zur aktuellen Aktualisierung enthalten waren oder bereits in AWS IoT gespeichert wurden. Attribute, die sich nicht zwischen dem Abschnitt `desired` (Soll) und dem Abschnitt `reported` (gemeldet) Abschnitt unterscheiden, sind nicht enthalten.
+ Wenn sich ein Attribut im Abschnitt `reported` (gemeldet) befindet, jedoch kein Pendant im Abschnitt `desired` (Soll), dann ist es nicht enthalten.
+ Ist ein Attribut im Abschnitt `desired` (Soll) vorhanden, besitzt jedoch kein Pendant im Abschnitt `reported` (gemeldet), dann ist es enthalten.
+ Wenn ein Attribut aus dem Abschnitt `reported` (gemeldet) gelöscht wurde, aber sich nach wie vor im Abschnitt `desired` (Soll) befindet, dann ist es enthalten.
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/delta"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/delta"
]
}
]
}
```
## /update/accepted
AWS IoT veröffentlicht ein Antwortstatusdokument zu diesem Thema, wenn eine Änderung für den Shadow des Geräts akzeptiert wird:
```
ShadowTopicPrefix/update/accepted
```
Der Nachrichtenpuffer enthält eine [Antwortstatusdokument „/accepted“](device-shadow-document.md#device-shadow-example-response-json-accepted).
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/accepted"
]
}
]
}
```
## /update/documents
AWS IoT veröffentlicht ein Statusdokument zu diesem Thema, wenn eine Aktualisierung des Shadows erfolgreich durchgeführt wurde:
```
ShadowTopicPrefix/update/documents
```
Der Nachrichtentext enthält eine [/Dokumente, Antwortstatusdokument](device-shadow-document.md#device-shadow-example-response-json-documents).
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/documents"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/documents"
]
}
]
}
```
## /update/rejected
AWS IoT veröffentlicht ein Fehlerantwortdokument zu diesem Thema, wenn eine Änderung für den Shadow des Geräts abgelehnt wird:
```
ShadowTopicPrefix/update/rejected
```
Der Nachrichtentext enthält eine [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json).
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/rejected"
]
}
]
}
```
## /delete
Um einen Geräteschatten zu löschen, veröffentlichen Sie im Löschthema eine leere Nachricht.
```
ShadowTopicPrefix/delete
```
Der Inhalt der Nachricht wird ignoriert.
Beachten Sie, dass durch das Löschen eines Shadows seine Versionsnummer nicht auf 0 zurückgesetzt wird.
AWS IoT antwortet, indem es entweder [/delete/accepted](#delete-accepted-pub-sub-topic) oder [/delete/rejected](#delete-rejected-pub-sub-topic) veröffentlicht.
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete"
]
}
]
}
```
## /delete/accepted
AWS IoT veröffentlicht eine Nachricht zu diesem Thema, wenn der Schatten eines Geräts gelöscht wird:
```
ShadowTopicPrefix/delete/accepted
```
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/accepted"
]
}
]
}
```
## /delete/rejected
AWS IoT veröffentlicht ein Dokument mit einer Fehlermeldung zu diesem Thema, wenn der Schatten des Geräts nicht gelöscht werden kann:
```
ShadowTopicPrefix/delete/rejected
```
Der Nachrichtentext enthält eine [Fehlerantwortdokument](device-shadow-document.md#device-shadow-example-error-json).
### Beispielrichtline
Im Folgenden finden Sie ein Beispiel für die erforderliche Richtlinie:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/rejected"
]
}
]
}
```
# 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" ]
}
}
```
# Device Shadow-Fehlermeldungen
Der Device Shadow-Service veröffentlicht (über MQTT) eine Meldung im Thema "Fehler”, wenn ein Versuch, das Statusdokument zu ändern, fehlschlägt. Diese Meldung wird lediglich als Antwort auf eine Veröffentlichungsanfrage zu einem der reservierten `$aws`-Topics ausgegeben. Aktualisiert der Client das Dokument mittels REST-API, erhält er den HTTP-Fehlercode als Teil seiner Antwort, und es werden keine MQTT-Fehlermeldungen ausgegeben.
****
| HTTP-Fehlercode | Fehlermeldungen |
| --- | --- |
| 400 (Ungültige Anfrage) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/device-shadow-error-messages.html) |
| 401 (Unauthorized) (Unautorisiert) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/device-shadow-error-messages.html) |
| 403 (Forbidden) (Unzulässig) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/device-shadow-error-messages.html) |
| 404 (Not Found) (Nicht gefunden) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/device-shadow-error-messages.html) |
| 409 (Conflict) (Konflikt) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/device-shadow-error-messages.html) |
| 413 (Payload Too Large) (Nutzlast zu hoch) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/device-shadow-error-messages.html) |
| 415 (Unsupported Media Type) (Nicht unterstützter Medientyp) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/device-shadow-error-messages.html) |
| 429 (Too Many Requests) (Zu viele Anfragen) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/device-shadow-error-messages.html) |
| 500 (Internal Server Error) (Interner Serverfehler) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/device-shadow-error-messages.html) |