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.
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 demdesired
und demreported
Status 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
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 Dienst kann den Status eines Shadows aktualisieren, indem Sie das UpdateThingShadow API oder verwenden, indem Sie es im /update Thema veröffentlichen. Aktualisierungen betreffen lediglich die in der Anfrage angegebenen Felder.
Aktualisieren eines Schattens, wenn ein Client eine Statusänderung anfordert
Wenn ein Client mithilfe des MQTT Protokolls eine Statusänderung in einem Shadow anfordert
-
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.
-
Der Kunde abonniert die folgenden 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
-
-
Der Client veröffentlicht ein
$aws/things/
-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.thingName
/shadow/name/shadowName
/update{ "state": { "desired": { "color": { "r": 10 }, "engine": "ON" } } }
-
Wenn die Aktualisierungsanfrage gültig ist, wird der gewünschte Status im Shadow AWS IoT aktualisiert und Nachrichten zu den folgenden Themen veröffentlicht:
-
$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“-Schattendokument, und die/update/delta
-Nachricht enthält ein Antwortstatusdokument „/delta“-Schattendokument. -
-
Wenn die Aktualisierungsanforderung nicht gültig ist, wird eine Nachricht mit dem
$aws/things/
Thema zusammen mit einem Fehlerantwortdokument Schattendokument AWS IoT veröffentlicht, das den Fehler beschreibt.thingName
/shadow/name/shadowName
/update/rejected
Wenn ein Client eine Statusänderung in einem Shadow anfordert, indem er den API
-
Der Client ruft das
UpdateThingShadow
API mit einem Anfragestatusdokument Statusdokument als Nachrichtentext auf. -
Wenn die Anfrage gültig war, werden ein HTTP Erfolgsantwortcode und ein Antwortstatusdokument „/accepted“ Schattendokument als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
AWS IoT veröffentlicht außerdem eine MQTT Nachricht zu dem
$aws/things/
Thema mit einem Antwortstatusdokument „/delta“ Shadow-Dokument für alle Geräte oder Clients, die es abonnieren.thingName
/shadow/name/shadowName
/update/delta -
Wenn die Anfrage nicht gültig war, wird der HTTP Fehlerantwortcode an Fehlerantwortdokument 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 mithilfe des MQTT Protokolls seinen aktuellen Status an den Shadow meldet
-
Das Gerät sollte die folgenden MQTT Themen abonnieren, bevor es den Shadow aktualisiert:
-
$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
-
-
Das Gerät meldet seinen aktuellen Status, indem es eine Nachricht zum
$aws/things/
-Thema veröffentlicht, das den aktuellen Status meldet, wie etwa in diesem Beispiel.thingName
/shadow/name/shadowName
/update{ "state": { "reported" : { "color" : { "r" : 10 }, "engine" : "ON" } } }
-
Wenn das Update AWS IoT akzeptiert wird, veröffentlicht es eine Nachricht zu den
$aws/things/
Themen zusammen mit einem Antwortstatusdokument „/accepted“ Shadow-Dokument.thingName
/shadow/name/shadowName
/update/accepted -
Wenn die Aktualisierungsanforderung nicht gültig ist, wird eine Nachricht mit dem
$aws/things/
Thema zusammen mit einem Fehlerantwortdokument Schattendokument AWS IoT veröffentlicht, das den Fehler beschreibt.thingName
/shadow/name/shadowName
/update/rejected
Wenn ein Gerät seinen aktuellen Status an den Shadow meldet, indem es den API
-
Das Gerät ruft das
UpdateThingShadow
API mit einem Anfragestatusdokument Statusdokument als Nachrichtentext auf. -
Wenn die Anfrage gültig war, AWS IoT aktualisiert es den Shadow und gibt einen HTTP Erfolgsantwortcode mit einem Antwortstatusdokument „/accepted“ Shadow-Dokument als Hauptteil der Antwortnachricht zurück.
AWS IoT veröffentlicht außerdem eine MQTT Nachricht zum
$aws/things/
Thema mit einem Antwortstatusdokument „/delta“ Shadow-Dokument für alle Geräte oder Clients, die es abonnieren.thingName
/shadow/name/shadowName
/update/delta -
Wenn die Anfrage nicht gültig war, wird der HTTP Fehlerantwortcode an Fehlerantwortdokument 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. Wenn Sie eine Version mit einer Aktualisierungsanforderung angeben, lehnt der Dienst die Anfrage mit einem HTTP 409-Konflikt-Antwortcode ab, falls die aktuelle Version des Statusdokuments nicht mit der bereitgestellten Version übereinstimmt. Der Konfliktreaktionscode kann auch bei allen Änderungen auftreten APIThingShadow
, darunter: DeleteThingShadow
Beispielsweise:
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 mithilfe von GetThingShadow API oder abrufen, indem Sie das Thema abonnieren und veröffentlichen. /get 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.
Um ein Shadow-Dokument mithilfe des MQTT Protokolls abzurufen
-
Das Gerät oder der Client sollte die folgenden MQTT Themen abonnieren, bevor der Shadow aktualisiert wird:
-
$aws/things/
thingName
/shadow/name/shadowName
/get/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/get/rejected
-
-
Das Gerät oder der Client veröffentlicht eine Nachricht mit einem leeren Nachrichtentext zum
$aws/things/
-Thema.thingName
/shadow/name/shadowName
/get -
Wenn die Anfrage erfolgreich ist, wird eine Nachricht zum
$aws/things/
Thema mit einem Antwortstatusdokument „/accepted“ im Nachrichtentext AWS IoT veröffentlicht.thingName
/shadow/name/shadowName
/get/accepted -
Wenn die Anfrage nicht gültig war, AWS IoT veröffentlicht eine Nachricht zum
$aws/things/
Thema mit einem Fehlerantwortdokument im Nachrichtentext.thingName
/shadow/name/shadowName
/get/rejected
Um ein Schattendokument mit einem abzurufen REST API
-
Das Gerät oder der Client ruft den
GetThingShadow
API mit einem leeren Nachrichtentext auf. -
Wenn die Anfrage gültig ist, wird ein HTTP Erfolgsantwortcode mit einem Antwortstatusdokument „/accepted“ Schattendokument als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
-
Wenn die Anfrage nicht gültig ist, wird ein HTTP Fehlerantwortcode an Fehlerantwortdokument 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 Wertnull
werden aus dem Schattendokument entfernt. -
Um den gesamten Schatten zu löschen, verwenden Sie das DeleteThingShadow API oder veröffentlichen Sie es im /delete Thema.
Anmerkung
Durch das Löschen eines Schattens 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
Um mithilfe des MQTT Protokolls eine Eigenschaft aus einem Schatten zu löschen
-
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.
-
Das Gerät oder der Client abonniert die folgenden MQTT Themen:
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected
-
-
Das Gerät oder der Client veröffentlicht ein
$aws/things/
-Anforderungsthema mit einem Statusdokument, das den Eigenschaften des zu löschenden SchattensthingName
/shadow/name/shadowName
/updatenull
-Werte zuweist. Nur die zu ändernden Eigenschaften müssen in das Dokument aufgenommen werden. Dies ist ein Beispiel für ein Dokument, das dieengine
-Eigenschaft löscht.{ "state": { "desired": { "engine": null } } }
-
Wenn die Aktualisierungsanfrage gültig ist, AWS IoT werden die angegebenen Eigenschaften im Shadow gelöscht und eine Nachricht mit dem
$aws/things/
Thema mit einem Antwortstatusdokument „/accepted“ Shadow-Dokument im Nachrichtentext veröffentlicht.thingName
/shadow/name/shadowName
/update/accepted -
Wenn die Aktualisierungsanforderung nicht gültig ist, wird eine Nachricht mit dem
$aws/things/
Thema zusammen mit einem Fehlerantwortdokument Schattendokument AWS IoT veröffentlicht, das den Fehler beschreibt.thingName
/shadow/name/shadowName
/update/rejected
Um eine Eigenschaft aus einem Schatten zu löschen, verwenden Sie REST API
-
Das Gerät oder der Client ruft das
UpdateThingShadow
API mit einem aufAnfragestatusdokument, das den Eigenschaften des zu löschenden Schattensnull
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 dieengine
-Eigenschaft löscht.{ "state": { "desired": { "engine": null } } }
-
Wenn die Anfrage gültig war, wird ein HTTP Erfolgsantwortcode und ein Antwortstatusdokument „/accepted“ Shadow-Dokument als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.
-
Wenn die Anfrage nicht gültig war, wird ein HTTP Fehlerantwortcode an Fehlerantwortdokument 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.
Um einen Shadow mithilfe des MQTT Protokolls zu löschen
-
Das Gerät oder der Client abonniert die folgenden MQTT Themen:
-
$aws/things/
thingName
/shadow/name/shadowName
/delete/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/delete/rejected
-
-
Das Gerät oder der Client veröffentlicht eine
$aws/things/
-mit einem leeren Nachrichtenpuffer.thingName
/shadow/name/shadowName
/delete -
Wenn die Löschanforderung gültig ist, wird der Shadow AWS IoT gelöscht und eine Nachricht mit dem
$aws/things/
Thema und einem abgekürzten Antwortstatusdokument „/accepted“ Shadow-Dokument im Nachrichtentext veröffentlicht. Dies ist ein Beispiel für eine akzeptierte Löschmeldung:thingName
/shadow/name/shadowName
/delete/accepted{ "version": 4, "timestamp": 1591057529 }
-
Wenn die Aktualisierungsanforderung nicht gültig ist, wird eine Nachricht mit dem
$aws/things/
Thema zusammen mit einem Fehlerantwortdokument Shadow-Dokument AWS IoT veröffentlicht, das den Fehler beschreibt.thingName
/shadow/name/shadowName
/delete/rejected
Um einen Schatten mit dem zu löschen REST API
-
Das Gerät oder der Client ruft den
DeleteThingShadow
API mit einem leeren Nachrichtenpuffer auf. -
Wenn die Anfrage gültig war, werden ein HTTP Erfolgsantwortcode Antwortstatusdokument „/accepted“ und ein abgekürztes Antwortstatusdokument „/accepted“ Schattendokument im Nachrichtentext AWS IoT zurückgegeben. Dies ist ein Beispiel für eine akzeptierte Löschmeldung:
{ "version": 4, "timestamp": 1591057529 }
-
Wenn die Anfrage nicht gültig war, wird ein HTTP Fehlerantwortcode an Fehlerantwortdokument als Hauptteil der Antwortnachricht AWS IoT zurückgegeben.