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.
# AWS IoT Service Device Shadow
Le service AWS IoT Device Shadow ajoute des ombres AWS IoT aux objets. Les ombres peuvent rendre l'état d'un appareil accessible aux applications et à d'autres services, que l'appareil soit connecté AWS IoT ou non. AWS IoT les objets objets peuvent avoir plusieurs ombres nommées, de sorte que votre solution IoT dispose de davantage d'options pour connecter vos appareils à d'autres applications et services.
AWS IoT les objets objets n'ont aucune ombre tant qu'ils ne sont pas créés explicitement. Les ombres peuvent être créées, mises à jour et supprimées à l'aide de la AWS IoT console. Les appareils, les autres clients Web et les services peuvent créer, mettre à jour et supprimer des ombres à l'aide de MQTT et des [rubriques MQTT réservées](reserved-topics.md#reserved-topics-shadow), de HTTP à l'aide de l'[API REST Device Shadow](device-shadow-rest-api.md) et le [AWS CLI pour AWS IoT](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html). Les ombres étant stockées AWS dans le cloud, elles peuvent collecter et rapporter des données sur l'état de l'appareil à partir d'applications et d'autres services cloud, que l'appareil soit connecté ou non.
## Utilisation des shadows
Les shadows fournissent un magasin de données fiable pour que les appareils, les applications et d'autres services cloud partagent des données. Ils permettent aux appareils, aux applications et aux autres services cloud de se connecter et déconnecter sans perdre l'état d'un appareil.
Lorsque les appareils, applications et autres services cloud sont connectés AWS IoT, ils peuvent accéder à l'état actuel d'un appareil et le contrôler à travers ses ombres. Par exemple, une application peut demander la modification de l'état d'un appareil en mettant à jour une ombre. AWS IoT publie un message indiquant la modification apportée à l'appareil. L'appareil reçoit ce message, met à jour son état pour qu'il corresponde et publie un message avec son état mis à jour. Le service Device Shadow reflète cet état mis à jour dans le shadow correspondant. L'application peut s'abonner à la mise à jour du shadow ou interroger le shadow pour obtenir son état actuel.
Lorsqu'un appareil se déconnecte, une application peut toujours communiquer avec AWS IoT les ombres de l'appareil. Lorsque l'appareil se reconnecte, il reçoit l'état actuel de ses shadows pour pouvoir mettre à jour son état afin que ce dernier corresponde à celui de ses shadows, et pour pouvoir publier un message avec son état mis à jour. De même, lorsqu'une application passe hors connexion et que l'état de l'appareil change alors qu'elle est hors connexion, l'appareil conserve le shadow mis à jour afin que l'application puisse interroger les shadows pour connaître son état actuel lorsqu'elle se reconnecte.
Si vos appareils sont fréquemment hors ligne et que vous souhaitez les configurer pour recevoir des messages delta après leur reconnexion, vous pouvez utiliser la fonctionnalité de session permanente. Pour plus d'informations sur la période d'expiration des sessions persistantes, consultez la section [Période d'expiration des sessions persistantes](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits).
### Choix d'utilisation de shadows nommés ou non nommés
Le service Device Shadow prend en charge les ombres nommées et non nommées, ou classiques. Un objet peut avoir plusieurs ombres nommées et pas plus d'une ombre non nommée. L'objet objet peut également avoir une ombre nommée réservée, qui fonctionne de la même manière qu'une ombre nommée, sauf que vous ne pouvez pas mettre à jour son nom. Pour plus d'informations, veuillez consulter [Gestion de la mémoire réservée](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow).
Un objet d'objet peut avoir des shadows nommés et non nommés en même temps. Toutefois, l'API utilisée pour accéder à chacun d'eux est légèrement différente. Il pourrait donc être plus efficace de décider quel type de shadow fonctionnerait le mieux pour votre solution et d'utiliser ce type uniquement. Pour de plus amples informations sur l'API permettant d'accéder aux shadows, veuillez consulter [Rubriques de shadow](reserved-topics.md#reserved-topics-shadow).
Avec les shadows nommés, vous pouvez créer différentes vues de l'état d'un objet d'objet. Par exemple, vous pouvez diviser un objet d'objet avec de nombreuses propriétés en shadows avec des groupes logiques de propriétés, chacun identifié par son nom de shadow. Vous pouvez également limiter l'accès aux propriétés en les regroupant dans différents shadows et en utilisant des stratégies pour contrôler l'accès. Pour plus d'informations sur les politiques à utiliser avec les ombres des appareils, consultez la section [Actions, ressources, clés de condition AWS IoT](https://docs.aws.amazon.com//service-authorization/latest/reference/list_awsiot.html) et [AWS IoT Core politiques](https://docs.aws.amazon.com//iot/latest/developerguide/iot-policies.html).
Les shadows classiques non nommés sont plus simples, mais un peu plus limités que les shadows nommés. Chaque AWS IoT objet ne peut avoir qu'une seule ombre sans nom. Si vous prévoyez que votre solution IoT aura un besoin limité de données de shadow, c'est peut-être ainsi que vous souhaitez commencer à utiliser les shadows. Toutefois, si vous pensez ajouter des shadows supplémentaires à l'avenir, envisagez d'utiliser des shadows nommés dès le début.
L'indexation des flottes prend en charge différemment les ombres anonymes et les ombres nommées. Pour de plus amples informations, veuillez consulter [Gérer l'indexation du parc](managing-fleet-index.md).
### Accès aux shadows
Chaque shadow a une [rubrique MQTT](reserved-topics.md#reserved-topics-shadow) réservée et une [URL HTTP](device-shadow-rest-api.md) qui prend en charge les actions `get`, `update` et `delete` sur le shadow.
Les shadows utilisent des [documents de shadow JSON](device-shadow-document.md) pour stocker et récupérer des données. Un document shadow contient une propriété d'état qui décrit les aspects suivants de l'état de l'appareil :
+ `desired`
Les applications spécifient les états souhaités des propriétés de l'appareil en mettant à jour l'objet `desired`.
+ `reported`
Les appareils rapportent leur état actuel dans l'objet `reported`.
+ `delta`
AWS IoT signale les différences entre l'état souhaité et l'état indiqué dans l'`delta`objet.
Les données stockées dans un shadow sont déterminées par la propriété d'état du corps du message de l'action de mise à jour. Les actions de mise à jour suivantes peuvent modifier les valeurs d'un objet de données existant, ainsi qu'ajouter et supprimer des clés et d'autres éléments dans l'objet d'état du shadow. Pour de plus amples informations sur l'accès aux shadows, veuillez consulter [Utilisation des shadows sur les appareils](device-shadow-comms-device.md) et [Utilisation des shadows dans les applications et les services](device-shadow-comms-app.md).
**Important**
L'autorisation d'effectuer des demandes de mise à jour doit être limitée aux applications et aux appareils approuvés. Cela empêche la propriété d'état du shadow d'être modifiée de manière inattendue. Sinon, les appareils et les applications qui utilisent le shadow doivent être conçus de manière à s'attendre à ce que les clés figurant dans la propriété d'état changent.
### Utilisation des shadows sur les appareils, dans les applications et dans d'autres services cloud
L'utilisation de shadows sur les appareils, dans les applications et dans d'autres services cloud nécessite une cohérence et une coordination entre tous ces éléments. Le service AWS IoT Device Shadow enregistre l'état d'ombre, envoie des messages lorsque l'état d'ombre change et répond aux messages qui modifient son état. Les appareils, applications et autres services cloud de votre solution IoT doivent gérer leur état et le maintenir cohérent avec l'état du shadow de l'appareil.
Les données d'état du shadow sont dynamiques et peuvent être modifiées par les appareils, les applications et les autres services cloud dotés de l'autorisation d'accéder au shadow. Pour cette raison, il est important de considérer comment chaque appareil, application et autre service cloud interagira avec le shadow. Par exemple :
+ Les*appareils* doivent écrire uniquement dans la propriété `reported` de l'état du shadow lors de la communication des données d'état au shadow.
+ Les *applications et autres services cloud* doivent écrire uniquement dans la propriété `desired` lors de la communication des demandes de changement d'état à l'appareil via le shadow.
**Important**
Les données contenues dans un objet de données de shadow sont indépendantes de celles des autres shadows et des autres propriétés de l'objet d'objet, telles que les attributs d'un objet et le contenu des messages MQTT que l'appareil d'un objet d'objet peut publier. Toutefois, un appareil peut rapporter les mêmes données dans différents shadows et différentes rubriques MQTT, si nécessaire.
Un appareil qui prend en charge plusieurs shadows doit maintenir la cohérence des données qu'il rapporte dans les différents shadows.
### Ordre des messages
Rien ne garantit que les messages du AWS IoT service arriveront à l'appareil dans un ordre spécifique. Le scénario suivant montre ce qui se passe dans ce cas.
Document d'état initial :
```
{
"state": {
"reported": {
"color": "blue"
}
},
"version": 9,
"timestamp": 123456776
}
```
Mise à jour 1 :
```
{
"state": {
"desired": {
"color": "RED"
}
},
"version": 10,
"timestamp": 123456777
}
```
Mise à jour 2 :
```
{
"state": {
"desired": {
"color": "GREEN"
}
},
"version": 11,
"timestamp": 123456778
}
```
Document d'état final :
```
{
"state": {
"reported": {
"color": "GREEN"
}
},
"version": 12,
"timestamp": 123456779
}
```
Il en résulte deux messages delta :
```
{
"state": {
"color": "RED"
},
"version": 11,
"timestamp": 123456778
}
```
```
{
"state": {
"color": "GREEN"
},
"version": 12,
"timestamp": 123456779
}
```
L'appareil peut recevoir ces messages dans le désordre. Etant donné que l'état de ces messages est cumulé, un dispositif peut ignorer en toute sécurité tous les messages qui contiennent un numéro de version plus ancien que celui qu'il suit. Si le dispositif reçoit le delta pour la version 12 avant la version 11, il peut en toute sécurité ignorer le message concernant la version 11.
### Suppression des messages de shadow
Pour réduire la taille des messages de shadow envoyés à votre appareil, définissez une règle qui sélectionne uniquement les champs dont votre appareil a besoin, puis republie le message dans une rubrique MQTT que votre appareil écoute.
La règle est spécifiée dans JSON et doit ressembler à ceci :
```
{
"sql": "SELECT state, version FROM '$aws/things/+/shadow/update/delta'",
"ruleDisabled": false,
"actions": [
{
"republish": {
"topic": "${topic(3)}/delta",
"roleArn": "arn:aws:iam:123456789012:role/my-iot-role"
}
}
]
}
```
L'instruction SELECT détermine quels champs du message seront republiés dans la rubrique spécifiée. Un caractère générique « \$1 » est utilisé pour apparier tous les noms de shadow. La règle spécifie que tous les messages correspondants doivent être republiés dans la rubrique spécifiée. Dans ce cas, la fonction `"topic()"` est utilisée pour indiquer la rubrique dans laquelle republier. `topic(3)` correspond à la valeur du nom de l'objet dans la rubrique d'origine. Pour plus d’informations sur la création de règles, consultez [Règles pour AWS IoT](iot-rules.md).
# Utilisation des shadows sur les appareils
Cette section décrit les communications entre les appareils et les ombres à l'aide de messages MQTT, la méthode préférée des appareils pour communiquer avec le service AWS IoT Device Shadow.
Les communications parallèles émulent un request/response modèle en utilisant le modèle de communication de publication/d'abonnement de MQTT. Chaque action de shadow se compose d'une rubrique de demande, d'une rubrique de réponse réussie (`accepted`) et d'une rubrique de réponse d'erreur (`rejected`).
Si vous souhaitez que les applications et les services soient en mesure de déterminer si un appareil est connecté, veuillez consulter [Détecter si un appareil est connecté](device-shadow-comms-app.md#thing-connection).
**Important**
Comme MQTT utilise un modèle publish/subscribe de communication, vous devez vous abonner aux sujets de réponse *avant* de publier un sujet de demande. Si vous ne le faites pas, vous risquez de ne pas recevoir la réponse à la demande que vous publiez.
Si vous utilisez un [Kit SDK des appareils AWS IoT](iot-sdks.md)pour appeler le service Device Shadow APIs, cela est géré pour vous.
Les exemples de cette section utilisent une forme abrégée de la rubrique dans laquelle ils *ShadowTopicPrefix* peuvent faire référence à une ombre nommée ou non, comme décrit dans ce tableau.
Les shadows peuvent être nommés ou non (classique). Les rubriques utilisées par chacun d'eux ne diffèrent que par le préfixe de rubrique. Ce tableau indique le préfixe de rubrique utilisé par chaque type de shadow.
| Valeur *ShadowTopicPrefix* | Type de shadow |
| --- | --- |
| \$1aws/things/thingName/shadow | Shadow non nommé (classique) |
| \$1aws/things/thingName/shadow/name/shadowName | Shadow nommé |
**Important**
Assurez-vous que l'utilisation des shadows par votre application ou service est cohérente et prise en charge par les implémentations correspondantes sur vos appareils. Par exemple, prenez en compte la façon dont les shadows sont créés, mis à jour et supprimés. Prenez également en compte la manière dont les mises à jour sont gérées sur l'appareil et dans les applications ou services qui accèdent à l'appareil via un shadow. Votre conception doit indiquer clairement comment l'état de l'appareil est mis à jour et rapporté, et comment vos applications et services interagissent avec l'appareil et ses shadows.
Pour créer une rubrique complète, sélectionnez `ShadowTopicPrefix` pour le type de shadow auquel vous souhaitez faire référence, remplacez `thingName`, et `shadowName` le cas échéant, par leurs valeurs correspondantes, puis ajoutez cela au stub de rubrique comme indiqué dans le tableau suivant. N'oubliez pas que les rubriques sont sensibles à la casse.
Veuillez consulter [Rubriques de shadow](reserved-topics.md#reserved-topics-shadow) pour de plus amples informations sur les rubriques réservées pour les shadows.
## Initialisation de l'appareil lors de la première connexion à AWS IoT
Une fois qu'un appareil s'est enregistré AWS IoT, il doit s'abonner à ces messages MQTT pour les ombres qu'il supporte.
| Rubrique | Signification | Action qu'un appareil doit effectuer lors de la réception de cette rubrique |
| --- | --- | --- |
| `ShadowTopicPrefix/delete/accepted` | La `delete` demande a été acceptée et l'ombre a été AWS IoT supprimée. | Actions nécessaires pour accompagner la suppression du shadow, telles que l'arrêt de la publication des mises à jour. |
| `ShadowTopicPrefix/delete/rejected` | La `delete` demande a été rejetée par AWS IoT et l'ombre n'a pas été supprimée. Le corps du message contient les informations d'erreur. | Répondre au message d'erreur dans le corps du message. |
| `ShadowTopicPrefix/get/accepted` | La `get` demande a été acceptée par AWS IoT, et le corps du message contient le document fantôme actuel. | Actions nécessaires pour traiter le document d'état dans le corps du message. |
| `ShadowTopicPrefix/get/rejected` | La `get` demande a été rejetée par AWS IoT, et le corps du message contient les informations d'erreur. | Répondre au message d'erreur dans le corps du message. |
| `ShadowTopicPrefix/update/accepted` | La `update` demande a été acceptée par AWS IoT, et le corps du message contient le document fantôme actuel. | Confirmer que les données mises à jour dans le corps du message correspondent à l'état de l'appareil. |
| `ShadowTopicPrefix/update/rejected` | La `update` demande a été rejetée par AWS IoT, et le corps du message contient les informations d'erreur. | Répondre au message d'erreur dans le corps du message. |
| `ShadowTopicPrefix/update/delta` | Le document fantôme a été mis à jour à la suite d'une demande adressée à AWS IoT, et le corps du message contient les modifications demandées. | Mettre à jour l'état de l'appareil pour qu'il corresponde à l'état souhaité dans le corps du message. |
| `ShadowTopicPrefix/update/documents` | Une mise à jour du shadow a été récemment réalisée et le corps du message contient le document shadow actuel. | Confirmer que l'état mis à jour dans le corps du message correspond à l'état de l'appareil. |
Après s'être abonné aux messages du tableau précédent pour chaque shadow, l'appareil doit tester si les shadows qu'il prend en charge ont déjà été créés en publiant une rubrique `/get` sur chaque shadow. Si un message `/get/accepted` est reçu, le corps du message contient le document shadow que l'appareil peut utiliser pour initialiser son état. Si un message `/get/rejected` est reçu, le shadow doit être créé en publiant un message `/update` avec l'état actuel de l'appareil.
Par exemple, supposons que vous ayez un objet `My_IoT_Thing` qui n'ait pas d'ombres classiques ou nommées. Si vous publiez maintenant une `/get` demande sur le sujet réservé`$aws/things/My_IoT_Thing/shadow/get`, elle renvoie une erreur sur le `$aws/things/My_IoT_Thing/shadow/get/rejected` sujet car le sujet ne comporte aucune ombre. Pour résoudre cette erreur, publiez d'abord un `/update` message en utilisant la `$aws/things/My_IoT_Thing/shadow/update` rubrique présentant l'état actuel de l'appareil, par exemple la charge utile suivante.
```
{
"state": {
"reported": {
"welcome": "aws-iot",
"color": "yellow"
}
}
}
```
Une ombre classique est désormais créée pour l'objet et le message est publié dans le `$aws/things/My_IoT_Thing/shadow/update/accepted` sujet. Si vous publiez dans le sujet`$aws/things/My_IoT_Thing/shadow/get`, il renvoie une réponse au `$aws/things/My_IoT_Thing/shadow/get/accepted` sujet avec l'état de l'appareil.
Pour les ombres nommées, vous devez d'abord créer l'ombre nommée ou publier une mise à jour avec le nom de l'ombre avant d'utiliser la requête get. Par exemple, pour créer une ombre nommée `namedShadow1`, publiez d'abord les informations sur l'état de l'appareil dans la rubrique `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/update`. Pour récupérer les informations d'état, utilisez la `/get` requête pour l'ombre nommée, `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/get`.
## Traitement des messages lorsque l'appareil est connecté à AWS IoT
Lorsqu'un appareil est connecté à AWS IoT, il peut recevoir des messages **/update/delta** et doit maintenir l'état de l'appareil adapté aux modifications survenues dans l'ombre en :
1. Lisant tous les messages **/update/delta** reçus et en synchronisant l'état de l'appareil pour qu'il y corresponde.
1. Publiant un message **/update** avec un corps de message `reported` doté de l'état actuel de l'appareil, chaque fois que l'état de l'appareil change.
Quand un appareil est connecté, il doit publier ces messages lorsque cela est indiqué.
| Indication | Rubrique | Charge utile |
| --- | --- | --- |
| L'état de l'appareil a changé. | `ShadowTopicPrefix/update` | Un document shadow avec la propriété `reported`. |
| L'appareil peut ne pas être synchronisé avec le shadow. | `ShadowTopicPrefix/get` | (empty) |
| Une action sur le dispositif indique qu'une ombre ne sera plus prise en charge par le dispositif, par exemple lorsque le dispositif est retiré ou remplacé. | `ShadowTopicPrefix/delete` | (empty) |
## Traitement des messages lorsque l'appareil se reconnecte à AWS IoT
Lorsqu'un appareil comportant une ou plusieurs ombres se connecte AWS IoT, il doit synchroniser son état avec celui de toutes les ombres qu'il supporte en :
1. Lisant tous les messages **/update/delta** reçus et en synchronisant l'état de l'appareil pour qu'il y corresponde.
1. Publiant un message **/update** avec un corps de message `reported` doté de l'état actuel de l'appareil.
# Utilisation des shadows dans les applications et les services
Cette section décrit comment une application ou un service interagit avec le service AWS IoT Device Shadow. Cet exemple suppose que l'application ou le service interagit uniquement avec le shadow et, via le shadow, avec l'appareil. Cet exemple n'inclut aucune action de gestion, telle que la création ou la suppression de shadows.
Cet exemple utilise l'API REST du service AWS IoT Device Shadow pour interagir avec les ombres. Contrairement à l'exemple utilisé dans[Utilisation des shadows sur les appareils](device-shadow-comms-device.md), qui utilise un modèle de publish/subscribe communications model, this example uses the request/response communication de l'API REST. Cela signifie que l'application ou le service doit faire une demande avant de pouvoir recevoir une réponse de AWS IoT. Un inconvénient de ce modèle, toutefois, est qu'il ne prend pas en charge les notifications. Si votre application ou service nécessite des notifications rapides en cas de modification de l'état de l'appareil, envisagez les protocoles MQTT ou MQTT over WSS, qui prennent en charge le modèle de publish/subscribe communication, comme décrit dans. [Utilisation des shadows sur les appareils](device-shadow-comms-device.md)
**Important**
Assurez-vous que l'utilisation des shadows par votre application ou service est cohérente et prise en charge par les implémentations correspondantes sur vos appareils. Prenez en compte, par exemple, la façon dont les shadows sont créés, mis à jour et supprimés, et la manière dont les mises à jour sont gérées sur l'appareil et dans les applications ou services qui accèdent au shadow. Votre conception doit indiquer clairement comment l'état de l'appareil est mis à jour et rapporté, et comment vos applications et services interagissent avec l'appareil et ses shadows.
L'URL de l'API REST pour un shadow nommé est :
```
https://endpoint/things/thingName/shadow?name=shadowName
```
et pour un shadow non nommé :
```
https://endpoint/things/thingName/shadow
```
où :
point de terminaison
Point de terminaison renvoyé par la commande CLI :
```
aws iot describe-endpoint --endpoint-type IOT:Data-ATS
```
thingName
Nom de l'objet d'objet auquel le shadow appartient
shadowName
Nom du shadow nommé. Ce paramètre n'est pas utilisé avec des shadows non nommés.
## Initialisation de l'application ou du service lors de la connexion à AWS IoT
Lorsque l'application se connecte pour la première fois à AWS IoT, elle doit envoyer une requête HTTP GET aux URLs ombres qu'elle utilise pour obtenir l'état actuel des ombres qu'elle utilise. Cela lui permet de synchroniser l'application ou le service avec le shadow.
## L'état de traitement change lorsque l'application ou le service est connecté à AWS IoT
Lorsque l'application ou le service est connecté AWS IoT, il peut demander périodiquement l'état actuel en envoyant une requête HTTP GET sur URLs les ombres qu'il utilise.
Lorsqu'un utilisateur final interagit avec l'application ou le service pour modifier l'état de l'appareil, l'application ou le service peut envoyer une requête HTTP POST aux URLs ombres qu'il utilise pour mettre à jour l'`desired`état de l'ombre. Cette demande renvoie la modification qui a été acceptée, mais vous devrez peut-être interroger le shadow en effectuant des demandes HTTP GET jusqu'à ce que l'appareil ait mis à jour le shadow avec son nouvel état.
## Détecter si un appareil est connecté
Pour déterminer si un appareil est actuellement connecté, incluez une propriété `connected` dans le document shadow et utilisez un message MQTT Last Will and Testament (LWT) pour définir la propriété `connected` sur `false` si un appareil est déconnecté en raison d'une erreur.
**Note**
Les messages MQTT LWT envoyés à des sujets AWS IoT réservés (sujets commençant par \$1) sont ignorés par le service AWS IoT Device Shadow. Cependant, ils sont traités par les clients abonnés et par le moteur de AWS IoT règles. Vous devrez donc créer un message LWT envoyé à un sujet non réservé et une règle qui republie le message MQTT LWT sous forme de message de mise à jour parallèle au sujet de mise à jour réservé du shadow,. `ShadowTopicPrefix/update`
**Pour envoyer un message LWT au service Device Shadow**
1. Créez une règle qui republie le message MQTT LWT sur la rubrique réservée. L'exemple suivant est une règle à l'écoute d'un message sur la `my/things/myLightBulb/update`rubrique et qui le republie dans `$aws/things/myLightBulb/shadow/update`.
```
{
"rule": {
"ruleDisabled": false,
"sql": "SELECT * FROM 'my/things/myLightBulb/update'",
"description": "Turn my/things/ into $aws/things/",
"actions": [
{
"republish": {
"topic": "$$aws/things/myLightBulb/shadow/update",
"roleArn": "arn:aws:iam:123456789012:role/aws_iot_republish"
}
}
]
}
}
```
1. Lorsque l'appareil se connecte à AWS IoT, il enregistre un message LWT dans un sujet non réservé afin que la règle de republication le reconnaisse. Dans cet exemple, cette rubrique est `my/things/myLightBulb/update` et elle définit la propriété connectée sur `false`.
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Après la connexion, l'appareil publie un message sur sa rubrique de mise à jour de shadow, `$aws/things/myLightBulb/shadow/update`, pour rapporter son état actuel, ce qui inclut la définition de sa propriété `connected` sur `true`.
```
{
"state": {
"reported": {
"connected":"true"
}
}
}
```
1. Avant que l'appareil ne se déconnecte gracieusement, il publie un message sur sa rubrique de mise à jour de shadow, `$aws/things/myLightBulb/shadow/update`, pour rapporter son état le plus récent, ce qui inclut la définition de sa propriété `connected` sur `false`.
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Si le périphérique se déconnecte en raison d'une erreur, le courtier de messages publie le AWS IoT message LWT de l'appareil au nom de celui-ci. La règle de republication détecte ce message et publie le message de mise à jour de shadow pour mettre à jour la propriété `connected` du shadow de l'appareil.
**Note**
En raison de la nature asynchrone du traitement des déconnexions, il n'est pas garanti que les messages LWT seront envoyés dans l'ordre lors de la reconnexion. Nous vous recommandons d'utiliser les [événements du cycle](life-cycle-events.md) de vie pour améliorer la précision de la détection de l'état de connectivité, car ces événements fournissent des attributs permettant de gérer les out-of-order événements.
# Simulation des communications du service Device Shadow
Cette rubrique indique comment le service Device Shadow agit en tant qu'intermédiaire et permet aux appareils et aux applications d'utiliser un shadow pour mettre à jour, stocker et récupérer l'état d'un appareil.
Pour démontrer l'interaction décrite dans cette rubrique et pour l'explorer plus en détail, vous aurez besoin d'un Compte AWS et d'un système sur lesquels vous pourrez exécuter le AWS CLI. Si vous ne les avez pas, vous pouvez toujours voir l'interaction dans les exemples de code.
Dans cet exemple, la AWS IoT console représente le périphérique. Le AWS CLI représente l'application ou le service qui accède à l'appareil par le biais de l'ombre. L' AWS CLI interface est très similaire à l'API avec laquelle une application peut communiquer AWS IoT. L'appareil dans cet exemple est une ampoule intelligente et l'application affiche l'état de cette ampoule et peut le modifier.
## Configuration de la simulation
Ces procédures initialisent la simulation en ouvrant la [console AWS IoT](https://console.aws.amazon.com/iot/home), qui simule votre appareil, et la fenêtre de ligne de commande qui simule votre application.
**Pour configurer votre environnement de simulation**
1. Vous aurez besoin d'un Compte AWS pour exécuter vous-même les exemples de cette rubrique. Si vous n'en avez pas Compte AWS, créez-en un, comme décrit dans[Configurez Compte AWS](setting-up.md).
1. Ouvrez la [console AWS IoT](https://console.aws.amazon.com/iot/home) et, dans le menu de gauche, choisissez **Test** pour ouvrir le **client MQTT**.
1. Dans une autre fenêtre, ouvrez une fenêtre de terminal sur un système où l'interface AWS CLI est installée.
Deux fenêtres doivent être ouvertes : l'une avec la AWS IoT console sur la page **Test** et l'autre avec une invite de ligne de commande.
## Initialisation de l'appareil
Dans cette simulation, nous allons travailler avec un objet nommé *mySimulatedThing*, et son ombre nommée *SimShadow1*.
**Create thing Object et sa politique en matière d'IoT**
Pour créer un objet, dans la **AWS IoT console** :
1. Sélectionnez **Gérer**, puis choisissez votre **objet **.
1. Cliquez sur le bouton **Créer** si des éléments sont répertoriés, sinon cliquez sur **Enregistrer un seul objet** pour créer un seul AWS IoT élément.
1. Entrez le nom`mySimulatedThing`, laissez les autres paramètres par défaut, puis cliquez sur **Suivant**.
1. Utilisez la création de certificats en un clic pour générer les certificats qui authentifieront la connexion de l'appareil à AWS IoT. Cliquez sur **Activer** pour activer le certificat.
1. Vous pouvez joindre la politique `My_IoT_Policy` qui autoriserait l'appareil à publier et à s'abonner aux sujets réservés au MQTT. Pour des étapes plus détaillées sur la création d'un AWS IoT objet et sur la création de cette politique, consultez[Créez un objet](create-iot-resources.md#create-aws-thing).
**Crée une ombre nommée pour l'objet**
Vous pouvez créer une ombre nommée pour un objet en publiant une demande de mise à jour dans la rubrique `$aws/things/mySimulatedThing/shadow/name/simShadow1/update`, comme décrit ci-dessous.
Ou, pour créer une ombre nommée :
1. Dans la **AWS IoT console**, choisissez votre objet dans la liste des objets affichés, puis choisissez **Shadows**.
1. Choisissez **Ajouter une ombre**, entrez le nom`simShadow1`, puis choisissez **Créer** pour ajouter l'ombre nommée.
**S'abonner et publier sur des sujets MQTT réservés**
Dans la console, souscrivez aux sujets MQTT réservés. Ces rubriques sont les réponses aux actions `get`, `update` et `delete`, afin que votre appareil soit prêt à recevoir les réponses après avoir publié une action.
**Pour vous abonner à une rubrique MQTT dans le **client MQTT****
1. Dans le **client MQTT**, choisissez **Publier dans une rubrique**.
1. Entrez le `get`, `update`, et les `delete` sujets auxquels vous souhaitez vous abonner. Copiez un sujet à la fois dans la liste suivante, collez-le dans le champ **Filtre de sujet**, puis cliquez sur **S'abonner**. Vous devriez voir les sujets apparaître sous **Abonnements**.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/documents`
À ce stade, votre appareil simulé est prêt à recevoir les rubriques telles qu'elles sont publiées par AWS IoT.
**Pour vous abonner à une rubrique MQTT dans le **client MQTT****
Une fois qu'un appareil s'est initialisé et s'est abonné aux rubriques de réponse, il doit exécuter une requête portant sur les shadows qu'il prend en charge. Cette simulation ne prend en charge qu'une seule ombre, l'ombre qui supporte un objet nommé *SimShadow1*. *mySimulatedThing*
**Pour obtenir l'état actuel du shadow à partir du **client MQTT****
1. Dans le **client MQTT**, choisissez **Publier dans une rubrique**.
1. Sous **Publish**, entrez l’objet suivant et supprimez tout contenu de la fenêtre de corps de message ci-dessous où vous avez entré la rubrique à obtenir. Vous pouvez ensuite choisir **Publier dans le sujet** pour publier la demande. `$aws/things/mySimulatedThing/shadow/name/simShadow1/get`.
Si vous n'avez pas créé l'ombre nommée, `simShadow1`, vous recevez un message dans `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected` l’objet et le `code` est `404`, comme dans cet exemple où l'ombre n'a pas été créée, nous allons donc la créer ensuite.
```
{
"code": 404,
"message": "No shadow exists with name: 'simShadow1'"
}
```
**Pour créer un shadow avec l'état actuel de l'appareil**
1. Dans le **client MQTT**, choisissez **Publier dans une rubrique** et entrez l’objet.
```
$aws/things/mySimulatedThing/shadow/name/simShadow1/update
```
1. Dans la fenêtre de corps de message ci-dessous où vous avez entré la rubrique, entrez ce document shadow pour montrer que l'appareil rapporte son ID et sa couleur actuelle en valeurs RVB. Choisissez **Publier** pour publier la demande.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
Si vous recevez un message dans le sujet :
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted` : Cela signifie que l'ombre a été créée et que le corps du message contient le document fantôme actuel.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected` : Vérifiez l'erreur dans le corps du message.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted` : L'ombre existe déjà et le corps du message contient l'état actuel de l'ombre, comme dans cet exemple. Avec cela, vous pouvez définir votre appareil ou confirmer qu'il correspond à l'état du shadow.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591140517,
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
## Envoi d'une mise à jour à partir de l'application
Cette section utilise le AWS CLI pour montrer comment une application peut interagir avec une ombre.
**Pour obtenir l'état actuel de l'ombre à l'aide du AWS CLI**
Sur la ligne de commande, entrez la commande ci-dessous.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Sur les plateformes Windows, vous pouvez utiliser `con` à la place de`/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
Comme le shadow existe et a été initialisé par l'appareil pour refléter son état actuel, il doit renvoyer le document shadow suivant.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591141111
}
```
L'application peut utiliser cette réponse pour initialiser sa représentation de l'état de l'appareil.
Si l'application met à jour l'état, par exemple lorsqu'un utilisateur final change la couleur de notre ampoule intelligente en jaune, l'application enverra une commande **update-thing-shadow**. Cette commande correspond à l'API REST `UpdateThingShadow`.
**Pour mettre à jour un shadow à partir d'une application**
Sur la ligne de commande, entrez la commande ci-dessous.
------
#### [ AWS CLI v2.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--cli-binary-format raw-in-base64-out \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
#### [ AWS CLI v1.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
Si elle réussit, cette commande doit renvoyer le document shadow suivant.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
}
},
"version": 4,
"timestamp": 1591141596,
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
## Réponse à une mise à jour sur l'appareil
Pour en revenir au **client MQTT** dans la AWS console, vous devriez voir les messages AWS IoT publiés pour refléter la commande de mise à jour émise dans la section précédente.
**Pour afficher les messages de mise à jour dans le **client MQTT****
Dans le **client MQTT**, choisissez **\$1 aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta** dans la colonne **Abonnements**. Si le nom de la rubrique est tronqué, vous pouvez faire une pause dessus pour voir le nom complet. Dans le journal des rubriques de cette rubrique, vous devriez voir un `/delta` message similaire à celui-ci.
```
{
"version": 4,
"timestamp": 1591141596,
"state": {
"ColorRGB": [
255,
255,
0
]
},
"metadata": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
Votre appareil traite le contenu de ce message pour définir l'état de l'appareil, afin qu'il corresponde à l'état `desired` dans le message.
Une fois que l'appareil a mis à jour l'état pour qu'il corresponde à l'`desired`état indiqué dans le message, il doit renvoyer le nouvel état signalé AWS IoT en publiant un message de mise à jour. Cette procédure simule cela dans le **client MQTT**.
**Pour mettre à jour le shadow à partir de l'appareil**
1. Dans le **client MQTT**, choisissez **Publier dans une rubrique**.
1. Dans la fenêtre du corps du message, dans le champ de sujet situé au-dessus de la fenêtre du corps du message, entrez le sujet de l'ombre suivi de l'`/update`action : `$aws/things/mySimulatedThing/shadow/name/simShadow1/update` et dans le corps du message, entrez ce document fantôme mis à jour, qui décrit l'état actuel de l'appareil. Choisissez **Publier** pour publier l'état de l'appareil mis à jour.
```
{
"state": {
"reported": {
"ColorRGB": [255,255,0]
}
},
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Si le message a bien été reçu par AWS IoT, vous devriez voir une nouvelle réponse dans le journal des aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted messages **\$1** du **client MQTT** avec l'état actuel de l'ombre, comme dans cet exemple.
```
{
"state": {
"reported": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"reported": {
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Une mise à jour réussie de l'état signalé du périphérique AWS IoT entraîne également l'envoi d'une description complète de l'état fantôme dans un message adressé au `update/documents` sujet, tel que le corps du message résultant de la mise à jour instantanée effectuée par le périphérique dans la procédure précédente.
```
{
"previous": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 4
},
"current": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5
},
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
## Observation de la mise à jour dans l'application
L'application peut désormais interroger le shadow pour obtenir l'état actuel, tel qu'il a été rapporté par l'appareil.
**Pour obtenir l'état actuel de l'ombre à l'aide du AWS CLI**
1. Sur la ligne de commande, entrez la commande ci-dessous.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Sur les plateformes Windows, vous pouvez utiliser à la `con` place de`/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
1. Comme le shadow vient d'être mis à jour par l'appareil pour refléter son état actuel, il doit renvoyer le document shadow suivant.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591143269
}
```
## Au-delà de la simulation
Expérimentez avec l'interaction entre l'interface AWS CLI (représentant l'application) et la console (représentant l'appareil) pour modéliser votre solution IoT.
# Interaction avec les shadows
Cette rubrique décrit les messages associés à chacune des trois méthodes fournies par AWS IoT qui permettent de travailler avec les shadows. Il s'agit notamment des méthodes suivantes :
`UPDATE`
Crée un shadow s'il n'existe pas ou met à jour le contenu d'un shadow existant avec les informations d'état fournies dans le corps de message. AWS IoT enregistre un horodatage avec chaque mise à jour pour indiquer quand l'état a été mis à jour pour la dernière fois. Lorsque l'état de l'ombre change, AWS IoT envoie `/delta` des messages à tous les abonnés MQTT avec la différence entre les `reported` états `desired` et. Les appareils ou les applications qui reçoivent un message `/delta` peuvent effectuer des actions en fonction de cette différence. Par exemple, un appareil peut mettre à jour son état à l'état souhaité, ou une application peut mettre à jour son interface utilisateur pour refléter le changement d'état de l'appareil.
`GET`
Récupère un document shadow actuel qui contient l'état complet du shadow, y compris les métadonnées.
`DELETE`
Supprime l'ombre de l'appareil et son contenu.
Vous ne pouvez pas restaurer un document fantôme supprimé sur un appareil, mais vous pouvez en créer un nouveau avec le nom d'un document fantôme supprimé sur un appareil. Si vous créez un document fantôme de terminal portant le même nom qu'un document supprimé au cours des dernières 48 heures, le numéro de version du nouveau document fantôme de terminal suivra celui du document supprimé. Si le document fantôme d'un appareil a été supprimé pendant plus de 48 heures, le numéro de version d'un nouveau document fantôme de l'appareil portant le même nom sera 0.
## Support du protocole
AWS IoT prend en charge le [MQTT](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) et une API REST via les protocoles HTTPS pour interagir avec les ombres. AWS IoT fournit un ensemble de sujets de demande et de réponse réservés pour les actions de publication et d'abonnement MQTT. Les appareils et les applications doivent s'abonner aux sujets de réponse avant de publier dans un sujet de demande afin d'obtenir des informations sur le AWS IoT traitement de la demande. Pour plus d’informations, consultez [Rubriques MQTT de Device Shadow](device-shadow-mqtt.md) et [API REST Device Shadow](device-shadow-rest-api.md).
## Demande d'état et génération de rapport d'état
Lorsque vous concevez votre solution IoT à l'aide de AWS IoT et d'ombres, vous devez déterminer les applications ou les appareils qui demanderont des modifications et ceux qui les mettront en œuvre. Généralement, un appareil implémente les modifications et les rapporte au shadow, et les applications et services y répondent et demandent les modifications dans le shadow. Votre solution peut être différente, mais les exemples de cette rubrique supposent que l'application ou le service client demande les modifications dans le shadow et que l'appareil effectue ces modifications et les rapporte en retour au shadow.
## Mise à jour d'un shadow
Votre application ou service peut mettre à jour l'état d'un shadow à l'aide de l'API [UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow) ou en publiant dans la rubrique [/update](device-shadow-mqtt.md#update-pub-sub-topic). Les mises à jour concernent uniquement les champs spécifiés dans la demande.
### Mise à jour d'un shadow lorsqu'un client demande un changement d'état
**Quand un client demande un changement d'état dans un shadow à l'aide du protocole MQTT**
1. Le client doit disposer d'un document shadow actuel pour pouvoir identifier les propriétés à modifier. Veuillez consulter l'action /get pour voir comment obtenir le document shadow actuel.
1. Le client s'abonne aux rubriques MQTT suivantes :
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/rejected`
+ `$aws/things/thingName/shadow/name/shadowName/update/delta`
+ `$aws/things/thingName/shadow/name/shadowName/update/documents`
1. Le client publie une rubrique de demande `$aws/things/thingName/shadow/name/shadowName/update` avec un document d'état qui contient l'état souhaité du shadow. Seules les propriétés à modifier doivent être incluses dans ce document. Ceci est un exemple de document avec l'état souhaité.
```
{
"state": {
"desired": {
"color": {
"r": 10
},
"engine": "ON"
}
}
}
```
1. Si la demande de mise à jour est valide, AWS IoT met à jour l'état souhaité dans l'ombre et publie des messages sur les sujets suivants :
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/delta`
Le message `/update/accepted` contient un document shadow [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) et le message `/update/delta` contient un document shadow [/documents d'état de la réponse delta](device-shadow-document.md#device-shadow-example-response-json-delta).
1. Si la demande de mise à jour n'est pas valide, AWS IoT publie un message avec le `$aws/things/thingName/shadow/name/shadowName/update/rejected` sujet avec un document [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) fantôme décrivant l'erreur.
**Quand un client demande un changement d'état dans un shadow à l'aide de l'API**
1. Le client appelle l'API `UpdateThingShadow` avec un document d'état [Document d'état de demande](device-shadow-document.md#device-shadow-example-request-json) comme corps de message.
1. Si la demande était valide, AWS IoT renvoie un code de réponse de réussite HTTP et un document [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) fantôme dans le corps du message de réponse.
AWS IoT publiera également un message MQTT sur le `$aws/things/thingName/shadow/name/shadowName/update/delta` sujet avec un document [/documents d'état de la réponse delta](device-shadow-document.md#device-shadow-example-response-json-delta) fantôme pour tous les appareils ou clients qui s'y abonnent.
1. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse d'erreur HTTP an [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) comme corps du message de réponse.
Lorsque l'appareil reçoit l'état `/desired` sur la rubrique `/update/delta`, il effectue les modifications souhaitées sur l'appareil. Il envoie ensuite un message à la rubrique `/update` pour rapporter son état actuel au shadow.
### Mise à jour d'un shadow lorsqu'un appareil rapporte son état actuel
**Quand un appareil rapporte son état actuel au shadow à l'aide du protocole MQTT**
1. L'appareil doit s'abonner aux rubriques MQTT suivantes avant de mettre à jour le shadow :
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/rejected`
+ `$aws/things/thingName/shadow/name/shadowName/update/delta`
+ `$aws/things/thingName/shadow/name/shadowName/update/documents`
1. L'appareil rapporte son état actuel en publiant un message dans la rubrique `$aws/things/thingName/shadow/name/shadowName/update` qui rapporte l'état actuel, comme dans cet exemple.
```
{
"state": {
"reported" : {
"color" : { "r" : 10 },
"engine" : "ON"
}
}
}
```
1. S'il AWS IoT accepte la mise à jour, il publie un message aux `$aws/things/thingName/shadow/name/shadowName/update/accepted` rubriques avec un document [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) fantôme.
1. Si la demande de mise à jour n'est pas valide, AWS IoT publie un message avec le `$aws/things/thingName/shadow/name/shadowName/update/rejected` sujet avec un document [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) fantôme décrivant l'erreur.
**Quand un appareil rapporte son état actuel au shadow à l'aide de l'API**
1. L'appareil appelle l'API `UpdateThingShadow` avec un document d'état [Document d'état de demande](device-shadow-document.md#device-shadow-example-request-json) comme corps de message.
1. Si la demande était valide, AWS IoT met à jour le fantôme et renvoie un code de réponse HTTP avec un document [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) fantôme comme corps de message de réponse.
AWS IoT publiera également un message MQTT sur le `$aws/things/thingName/shadow/name/shadowName/update/delta` sujet avec un document [/documents d'état de la réponse delta](device-shadow-document.md#device-shadow-example-response-json-delta) fantôme pour tous les appareils ou clients qui s'y abonnent.
1. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse d'erreur HTTP an [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) comme corps du message de réponse.
### Verrouillage optimiste
Vous pouvez utiliser la version du document d'état pour vous assurer que vous mettez à jour la version la plus récente d'un document shadow d'appareil. Lorsque vous fournissez une version dans une demande de mise à jour, le service rejette la demande avec un code de réponse de conflit HTTP 409 si la version actuelle du document d'état ne correspond pas à la version fournie. Le code de réponse au conflit peut également apparaître sur n'importe quelle API modifiée`ThingShadow`, notamment`DeleteThingShadow`.
Par exemple :
Document initial :
```
{
"state": {
"desired": {
"colors": [
"RED",
"GREEN",
"BLUE"
]
}
},
"version": 10
}
```
Mise à jour : (la version ne correspond pas ; cette demande est rejetée)
```
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 9
}
```
Résultat :
```
{
"code": 409,
"message": "Version conflict",
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
Mise à jour : (la version correspond ; cette demande est acceptée)
```
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 10
}
```
État final :
```
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 11
}
```
## Récupération d'un document Shadow
Vous pouvez récupérer un document shadow à l'aide de l'API [GetThingShadow](device-shadow-rest-api.md#API_GetThingShadow) ou en vous abonnant et en publiant dans la rubrique [/get](device-shadow-mqtt.md#get-pub-sub-topic). Ceci récupère un document shadow complet, y compris tout delta entre les états `desired` et `reported`. La procédure pour cette tâche est la même que l'appareil ou un client effectue la demande.
**Pour récupérer un document shadow à l'aide du protocole MQTT**
1. L'appareil ou le client doit s'abonner à ces rubriques MQTT avant de mettre à jour le shadow :
+ `$aws/things/thingName/shadow/name/shadowName/get/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/get/rejected`
1. L'appareil ou le client publie un message dans la rubrique `$aws/things/thingName/shadow/name/shadowName/get` avec un corps de message vide.
1. Si la demande aboutit, AWS IoT publie un message dans le `$aws/things/thingName/shadow/name/shadowName/get/accepted` sujet avec un [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) dans le corps du message.
1. Si la demande n'est pas valide, AWS IoT publie un message dans le `$aws/things/thingName/shadow/name/shadowName/get/rejected` sujet avec un [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) dans le corps du message.
**Pour récupérer un document shadow à l'aide d'une API REST**
1. L'appareil ou le client appelle l'API `GetThingShadow` avec un corps de message vide.
1. Si la demande est valide, AWS IoT renvoie un code de réponse HTTP avec un document [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) fantôme comme corps du message de réponse.
1. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse d'erreur HTTP an [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) comme corps du message de réponse.
## Suppression de données shadow
Il existe deux façons de supprimer des données shadow : vous pouvez supprimer les propriétés spécifiques dans le document shadow et vous pouvez supprimer complètement le shadow.
+ Pour supprimer des propriétés spécifiques d'un shadow, mettez à jour le shadow. Toutefois, définissez la valeur des propriétés à supprimer sur `null`. Les champs dotés d'une valeur `null` sont supprimés du document shadow.
+ Pour supprimer le shadow entier, utilisez l'API [DeleteThingShadow](device-shadow-rest-api.md#API_DeleteThingShadow) ou publiez dans la rubrique [/delete](device-shadow-mqtt.md#delete-pub-sub-topic).
**Note**
La suppression d'une ombre ne remet pas immédiatement son numéro de version à zéro. Il sera remis à zéro au bout de 48 heures.
### Suppression d'une propriété dans un document shadow
**Pour supprimer une propriété dans un shadow à l'aide du protocole MQTT**
1. L'appareil ou le client doit disposer d'un document shadow actuel pour pouvoir identifier les propriétés à modifier. Veuillez consulter [Récupération d'un document Shadow](#retrieving-device-shadow) pour obtenir des informations sur la façon d'obtenir le document shadow actuel.
1. L'appareil ou le client s'abonne aux rubriques MQTT suivantes :
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/rejected`
1. L'appareil ou le client publie une rubrique de demande `$aws/things/thingName/shadow/name/shadowName/update` avec un document d'état qui attribue des valeurs `null` aux propriétés du shadow à supprimer. Seules les propriétés à modifier doivent être incluses dans ce document. Voici un exemple de document qui supprime la propriété `engine`.
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. Si la demande de mise à jour est valide, AWS IoT supprime les propriétés spécifiées dans l'ombre et publie un message avec le `$aws/things/thingName/shadow/name/shadowName/update/accepted` sujet avec un document [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) fantôme dans le corps du message.
1. Si la demande de mise à jour n'est pas valide, AWS IoT publie un message avec le `$aws/things/thingName/shadow/name/shadowName/update/rejected` sujet avec un document [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) fantôme décrivant l'erreur.
**Pour supprimer une propriété d'un shadow à l'aide de l'API REST**
1. L'appareil ou le client appelle l'API `UpdateThingShadow` avec un [Document d'état de demande](device-shadow-document.md#device-shadow-example-request-json) qui attribue des valeurs `null` aux propriétés du shadow à supprimer. Incluez uniquement les propriétés que vous souhaitez supprimer dans le document. Voici un exemple de document qui supprime la propriété `engine`.
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. Si la demande était valide, AWS IoT renvoie un code de réponse de réussite HTTP et un document [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) fantôme dans le corps du message de réponse.
1. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse d'erreur HTTP an [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) comme corps du message de réponse.
### Suppression d'un shadow
Vous trouverez ci-après quelques considérations relatives à la suppression de l'ombre d'un appareil.
+ La définition de l'état de shadow de l'appareil sur `null` ne supprime pas le shadow. La version de shadow sera incrémentée lors de la prochaine mise à jour.
+ La suppression d'un shadow d'appareil ne supprime pas l'objet d'objet. La suppression d'un objet d'objet ne supprime pas le shadow d'appareil correspondant.
+ La suppression d'une ombre ne remet pas immédiatement son numéro de version à zéro. Il sera remis à zéro au bout de 48 heures.
**Pour supprimer un shadow à l'aide du protocole MQTT**
1. L'appareil ou le client s'abonne aux rubriques MQTT suivantes :
+ `$aws/things/thingName/shadow/name/shadowName/delete/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/delete/rejected`
1. L'appareil ou le client publie un `$aws/things/thingName/shadow/name/shadowName/delete` avec un tampon de messages vide.
1. Si la demande de suppression est valide, AWS IoT supprime l'ombre et publie un message avec le `$aws/things/thingName/shadow/name/shadowName/delete/accepted` sujet et un document [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) fantôme abrégé dans le corps du message. Voici un exemple du message de suppression accepté :
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Si la demande de mise à jour n'est pas valide, AWS IoT publie un message avec le `$aws/things/thingName/shadow/name/shadowName/delete/rejected` sujet avec un document [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) fantôme décrivant l'erreur.
**Pour supprimer un shadow à l'aide de l'API REST**
1. L'appareil ou le client appelle l'API `DeleteThingShadow` avec un tampon de messages vide.
1. Si la demande était valide, AWS IoT renvoie un code de réponse de réussite HTTP [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) et un document [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted) fantôme abrégé dans le corps du message. Voici un exemple du message de suppression accepté :
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse d'erreur HTTP an [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json) comme corps du message de réponse.
# 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"
]
}
]
}
```
# Rubriques MQTT de Device Shadow
Le service Device Shadow utilise des rubriques MQTT réservées pour permettre à des appareils et à des applications d'obtenir, de mettre à jour ou de supprimer les informations d'état d'un appareil (shadow).
La publication et l'abonnement à des rubriques shadow nécessite une autorisation basée sur les rubriques. AWS IoT se réserve le droit d'ajouter de nouvelles rubriques à la structure de rubriques existante. C'est pourquoi nous vous recommandons d'éviter les abonnements de caractère générique aux rubriques shadow. Par exemple, évitez de vous abonner à des filtres de sujets, `$aws/things/thingName/shadow/#` car le nombre de sujets correspondant à ce filtre de sujet peut augmenter à mesure que de nouveaux AWS IoT sujets secondaires seront introduits. Pour consulter des messages publiés dans ces rubriques, consultez [Interaction avec les shadows](device-shadow-data-flow.md).
Les shadows peuvent être nommés ou non (classique). Les rubriques utilisées par chacun d'eux ne diffèrent que par le préfixe de rubrique. Ce tableau indique le préfixe de rubrique utilisé par chaque type de shadow.
| Valeur *ShadowTopicPrefix* | Type de shadow |
| --- | --- |
| \$1aws/things/thingName/shadow | Shadow non nommé (classique) |
| \$1aws/things/thingName/shadow/name/shadowName | Shadow nommé |
Pour créer une rubrique complète, sélectionnez le `ShadowTopicPrefix` pour le type de shadow auquel vous souhaitez faire référence, remplacez `thingName`, et `shadowName` le cas échéant, par leurs valeurs correspondantes, puis ajoutez cela au stub de rubrique comme indiqué dans les sections suivantes.
Voici les rubriques MQTT utilisés pour interagir avec les shadows.
**Topics**
+ [/get](#get-pub-sub-topic)
+ [/get/accepted](#get-accepted-pub-sub-topic)
+ [/get/rejected](#get-rejected-pub-sub-topic)
+ [/update](#update-pub-sub-topic)
+ [/update/delta](#update-delta-pub-sub-topic)
+ [/update/accepted](#update-accepted-pub-sub-topic)
+ [/update/documents](#update-documents-pub-sub-topic)
+ [/update/rejected](#update-rejected-pub-sub-topic)
+ [/delete](#delete-pub-sub-topic)
+ [/delete/accepted](#delete-accepted-pub-sub-topic)
+ [/delete/rejected](#delete-rejected-pub-sub-topic)
## /get
Publier un message vide dans cette rubrique pour obtenir le shadow d'appareil :
```
ShadowTopicPrefix/get
```
AWS IoT répond en publiant à l'un [/get/accepted](#get-accepted-pub-sub-topic) ou à l'autre[/get/rejected](#get-rejected-pub-sub-topic).
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get"
]
}
]
}
```
## /get/accepted
AWS IoT publie un document d'ombre de réponse dans cette rubrique lors du renvoi de l'ombre de l'appareil :
```
ShadowTopicPrefix/get/accepted
```
Pour de plus amples informations, veuillez consulter [Documents d'état de la réponse](device-shadow-document.md#device-shadow-example-response-json).
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/accepted"
]
}
]
}
```
## /get/rejected
AWS IoT publie un document de réponse aux erreurs dans cette rubrique lorsqu'il ne parvient pas à renvoyer l'ombre de l'appareil :
```
ShadowTopicPrefix/get/rejected
```
Pour de plus amples informations, veuillez consulter [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json).
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/rejected"
]
}
]
}
```
## /update
Publier un document d'état de la demande dans cette rubrique pour mettre à jour l'objet d'appareil :
```
ShadowTopicPrefix/update
```
Le corps du message contient un [document d'état de demande partiel](device-shadow-document.md#device-shadow-example-request-json).
Un client tentant de mettre à jour l'état d'un appareil enverrait un document d'état de demande JSON avec la propriété `desired` comme la suivante :
```
{
"state": {
"desired": {
"color": "red",
"power": "on"
}
}
}
```
Un appareil mettant à jour son shadow enverrait un document d'état de demande JSON avec la propriété `reported`, comme ceci :
```
{
"state": {
"reported": {
"color": "red",
"power": "on"
}
}
}
```
AWS IoT répond en publiant à l'un [/update/accepted](#update-accepted-pub-sub-topic) ou à l'autre[/update/rejected](#update-rejected-pub-sub-topic).
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update"
]
}
]
}
```
## /update/delta
AWS IoT publie un document d'état de réponse dans cette rubrique lorsqu'il accepte une modification de l'ombre de l'appareil, et le document d'état de réponse contient des valeurs `desired` et des `reported` états différents :
```
ShadowTopicPrefix/update/delta
```
Le tampon de messages contient un [/documents d'état de la réponse delta](device-shadow-document.md#device-shadow-example-response-json-delta).
### Détails du corps de message
+ Un message publié dans `update/delta` comprend uniquement les attributs « souhaité » qui diffèrent entre les sections `desired` et `reported`. Il contient tous ces attributs, indépendamment qu'ils aient été contenus dans le message de mise à jour actuel ou qu'ils aient déjà été stockés dans AWS IoT. Les attributs qui ne diffèrent pas entre les sections `desired` et `reported` ne sont pas inclus.
+ Si un attribut figure dans la section `reported`, mais qu'il n'a aucun équivalent dans la section `desired`, il n'est pas inclus.
+ Si un attribut figure dans la section `desired`, mais qu'il n'a aucun équivalent dans la section `reported`, il n'est pas inclus.
+ Si un attribut est supprimé de la section `reported`, mais qu'il existe toujours dans la section `desired`, il est inclus.
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/delta"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/delta"
]
}
]
}
```
## /update/accepted
AWS IoT publie un document d'état de réponse dans cette rubrique lorsqu'il accepte une modification de l'ombre de l'appareil :
```
ShadowTopicPrefix/update/accepted
```
Le tampon de messages contient un [/document d'état de la réponse accepté](device-shadow-document.md#device-shadow-example-response-json-accepted).
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/accepted"
]
}
]
}
```
## /update/documents
AWS IoT publie un document d'état sur cette rubrique chaque fois qu'une mise à jour du shadow est effectuée avec succès :
```
ShadowTopicPrefix/update/documents
```
Le corps du message contient un [/documents d'état de la réponse documents](device-shadow-document.md#device-shadow-example-response-json-documents).
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/documents"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/documents"
]
}
]
}
```
## /update/rejected
AWS IoT publie un document de réponse aux erreurs dans cette rubrique lorsqu'il rejette une modification concernant l'ombre de l'appareil :
```
ShadowTopicPrefix/update/rejected
```
Le corps du message contient un [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json).
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/rejected"
]
}
]
}
```
## /delete
Pour supprimer un shadow d'appareil, publiez un message vide dans la rubrique delete :
```
ShadowTopicPrefix/delete
```
Le contenu du message est ignoré.
Notez que la suppression d'une ombre ne rétablit pas son numéro de version à 0.
AWS IoT répond en publiant à l'un [/delete/accepted](#delete-accepted-pub-sub-topic) ou à l'autre[/delete/rejected](#delete-rejected-pub-sub-topic).
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete"
]
}
]
}
```
## /delete/accepted
AWS IoT publie un message dans cette rubrique lorsque l'ombre d'un appareil est supprimée :
```
ShadowTopicPrefix/delete/accepted
```
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/accepted"
]
}
]
}
```
## /delete/rejected
AWS IoT publie un document de réponse aux erreurs dans cette rubrique lorsqu'il ne parvient pas à supprimer l'ombre de l'appareil :
```
ShadowTopicPrefix/delete/rejected
```
Le corps du message contient un [Document de réponse d'erreur](device-shadow-document.md#device-shadow-example-error-json).
### Exemple de stratégie
Voici un exemple de document de stratégie requise :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/rejected"
]
}
]
}
```
# Documents du service Device Shadow
Le service Device Shadow respecte toutes les règles de la spécification JSON. Valeurs, objets et tableaux sont stockés dans le document shadow de l'appareil.
**Topics**
+ [Exemples de documents shadow](#device-shadow-document-syntax)
+ [Propriétés du document](#document-structure)
+ [État Delta](#delta-state)
+ [Documents shadow de gestion des versions](#versioning)
+ [Jetons clients dans les documents shadow](#client-token)
+ [Propriétés de document shadow vides](#device-shadow-empty-fields)
+ [Valeurs de tableau dans les documents shadow](#device-shadow-arrays)
## Exemples de documents shadow
Le service Device Shadow utilise ces documents dans les opérations UPDATE, GET et DELETE à l'aide de l'[API REST](device-shadow-rest-api.md) ou [ Pub/Sub des messages MQTT](device-shadow-mqtt.md).
**Topics**
+ [Document d'état de demande](#device-shadow-example-request-json)
+ [Documents d'état de la réponse](#device-shadow-example-response-json)
+ [Document de réponse d'erreur](#device-shadow-example-error-json)
+ [Document de réponse de liste de noms de shadows](#device-shadow-list-json)
### Document d'état de demande
Un document d'état de demande a le format suivant :
```
{
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer1,
"attribute2": "string1",
...
"attributeN": boolean1
}
},
"clientToken": "token",
"version": version
}
```
+ `state` — Les mises à jour affectent uniquement les champs spécifiés. Généralement, vous utiliserez la propriété `reported` ou la propriété `desired`, mais pas les deux dans la même demande.
+ `desired` — Les propriétés d'état et les valeurs dont la mise à jour est demandé dans l’appareil.
+ `reported` — Les propriétés d'état et les valeurs signalées par l’appareil.
+ `clientToken` — Si utilisé, vous pouvez faire correspondre la requête et la réponse correspondante par le jeton client.
+ `version` — Le service Device Shadow traite la mise à jour uniquement si la version spécifiée correspond à la dernière version qu'il a.
### Documents d'état de la réponse
Les documents d'état de la réponse ont le format suivant, selon le type de réponse.
#### /document d'état de la réponse accepté
```
{
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"timestamp": timestamp,
"clientToken": "token",
"version": version
}
```
#### /documents d'état de la réponse delta
```
{
"state": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"metadata": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"timestamp": timestamp,
"clientToken": "token",
"version": version
}
```
#### /documents d'état de la réponse documents
```
{
"previous" : {
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer1,
"attribute2": "string1",
...
"attributeN": boolean1
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"reported": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"version": version-1
},
"current": {
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"reported": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"version": version
},
"timestamp": timestamp,
"clientToken": "token"
}
```
#### Propriétés du document d'état de réponse
+ `state` — Après une mise à jour réussie, il contient l’ de l'objet avant la mise à jour.
+ `state` — Après une mise à jour réussie, il contient l’ de l'objet après la mise à jour.
+ `state`
+ `reported` — Présent uniquement si un objet a déclaré des données dans la section et qu'il contient uniquement les champs qui se trouvaient dans le document d’état de la demande.
+ `desired` — Présente uniquement si un dispositif a communiqué des données dans la `desired` section et contient uniquement des champs qui figuraient dans le document d'état de la demande.
+ `metadata` — Contient les horodatages pour chaque attribut dans le `desired` et `reported` sections et afin que vous puissiez déterminer quand l'état a été mis à jour.
+ `timestamp`— La date et l'heure d'époque auxquelles la réponse a été générée AWS IoT.
+ `clientToken` — Présent uniquement si un jeton client a été utilisé lors de la publication d'un JSON valide dans la rubrique .
+ `version` — Version actuelle du document du shadow de l'appareil partagé dans AWS IoT. Elle est augmentée d'une unité par rapport à la version précédente du document.
### Document de réponse d'erreur
— Un document de réponse d'erreur a le format suivant :
```
{
"code": error-code,
"message": "error-message",
"timestamp": timestamp,
"clientToken": "token"
}
```
+ `code` — Code de réponse HTTP qui indique le type d'erreur.
+ `message` — Message texte qui fournit des informations supplémentaires.
+ `timestamp`— Date et heure auxquelles la réponse a été générée AWS IoT. Cette propriété n'est pas présente dans tous les documents de réponse d’erreur.
+ `clientToken`— Présent uniquement si un jeton client a été utilisé dans le message publié.
Pour de plus amples informations, veuillez consulter [Messages d'erreur de Device Shadow](device-shadow-error-messages.md).
### Document de réponse de liste de noms de shadows
Un document de réponse de liste de noms de shadows a le format suivant :
```
{
"results": [
"shadowName-1",
"shadowName-2",
"shadowName-3",
"shadowName-n"
],
"nextToken": "nextToken",
"timestamp": timestamp
}
```
+ `results`— Le tableau des noms des ombres.
+ `nextToken`— La valeur du jeton à utiliser dans les demandes paginées pour obtenir la page suivante de la séquence. Cette propriété n'est pas présente quand il ne reste plus de noms de shadows à renvoyer.
+ `timestamp`— Date et heure auxquelles la réponse a été générée AWS IoT.
## Propriétés du document
Un document de shadow d'appareil possède les propriétés suivantes :
`state`
`desired`
État souhaité de l'appareil. Les applications peuvent écrire dans cette partie du document pour mettre à jour l'état d'un appareil directement sans avoir à s'y connecter.
`reported`
État rapporté de l'appareil. Les appareils écrivent dans cette partie du document pour rapporter leur nouvel état. Les applications lisent cette partie du document pour déterminer le dernier état rapporté de l'appareil.
`metadata`
Informations sur les données stockées dans la section `state` du document. Il s'agit notamment des horodatages, en heure Unix, de chaque attribut de la section `state`, qui vous permet de déterminer quand ils ont été mis à jour.
Les métadonnées ne contribuent pas à la taille du document pour les limites de service ou la tarification. Pour plus d'informations, consultez [AWS IoT Limites de service ](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot).
`timestamp`
Indique quand le message a été envoyé par AWS IoT. En utilisant l'horodatage dans le message et les horodatages pour les attributs individuels dans la section `desired` ou `reported`, un appareil peut déterminer l'âge d'une propriété, même si l'appareil n'a pas d'horloge interne.
`clientToken`
Chaîne unique du dispositif qui permet d'associer les réponses à des demandes dans un environnement MQTT.
`version`
Version du document. Chaque fois que le document est mis à jour, ce numéro de version est incrémenté. Permet de s'assurer que la version du document en cours de mise à jour est la plus récente.
Pour de plus amples informations, veuillez consulter [Exemples de documents shadow](#device-shadow-document-syntax).
## État Delta
L'état Delta est un type virtuel d'état qui contient l'écart entre les états `desired` et `reported`. Les champs de la section `desired` qui ne figurent pas dans la section `reported` sont inclus dans le delta. Les champs qui figurent dans la section `reported` mais pas dans la section `desired` ne sont pas inclus dans le delta. Le delta contient des métadonnées et ses valeurs sont égales aux métadonnées contenues dans le champ `desired`. Par exemple :
```
{
"state": {
"desired": {
"color": "RED",
"state": "STOP"
},
"reported": {
"color": "GREEN",
"engine": "ON"
},
"delta": {
"color": "RED",
"state": "STOP"
}
},
"metadata": {
"desired": {
"color": {
"timestamp": 12345
},
"state": {
"timestamp": 12345
}
},
"reported": {
"color": {
"timestamp": 12345
},
"engine": {
"timestamp": 12345
}
},
"delta": {
"color": {
"timestamp": 12345
},
"state": {
"timestamp": 12345
}
}
},
"version": 17,
"timestamp": 123456789
}
}
```
Lorsque des objets imbriqués diffèrent, le delta contient le chemin d'accès à la racine.
```
{
"state": {
"desired": {
"lights": {
"color": {
"r": 255,
"g": 255,
"b": 255
}
}
},
"reported": {
"lights": {
"color": {
"r": 255,
"g": 0,
"b": 255
}
}
},
"delta": {
"lights": {
"color": {
"g": 255
}
}
}
},
"version": 18,
"timestamp": 123456789
}
```
Le service Device Shadow calcule le delta en itérant sur chaque champ de l'état `desired` et en le comparant à l'état `reported`.
Les tableaux sont traités comme des valeurs. Si un tableau de la section `desired` ne correspond pas au tableau de la section `reported`, l'intégralité du tableau souhaité est copiée dans le delta.
## Documents shadow de gestion des versions
Le service Device Shadow prend en charge la gestion des versions sur chaque message de mise à jour, qu'il s'agisse de la demande ou de la réponse. Cela signifie qu'à chaque mise à jour d'un shadow, la version du document JSON est incrémentée. Cela permet de garantir deux choses :
+ Un client peut recevoir une erreur s'il tente de remplacer un shadow par un numéro de version plus ancien. Le client est informé qu'il doit effectuer une resynchronisation avant de mettre à jour un shadow d'appareil.
+ Un client peut décider de ne pas agir sur un message reçu si le message est d'une version inférieure à la version stockée par le client.
Un client peut contourner la mise en correspondance des versions en n'incluant pas de version dans le document shadow.
## Jetons clients dans les documents shadow
Vous pouvez utiliser un jeton client avec la messagerie MQTT pour vérifier si une demande et une réponse contiennent le même jeton client. Cela garantit que la réponse et la demande sont associées.
**Note**
La longueur du jeton client ne peut pas dépasser 64 octets. Un jeton client d'une longueur supérieure à 64 octets génère une réponse 400 (Demande erronée) et un message d'erreur *ClientToken non valide*.
## Propriétés de document shadow vides
Les propriétés `reported` et `desired` d'un document shadow peuvent être vides ou omises lorsqu'elles ne s'appliquent pas à l'état actuel du shadow. Par exemple, un document shadow contient une propriété `desired` uniquement s'il a un état souhaité. Voici un exemple valide d'un document d'état sans propriété `desired` :
```
{
"reported" : { "temp": 55 }
}
```
La propriété `reported` peut également être vide, par exemple si le shadow n'a pas été mis à jour par l'appareil :
```
{
"desired" : { "color" : "RED" }
}
```
Si une mise à jour entraîne l'affectation de la valeur null aux propriétés `desired` ou `reported`, elle est supprimée du document. Voici comment supprimer la propriété `desired` en la définissant sur `null`. Vous pouvez le faire lorsqu'un appareil met à jour son état, par exemple.
```
{
"state": {
"reported": {
"color": "red"
},
"desired": null
}
}
```
Un document shadow peut également n'avoir aucune des propriétés `desired` et `reported`, auquel cas le document shadow est vide. Ceci est un exemple de document shadow vide, mais valide.
```
{
}
```
## Valeurs de tableau dans les documents shadow
Les shadows prennent en charge les tableaux, mais les traitent comme des valeurs normales, dans la mesure où une mise à jour d'un tableau remplace l'intégralité du tableau. Il n'est pas possible de mettre à jour une partie d'un tableau.
État initial :
```
{
"desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}
```
Mise à jour:
```
{
"desired" : { "colors" : ["RED"] }
}
```
État final :
```
{
"desired" : { "colors" : ["RED"] }
}
```
Les tableaux ne peuvent pas avoir de valeurs null. Par exemple, le tableau suivant n'est pas valide et sera rejeté.
```
{
"desired" : {
"colors" : [ null, "RED", "GREEN" ]
}
}
```
# Messages d'erreur de Device Shadow
Le service Device Shadow publie un message dans la rubrique d'erreur (via MQTT) en cas d'échec d'une tentative de modifier le document d'état. Ce message est émis uniquement en réponse à une demande de publication dans l'une des `$aws` rubriques réservées. Si le client met à jour le document à l'aide de l'API REST, il reçoit le code d'erreur HTTP dans le cadre de la réponse, et aucun message d'erreur MQTT n'est émis.
****
| Code d’erreur HTTP | Messages d’erreur |
| --- | --- |
| 400 (Requête erronée) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/device-shadow-error-messages.html) |
| 401 (Accès non autorisé) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/device-shadow-error-messages.html) |
| 403 (Accès interdit) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/device-shadow-error-messages.html) |
| 404 (Introuvable) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/device-shadow-error-messages.html) |
| 409 (Conflit) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/device-shadow-error-messages.html) |
| 413 (Charge utile trop importante) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/device-shadow-error-messages.html) |
| 415 (Type de support non pris en charge) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/device-shadow-error-messages.html) |
| 429 (Nombre de requêtes trop élevé) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/device-shadow-error-messages.html) |
| 500 (Erreur interne du serveur) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/device-shadow-error-messages.html) |