AWS IoT
Entwicklerhandbuch

MQTT-Themen für Schatten

Der Device Shadow-Services verwendet reservierte MQTT-Themen, um es Anwendungen und Geräten zu ermöglichen, die Statusinformationen für ein Gerät (Schattengerät) abzurufen, zu aktualisieren oder zu löschen. Die Namen dieser Topics beginnen mit $aws/things/thingName/shadow. 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 beispielsweise das Abonnieren von Themenfiltern wie $aws/things/thingName/shadow/#, weil die Zahl der Themen, die mit diesem Themenfilter übereinstimmen, steigen könnte, da AWS IoT neue Themen zu Schattengeräten einführt. Beispiele für Nachrichten, die zu diesen Topics veröffentlichten wurden, finden Sie unter Datenfluss des Device Shadow-Service.

Nachstehend finden Sie die MQTT-Themen, die für die Interaktion mit Schatten verwendet wurden.

/update

Veröffentlichen Sie in diesem Thema ein Antwort-Statusdokument, um den Geräteschatten zu aktualisieren:

$aws/things/thingName/shadow/update

Ein Client, der versucht, den Status eines Geräts zu aktualisieren, würde ein JSON-Anfrage-Statusdokument senden, das wie folgt aussieht:

{ "state" : { "desired" : { "color" : "red", "power" : "on" } } }

Ein Gerät, das seinen Schatten aktualisiert, würde ein JSON-Anfrage-Statusdokument senden, das wie folgt aussieht:

{ "state" : { "reported" : { "color" : "red", "power" : "on" } } }

AWS IoT antwortet mittels Veröffentlichung entweder in /update/accepted oder /update/rejected.

Weitere Informationen finden Sie unter Anfrage-Statusdokumente.

Beispiel für eine Richtlinie

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:region:account:topic/$aws/things/thingName/shadow/update"] }] }

/update/accepted

AWS IoT veröffentlicht ein Antwort-Statusdokument in diesem Thema, wenn es eine Änderung für den Geräteschatten akzeptiert:

$aws/things/thingName/shadow/update/accepted

Weitere Informationen finden Sie unter Antwort-Statusdokumente.

Beispiel für eine Richtlinie

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:region:account:topicfilter/$aws/things/thingName/shadow/update/accepted"] }, { "Effect": "Allow", "Action": ["iot:Receive"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/accepted"] } ] }

/update/documents

AWS IoT veröffentlicht immer dann ein Statusdokument zu diesem Thema, wenn das Schattengerät erfolgreich aktualisiert wurde:

$aws/things/thingName/shadow/update/documents

Das JSON-Dokument wird zwei primäre Knoten enthalten: previous (vorheriger) und current (aktueller). Der previous (vorherige) Knoten wird den Inhalt des vollständigen Dokuments zum Schattengerät enthalten, bevor die Aktualisierung durchgeführt wurde, wohingegen der current (aktuelle) Knoten den vollständigen Dokumenteninhalt zum Schattengerät enthält, nachdem die Aktualisierung erfolgreich angewendet wurde. Wird der Schatten zum ersten Mal aktualisiert (angelegt), enthält der previous (vorherige) Knoten den Wert null (Null).

Beispiel für eine Richtlinie

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:region:account:topicfilter/$aws/things/thingName/shadow/update/documents"] }, { "Effect": "Allow", "Action": ["iot:Receive"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/accepted"] } ] }

/update/rejected

AWS IoT veröffentlicht ein Dokument über Fehlermeldungen in diesem Thema, wenn es eine Änderung für den Geräteschatten ablehnt:

$aws/things/thingName/shadow/update/rejected

Weitere Informationen finden Sie unter Dokumente über Fehlermeldungen.

Beispiel für eine Richtlinie

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:region:account:topicfilter/$aws/things/thingName/shadow/update/rejected"] }, { "Effect": "Allow", "Action": ["iot:Receive"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/rejected"] } ] }

/update/delta

AWS IoT veröffentlicht ein Antwort-Statusdokument zu diesem Thema, wenn es eine Änderung für den Geräteschatten akzeptiert, und das Anfrage-Statusdokument enthält unterschiedliche Werte für den Status desired (Soll) und den Status reported (gemeldet):

$aws/things/thingName/shadow/update/delta

Weitere Informationen finden Sie unter Antwort-Statusdokumente.

Veröffentlichungsdetails

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

Beispiel für eine Richtlinie

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:region:account:topicfilter/$aws/things/thingName/shadow/update/delta"] }, { "Effect": "Allow", "Action": ["iot:Receive"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/delta"] } ] }

/get

Veröffentlichen Sie eine leere Nachricht in diesem Thema, um den Geräteschatten abzurufen:

$aws/things/thingName/shadow/get

AWS IoT antwortet mittels Veröffentlichung entweder in /get/accepted oder /update/rejected.

Beispiel für eine Richtlinie

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:region:account:topic/$aws/things/thingName/shadow/get"] } ] }

/get/accepted

AWS IoT veröffentlicht bei Rückgabe des Geräteschattens ein Antwort-Statusdokument in diesem Thema:

$aws/things/thingName/shadow/get/accepted

Weitere Informationen finden Sie unter Antwort-Statusdokumente.

Beispiel für eine Richtlinie

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:region:account:topicfilter/$aws/things/thingName/shadow/get/accepted"] }, { "Effect": "Allow", "Action": ["iot:Receive"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get/accepted"] } ] }

/update/rejected

AWS IoT veröffentlicht ein Dokument über Fehlermeldungen in diesem Thema, wenn es den Geräteschatten nicht zurückgeben kann:

$aws/things/thingName/shadow/get/rejected

Weitere Informationen finden Sie unter Dokumente über Fehlermeldungen.

Beispiel für eine Richtlinie

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:region:account:topicfilter/$aws/things/thingName/shadow/get/rejected"] }, { "Action": ["iot:Receive"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get/rejected"] } ] }

/delete

Um einen Geräteschatten zu löschen, veröffentlichen Sie im Löschthema eine leere Nachricht.

$aws/things/thingName/shadow/delete

Der Inhalt der Nachricht wird ignoriert.

AWS IoT antwortet mittels Veröffentlichung entweder in /delete/accepted oder /delete/rejected.

Beispiel für eine Richtlinie

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:region:account:topicfilter/$aws/things/thingName/shadow/delete"] }, { "Effect": "Allow", "Action": ["iot:Receive"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/delete"] } ] }

/delete/accepted

AWS IoT veröffentlicht eine Nachricht in diesem Thema, wenn ein Geräteschatten gelöscht wird:

$aws/things/thingName/shadow/delete/accepted

Beispiel für eine Richtlinie

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:region:account:topicfilter/$aws/things/thingName/shadow/delete/accepted"] }, { "Effect": "Allow", "Action": ["iot:Receive"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/delete/accepted"] } ] }

/delete/rejected

AWS IoT veröffentlicht ein Dokument über Fehlermeldungen in diesem Thema, wenn es den Geräteschatten nicht löschen kann:

$aws/things/thingName/shadow/delete/rejected

Weitere Informationen finden Sie unter Dokumente über Fehlermeldungen.

Beispiel für eine Richtlinie

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:region:account:topicfilter/$aws/things/thingName/shadow/delete/rejected"] }, { "Effect": "Allow", "Action": ["iot:Receive"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/delete/rejected"] } ] }