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 Ihren AWS-Konto. Um Ihren Endpunkt zu finden, können Sie:
+ den Befehl [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) 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 Seite mit den Details der AWS IoT Konsolenelemente. In der Konsole:
1. Öffnen Sie **Verwalten** und wählen Sie unter **Verwalten** die Option **Objekte** aus.
1. Wählen Sie in der Liste der Objekte das Objekt aus, für das Sie den Endpunkt-URI abrufen möchten.
1. 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 folgt denselben protocols/port HTTPS-Zuordnungen wie unter beschrieben. [Gerätekommunikationsprotokolle](protocols.md)
**Anmerkung**
Um den zu verwenden APIs, müssen Sie den Dienstnamen für die Authentifizierung verwenden`iotdevicegateway`. Weitere Informationen finden Sie unter [Io TData Plane](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html).
**Topics**
+ [GetThingShadow](#API_GetThingShadow)
+ [UpdateThingShadow](#API_UpdateThingShadow)
+ [DeleteThingShadow](#API_DeleteThingShadow)
+ [ListNamedShadowsForThing](#API_ListNamedShadowsForThing)
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](device-shadow-document.md#device-shadow-example-response-json).
**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:us-east-1:123456789012: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](device-shadow-document.md#device-shadow-example-request-json).
**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](device-shadow-document.md#device-shadow-example-response-json).
**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:us-east-1:123456789012: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:us-east-1:123456789012: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](device-shadow-document.md#device-shadow-list-json).
**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:us-east-1:123456789012:thing/thing"
]
}
]
}
```