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. # 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.