Geräteschatten-REST-API - AWS IoT Core
GetThingShadowUpdateThingShadowDeleteThingShadowListNamedShadowsForThing

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.

Geräteschatten-REST-API

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

https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow

Der Endpunkt ist spezifisch für Ihr AWS-Konto. Um Ihren Endpunkt zu finden, können Sie:

  • den Befehl describe-endpoint aus dem AWS CLI verwenden.

  • Verwenden Sie die AWS IoT Konsoleneinstellungen. In den Einstellungen ist der Endpunkt unter Benutzerdefinierter Endpunkt aufgeführt

  • Verwenden Sie die Detailseite des AWS IoT Konsolenobjekts. In der Konsole:

    1. Öffnen Sie Verwalten und wählen Sie unter Verwalten die Option Objekte aus.

    2. Wählen Sie in der Liste der Objekte das Objekt aus, für das Sie den Endpunkt-URI abrufen möchten.

    3. Wählen Sie die Registerkarte Geräteschatten und wählen Sie Ihren Schatten aus. Sie können den Endpunkt-URI im Abschnitt Geräteschatten-URL der Geräteschatten-Detailseite einsehen.

Der Endpunkt hat folgendes Format:

identifier.iot.region.amazonaws.com

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

Anmerkung

Um die APIs verwenden zu können, müssen Sie iotdevicegateway als Dienstnamen den Namen der Authentifizierung verwenden. Weitere Informationen finden Sie unter IoTDataPlane.

Sie können die API auch verwenden, um einen benannten Schatten zu erstellen, indem Sie name=shadowName als Teil des Abfrageparameters der API angeben.

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

Anforderung

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 Geräteschatten-Service akzeptiert zwei Arten der Authentifizierung: die Signatur-Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Client-Zertifikat.

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 Anfragestatusdokument angegebenen Felder. Ein Feld mit dem Wert null (Null) wird aus dem Geräteschatten entfernt.

Anforderung

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

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 Geräteschatten-Service akzeptiert zwei Arten der Authentifizierung: die Signatur-Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Client-Zertifikat.

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.

Anforderung

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

Beachten Sie, dass durch das Löschen eines Shadows seine Versionsnummer nicht auf 0 zurückgesetzt wird.

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 Geräteschatten-Service akzeptiert zwei Arten der Authentifizierung: die Signatur-Version 4 mit IAM-Anmeldeinformationen oder die gegenseitige TLS-Authentifizierung mit einem Client-Zertifikat.

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.

Anforderung

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. Siehe auch 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 eine Antwortdokument für die Schattennamenliste.

Anmerkung

Der unbenannte (klassische) Schatten wird in dieser Liste nicht angezeigt. Die Antwort ist eine leere Liste, wenn Sie nur einen klassischen Schatten haben oder wenn der von thingName Ihnen angegebene Schatten nicht existiert.

HTTP 200
Response body: Shadow name list document
Autorisierung

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

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"
      ]
    }
  ]
}