Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# API REST Device Shadow
Un shadow expose l'URI suivante pour mettre à jour les informations d'état :
```
https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow
```
Le point de terminaison est spécifique à votre Compte AWS. Pour trouver votre point de terminaison, vous pouvez :
+ Utilisez la commande [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) du AWS CLI.
+ Utilisez les paramètres AWS IoT de la console. Dans **Paramètres**, le point de terminaison est répertorié sous Point de **terminaison personnalisé**
+ Utilisez la page de détails des éléments de la AWS IoT console. Dans la console :
1. Ouvrez **Gérer** et sous **Gérer**, sélectionnez **Objets**.
1. Dans la liste des éléments, choisissez l'élément pour lequel vous souhaitez obtenir l'URI du point de terminaison.
1. Choisissez l'onglet **Device Shadows** et choisissez votre ombre. Vous pouvez consulter l'URI du point de terminaison dans la section ** Device Shadow URL** de la page de **détails du Device Shadow**.
Le format du point de terminaison est le suivant :
```
identifier.iot.region.amazonaws.com
```
L'API Shadow REST suit les mêmes protocols/port mappages HTTPS que ceux décrits dans[Protocoles de communication des appareils](protocols.md).
**Note**
Pour utiliser le APIs, vous devez l'utiliser `iotdevicegateway` comme nom de service pour l'authentification. Pour plus d'informations, consultez [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)
Vous pouvez également utiliser l'API pour créer une ombre nommée en la fournissant dans le `name=shadowName` cadre du paramètre de requête de l'API.
## GetThingShadow
Obtient le shadow de l'objet spécifié.
Le document d'état de réponse comprend le delta entre les états `desired` et `reported`.
**Demande**
La demande comprend les en-têtes HTTP standard, plus l'URI suivante :
```
HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
Le paramètre de requête `name` n'est pas requis pour les shadows non nommés (classiques).
**Réponse**
En cas de réussite, la réponse comprend les en-têtes HTTP standard, plus le code et le corps suivants :
```
HTTP 200
Response Body: response state document
```
Pour plus d'informations, consultez [Exemple de document d'état de réponse](device-shadow-document.md#device-shadow-example-response-json).
**Autorisation**
La récupération d'un shadow nécessite une stratégie qui permet au mandataire de réaliser l'action `iot:GetThingShadow`. Le service Device Shadow accepte deux formes d'authentification : Signature Version 4 avec des informations d'identification IAM ou authentification mutuelle TLS avec un certificat client.
Voici un exemple de stratégie qui permet à un mandataire de récupérer un shadow d'appareil :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:GetThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## UpdateThingShadow
Met à jour le shadow de l'objet spécifié.
Les mises à jour concernent uniquement les champs spécifiés dans le document d'état de la demande. Tout champ avec une valeur `null` est supprimé du shadow d'appareil.
**Demande**
La demande comprend les en-têtes HTTP standard, plus l'URI et le corps suivants :
```
HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document
```
Le paramètre de requête `name` n'est pas requis pour les shadows non nommés (classiques).
Pour plus d'informations, consultez [Exemple de document d'état de la demande](device-shadow-document.md#device-shadow-example-request-json).
**Réponse**
En cas de réussite, la réponse comprend les en-têtes HTTP standard, plus le code et le corps suivants :
```
HTTP 200
Response body: response state document
```
Pour plus d'informations, consultez [Exemple de document d'état de réponse](device-shadow-document.md#device-shadow-example-response-json).
**Autorisation**
La mise à jour d'un shadow nécessite une stratégie qui permet au mandataire de réaliser l'action `iot:UpdateThingShadow`. Le service Device Shadow accepte deux formes d'authentification : Signature Version 4 avec des informations d'identification IAM ou authentification mutuelle TLS avec un certificat client.
Voici un exemple de stratégie qui permet à un mandataire de mettre à jour un shadow d'appareil :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:UpdateThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## DeleteThingShadow
Supprime le shadow de l'objet spécifié.
**Demande**
La demande comprend les en-têtes HTTP standard, plus l'URI suivante :
```
HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
Le paramètre de requête `name` n'est pas requis pour les shadows non nommés (classiques).
**Réponse**
En cas de réussite, la réponse comprend les en-têtes HTTP standard, plus le code et le corps suivants :
```
HTTP 200
Response body: Empty response state document
```
Notez que la suppression d'une ombre ne rétablit pas son numéro de version à 0.
**Autorisation**
La suppression d'un shadow d'appareil nécessite une stratégie qui permet au mandataire de réaliser l'action `iot:DeleteThingShadow`. Le service Device Shadow accepte deux formes d'authentification : Signature Version 4 avec des informations d'identification IAM ou authentification mutuelle TLS avec un certificat client.
Voici un exemple de stratégie qui permet à un mandataire de supprimer un shadow d'appareil :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DeleteThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## ListNamedShadowsForThing
Répertorie les shadows de l'objet spécifié.
**Demande**
La demande comprend les en-têtes HTTP standard, plus l'URI suivante :
```
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
```
nextToken
Jeton permettant de récupérer l'ensemble suivant de résultats.
Cette valeur est renvoyée sur les résultats paginés et est utilisée dans l'appel qui renvoie la page suivante.
pageSize
Nombre de noms de shadows à renvoyer dans chaque appel. Consultez également `nextToken`.
thingName
Nom de l'objet pour lequel répertorier les shadows nommés.
**Réponse**
En cas de succès, la réponse comprend les en-têtes HTTP standard ainsi que le code de réponse suivant et un message de type [Document de réponse de liste de noms de shadows](device-shadow-document.md#device-shadow-list-json)
**Note**
Le shadow non nommé (classique) n'apparaît pas dans cette liste. La réponse est une liste vide si vous n'avez qu'une ombre classique ou si celle `thingName` que vous spécifiez n'existe pas.
```
HTTP 200
Response body: Shadow name list document
```
**Autorisation**
L'énumération de l'ombre d'un appareil nécessite une politique permettant à l'appelant d'effectuer l'action `iot:ListNamedShadowsForThing`. Le service Device Shadow accepte deux formes d'authentification : Signature Version 4 avec des informations d'identification IAM ou authentification mutuelle TLS avec un certificat client.
Voici un exemple de stratégie qui permet à un mandataire de répertorier les shadows nommés d'un objet :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:ListNamedShadowsForThing",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```