AWS IoT
Entwicklerhandbuch

Verwendung von Schatten

AWS IoT bietet drei Verfahren zur Arbeit mit einem Geräteschatten an:

UPDATE

Legt einen Geräteschatten an, wenn keiner vorhanden ist, oder aktualisiert den Inhalt eines Geräteschattens mit den in der Anfrage bereitgestellten Daten. Die Daten werden zusammen mit den Zeitstempelangaben gespeichert, um anzugeben, wann sie zuletzt aktualisiert wurden. Es werden Nachrichten an alle Abonnenten versendet mit Angaben zum Unterschied zwischen dem desired (Soll)- Status oder dem reported (gemeldeten) Status (Delta). Geräte oder Anwendungen, die eine Nachricht erhalten, können eine Aktion basierend auf dem Unterschied zwischen dem Status desired (Soll) Status oder dem Status reported (gemeldet) 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 anzuzeigen.

GET

Ruft den letzten im Geräteschatten gespeicherten Status ab (z. B. beim Startup eines Geräts, um die Konfiguration und den letzten Betriebszustand abzurufen). Diese Methode gibt das vollständige JSON-Dokument einschließlich der Metadaten zurück.

DELETE

Löscht einen Geräteschatten einschließlich seines gesamten Inhalts. Dies entfernt das JSON-Dokument aus dem Datenspeicher. Sie können einen gelöschten Geräteschatten zwar nicht wiederherstellen, Sie können jedoch einen neuen Schatten mit demselben Namen anlegen.

Protokollunterstützung

Diese Methoden werden sowohl von MQTT als auch von einer RESTful-API über HTTPS unterstützt. Da es sich bei MQTT um ein Kommunikationsmodell für Veröffentlichungen/Abonnements handelt, implementiert AWS IoT eine Reihe von reservierten Themen. Geräte oder Anwendungen abonnieren diese Topics vor der Veröffentlichung auf einem AnforderungsTopic, um ein Anforderungs-/Antwort-Verhalten zu implementieren. Weitere Informationen finden Sie unter MQTT-Themen für Schatten und RESTful-API für Device Shadow.

Einen Schatten aktualisieren

Sie können einen Geräteschatten aktualisieren, indem Sie die UpdateThingShadow RESTful-API verwenden oder im Thema /update veröffentlichen. Aktualisierungen betreffen lediglich die in der Anfrage angegebenen Felder.

Ursprungszustand:

{ "state": { "reported" : { "color" : { "r" :255, "g": 255, "b": 0 } } } }

Es wird eine Aktualisierungsnachricht gesendet:

{ "state": { "desired" : { "color" : { "r" : 10 }, "engine" : "ON" } } }

Das Gerät empfängt den Status desired (Soll) im Topic /update/delta, das durch die vorherige /update (Aktualisierungs-) Nachricht ausgelöst wird und führt dann die gewünschten Änderungen durch. Anschließend bestätigt das Gerät seinen aktualisierten Status anhand des Abschnitts reported (gemeldet) im JSON-Dokument des Schattens.

Endzustand:

{ "state": { "reported" : { "color" : { "r" : 10, "g" : 255, "b": 0 }, "engine" : "ON" } } }

Ein Schattendokument abrufen

Sie können einen Geräteschatten abrufen, indem Sie die GetThingShadow RESTful-API verwenden oder das Thema /get abonnieren und darin veröffentlichen. Damit wird das gesamte Dokument zuzüglich des Deltas zwischen dem Status desired (Soll) bzw. dem Status reported (gemeldet) abgerufen.

Beispieldokument:

{ "state": { "desired": { "lights": { "color": "RED" }, "engine": "ON" }, "reported": { "lights": { "color": "GREEN" }, "engine": "ON" } }, "metadata": { "desired": { "lights": { "color": { "timestamp": 123456 }, "engine": { "timestamp": 123456 } } }, "reported": { "lights": { "color": { "timestamp": 789012 } }, "engine": { "timestamp": 789012 } }, "version": 10, "timestamp": 123456789 } }

Antwort:

{ "state": { "desired": { "lights": { "color": "RED" }, "engine": "ON" }, "reported": { "lights": { "color": "GREEN" }, "engine": "ON" }, "delta": { "lights": { "color": "RED" } } }, "metadata": { "desired": { "lights": { "color": { "timestamp": 123456 }, }, "engine": { "timestamp": 123456 } }, "reported": { "lights": { "color": { "timestamp": 789012 } }, "engine": { "timestamp": 789012 } }, "delta": { "lights": { "color": { "timestamp": 123456 } } } }, "version": 10, "timestamp": 123456789 }

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.

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:

409 Conflict

Aktualisierung: (die Versionen stimmen überein; die Anfrage wird angenommen)

{ "state": { "desired": { "colors": [ "BLUE" ] } }, "version": 10 }

Endzustand:

{ "state": { "desired": { "colors": [ "BLUE" ] } }, "version": 11 }

Daten löschen

Sie können Daten aus einem Geräteschatten löschen, indem Sie im Thema /update veröffentlichen und die zu löschenden Felder auf Null einstellen. Ein Feld mit dem Wert null (Null) wird aus dem Dokument entfernt.

Ursprungszustand:

{ "state": { "desired" : { "lights": { "color": "RED" }, "engine" : "ON" }, "reported" : { "lights" : { "color": "GREEN" }, "engine" : "OFF" } } }

Es wird eine Aktualisierungsnachricht gesendet:

{ "state": { "desired": null, "reported": { "engine": null } } }

Endzustand:

{ "state": { "reported" : { "lights" : { "color" : "GREEN" } } } }

Sie können alle Daten aus einem Geräteschatten löschen, indem Sie seinen Status auf null (Null) einstellen. Beispielsweise werden mit dem Senden der folgenden Nachricht alle Statusdaten gelöscht, der Geräteschatten wird jedoch beibehalten.

{ "state": null }

Der Geräteschatten ist nach wie vor vorhanden, auch wenn der Status auf null (Null) festgelegt ist. Die Versionsnummer des Schattens erhöht sich, sobald die nächste Aktualisierung durchgeführt wurde.

Einen Schatten löschen

Sie können ein Geräteschattendokument löschen, indem Sie die DeleteThingShadow RESTful-API verwenden oder im Thema /delete veröffentlichen.

Anmerkung

Das Löschen eines Geräteschattens löscht nicht das Objekt. Das Löschen eines Objekts löscht nicht den entsprechenden Geräteschatten.

Ursprungszustand:

{ "state": { "desired" : { "lights": { "color": "RED" }, "engine" : "ON" }, "reported" : { "lights" : { "color": "GREEN" }, "engine" : "OFF" } } }

Im /Löschen-Topic wird eine leere Nachricht veröffentlicht.

Endzustand:

HTTP 404 - resource not found

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.

Statusänderungen beobachten

Wenn ein Geräteschatten aktualisiert wird, werden in zwei Themen MQTT-Nachrichten veröffentlicht:

  • $aws/things/thing-name/shadow/update/accepted

  • $aws/things/thing-name/shadow/update/delta

Die an das Topic update/delta gesendete Nachricht ist für das Gerät bestimmt, dessen Status aktualisiert wird. Diese Nachricht enthält nur den Unterschied zwischen dem Abschnitt desired (Soll) und dem Abschnitt reported (gemeldet) des Geräteschattendokuments. Bei Erhalt dieser Nachricht sollte das Gerät entscheiden, ob die angefragte Änderung durchgeführt wird. Wird der Status des Geräts geändert, sollte es seinen neuen aktuellen Status im Thema $aws/things/thing-name/shadow/update veröffentlichen.

Geräte und Anwendungen können beide Topics abonnieren, um darüber benachrichtigt zu werden, sobald sich der Status des Dokuments geändert hat.

Hier sehen Sie ein Beispiel für diesen Ablauf:

  1. Ein Gerät meldet seinen Status.

  2. Das System aktualisiert das Statusdokument in seinem persistenten Datenspeicher.

  3. Das System veröffentlicht eine Delta-Nachricht, die nur das Delta enthält und sich an die abonnierten Geräte richtet. Geräte sollten dieses Topic abonnieren, um Aktualisierungen zu erhalten.

  4. Der Geräteschatten veröffentlicht eine angenommene Nachricht, die das gesamte empfangene Dokument einschließlich der Metadaten enthält. Anwendungen sollten dieses Topic abonnieren, um Aktualisierungen zu erhalten.

Nachrichtreihenfolge

Es ist nicht gewährleistet, dass Nachrichten aus dem AWS IoT-Service im Gerät in einer bestimmten Reihenfolge ankommen.

Ursprüngliches Statusdokument:

{ "state" : { "reported" : { "color" : "blue" } }, "version" : 10, "timestamp": 123456777 }

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.

Schatten-Nachrichten kürzen

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(2)}/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 "+” 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 vorzugeben, in dem erneut eine Veröffentlichung erfolgen soll. topic(2) ermittelt den Gerätenamen im Ursprungs-Thema. Weitere Informationen zum Erstellen von Regeln finden Sie unter -Regeln.