Geräteschatten-REST-API - AWS IoT

Geräteschatten-REST-API

Ein Schatten stellt den folgenden URI für die Aktualisierung der Statusinformationen bereit:

https://endpoint/things/thingName/shadow

Der Endpunkt entspricht Ihrem AWS-Konto. Um den Endpunkt abzurufen, verwenden Sie den Befehl describe-endpoint. Der Endpunkt hat folgendes Format:

identifier.iot.region.amazonaws.com

Die Shadow-REST-API verwendet die unter Protokolle beschriebenen HTTPS-Protokolle/Portzuweisungen.

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

Anfrage

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.

Autorisierung

Für das Abrufen eine Schattens ist eine Richtlinie erforderlich, die es dem Aufrufer erlaubt, die Aktion iot:GetThingShadow durchzuführen. Der Device Shadow-Service akzeptiert zwei Arten der Authentifizierung: die Signatur Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Clientzertifikat.

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:region:account:thing/thing" ] } ] }

UpdateThingShadow

Aktualisiert das Schattengerät für das angegebene Objekt.

Aktualisierungen betreffen lediglich die im Anfrage-Statusdokument angegebenen Felder. Ein Feld mit dem Wert null (Null) wird aus dem Geräteschatten entfernt.

Anfrage

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 Anfrage-Statusdokumentenbeispiel.

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.

Autorisierung

Für das Aktualisieren eines Schattens ist eine Richtlinie erforderlich, die es dem Aufrufer erlaubt, die Aktion iot:UpdateThingShadow durchzuführen. Der Device Shadow-Service akzeptiert zwei Arten der Authentifizierung: die Signatur Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Clientzertifikat.

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:region:account:thing/thing" ] } ] }

DeleteThingShadow

Löscht das Schattengerät für das angegebene Objekt.

Anfrage

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

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 Device Shadow-Service akzeptiert zwei Arten der Authentifizierung: die Signatur Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Clientzertifikat.

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:region:account:thing/thing" ] } ] }

ListNamedShadowsForThing

Listet die Schatten für das angegebene Objekt auf.

Anfrage

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. Weitere Informationen finden Sie auch unter 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 ein .

Anmerkung

Der unbenannte (klassische) Schatten wird in dieser Liste nicht angezeigt.

HTTP 200 Response body: Shadow name list document

Autorisierung

Für das Löschen eine Geräteschattens ist eine Richtlinie erforderlich, die es dem Aufrufer erlaubt, die Aktion iot:ListNamedShadowsForThing durchzuführen. Der Device Shadow-Service akzeptiert zwei Arten der Authentifizierung: die Signatur Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Clientzertifikat.

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:region:account:thing/thing" ] } ] }