Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# AWS IoT Servicio Device Shadow
El servicio AWS IoT Device Shadow añade sombras a los objetos de las AWS IoT cosas. Las sombras pueden hacer que el estado de un dispositivo esté disponible para las aplicaciones y otros servicios, independientemente de que el dispositivo esté conectado AWS IoT o no. AWS IoT los objetos de las cosas pueden tener varias sombras con nombre para que su solución de IoT tenga más opciones para conectar sus dispositivos a otras aplicaciones y servicios.
AWS IoT los objetos tipo cosa no tienen sombras hasta que se crean de forma explícita. Las sombras se pueden crear, actualizar y eliminar mediante la AWS IoT consola. Los dispositivos, otros clientes web y los servicios pueden crear, actualizar y eliminar sombras mediante MQTT, y los [temas reservados de MQTT](reserved-topics.md#reserved-topics-shadow), HTTP, con la [API de REST de sombra de dispositivo](device-shadow-rest-api.md), y [AWS CLI para AWS IoT](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html). Como las sombras se almacenan AWS en la nube, pueden recopilar y generar informes sobre el estado del dispositivo desde aplicaciones y otros servicios en la nube, independientemente de que el dispositivo esté conectado o no.
## Uso de sombras
Las sombras proporcionan un almacén de datos de confianza para dispositivos, aplicaciones y otros servicios en la nube para compartir datos. Permiten que dispositivos, aplicaciones y otros servicios en la nube se conecten y desconecten sin perder el estado de un dispositivo.
Mientras los dispositivos, las aplicaciones y otros servicios en la nube estén conectados AWS IoT, estos pueden acceder al estado actual de un dispositivo y controlarlo a través de sus sombras. Por ejemplo, una aplicación puede solicitar un cambio en el estado de un dispositivo actualizando una sombra. AWS IoT publica un mensaje que indica el cambio en el dispositivo. El dispositivo recibe este mensaje, actualiza su estado para que coincida y publica un mensaje con su estado actualizado. El servicio Device Shadow refleja este estado actualizado en la sombra correspondiente. La aplicación puede suscribirse a la actualización de la sombra o puede consultar la sombra para conocer su estado actual.
Cuando un dispositivo se desconecta, la aplicación puede seguir comunicándose con el dispositivo AWS IoT y con las sombras de éste. Cuando el dispositivo se vuelve a conectar, recibe el estado actual de sus sombras para que pueda actualizar su estado para que coincida con el de sus sombras y, a continuación, publicar un mensaje con su estado actualizado. Del mismo modo, cuando una aplicación se desconecta y el estado del dispositivo cambia mientras está fuera de línea, el dispositivo mantiene la sombra actualizada para que la aplicación pueda consultar las sombras para conocer su estado actual cuando se vuelva a conectar.
Si sus dispositivos están desconectados con frecuencia y quiere configurarlos para que reciban mensajes delta después de que se vuelvan a conectar, puede usar la característica de sesión persistente. Para obtener más información sobre el periodo de caducidad de la sesión persistente, consulte el [Persistent session expiry period](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits).
### Elegir utilizar sombras con nombre o sin nombre
El servicio sombra de dispositivo admite sombras con nombre y sin nombre (o clásicas). Un objeto puede tener varias sombras con nombre, pero no más de una sombra sin nombre. El objeto también puede tener una sombra reservada con nombre, que funciona de forma similar a una sombra con nombre, con la diferencia de que no se puede actualizar el nombre. Para obtener más información, consulte [Sombra con nombre reservado](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow).
Un objeto puede tener sombras con nombre y sin nombre al mismo tiempo; sin embargo, la API utilizada para acceder a cada una es ligeramente diferente, por lo que podría ser más eficiente decidir qué tipo de sombra funcionaría mejor para su solución y usar solo dicho tipo. Para obtener más información acerca de la API para acceder a las sombras, consulte [Temas de sombra](reserved-topics.md#reserved-topics-shadow).
Mediante las sombras con nombre, puede crear distintas vistas del estado de un objeto. Por ejemplo, podría dividir un objeto con muchas propiedades en sombras con grupos lógicos de propiedades, cada una identificada por su nombre de sombra. También puede limitar el acceso a las propiedades agrupándolas en distintas sombras y utilizando políticas para controlar el acceso. Para obtener más información sobre las políticas que se pueden usar con las sombras de dispositivo, consulte [Acciones, recursos y claves de condición para AWS IoT](https://docs.aws.amazon.com//service-authorization/latest/reference/list_awsiot.html) y las [políticas de AWS IoT Core](https://docs.aws.amazon.com//iot/latest/developerguide/iot-policies.html).
Las sombras clásicas sin nombre son más sencillas, pero algo más limitadas que las sombras con nombre. Cada AWS IoT objeto puede tener solo una sombra sin nombre. Si espera que la solución de IoT tenga una necesidad limitada de datos de sombra, puede que así sea como desee comenzar a usar sombras. Sin embargo, si cree que es posible que desee agregar sombras adicionales en el futuro, plantéese la posibilidad de utilizar sombras con nombre desde el principio.
La indexación de flota admite de forma distinta las sombras sin nombre y con nombre. Para obtener más información, consulte [Manage fleet indexing](managing-fleet-index.md).
### Acceso a sombras
Cada sombra tiene un [tema de MQTT](reserved-topics.md#reserved-topics-shadow) reservado y una [URL HTTP](device-shadow-rest-api.md) que admite las acciones `get`, `update` y `delete` en la sombra.
Las sombras utilizan [documentos de sombra JSON](device-shadow-document.md) para almacenar y recuperar datos. Un documento de sombra contiene una propiedad de estado que describe estos aspectos del estado del dispositivo:
+ `desired`
Las aplicaciones especifican los estados deseados de las propiedades del dispositivo actualizando el objeto `desired`.
+ `reported`
Los dispositivos notifican su estado actual en el objeto `reported`.
+ `delta`
AWS IoT informa de las diferencias entre el estado deseado y el registrado en el `delta` objeto.
Los datos almacenados en una sombra están determinados por la propiedad de estado del cuerpo del mensaje de la acción de actualización. Las acciones de actualización posteriores pueden modificar los valores de un objeto de datos existente y también agregar y eliminar claves y otros elementos del objeto de estado de la sombra. Para obtener más información sobre cómo acceder a las sombras, consulte [Uso de sombras en dispositivos](device-shadow-comms-device.md) y [Uso de sombras en aplicaciones y servicios](device-shadow-comms-app.md).
**importante**
El permiso para realizar solicitudes de actualización debe limitarse a aplicaciones y dispositivos de confianza. Esto evita que la propiedad de estado de la sombra se cambie de forma inesperada; de lo contrario, los dispositivos y aplicaciones que usan la sombra deben diseñarse para esperar que cambien las claves de la propiedad de estado.
### Uso de sombras en dispositivos, aplicaciones y otros servicios en la nube
El uso de sombras en dispositivos, aplicaciones y otros servicios en la nube requiere coherencia y coordinación entre todos ellos. El servicio AWS IoT Device Shadow almacena el estado de sombra, envía mensajes cuando el estado de sombra cambia y responde a los mensajes que cambian de estado. Los dispositivos, las aplicaciones y otros servicios en la nube de la solución IoT deben administrar su estado y mantenerlo coherente con el estado de la sombra del dispositivo.
Los datos de estado de sombra son dinámicos y los pueden modificar los dispositivos, las aplicaciones y otros servicios en la nube con permiso para acceder a la sombra. Por esta razón, es importante considerar cómo interactuarán con la sombra cada dispositivo, aplicación y otro servicio en la nube. Por ejemplo:
+ Los *dispositivos* deben escribir solo en la propiedad `reported` del estado de la sombra al comunicar datos de estado a la sombra.
+ Las *aplicaciones y otros servicios en la nube* deben escribir solo en la propiedad `desired` al comunicar solicitudes de cambio de estado al dispositivo a través de la sombra.
**importante**
Los datos contenidos en un objeto de datos de sombra son independientes de los de otras sombras y otras propiedades de objetos, como los atributos de un objeto y el contenido de los mensajes MQTT que el dispositivo de un objeto podría publicar. Sin embargo, un dispositivo puede notificar los mismos datos en diferentes temas y sombras de MQTT si es necesario.
Un dispositivo que admita varias sombras debe mantener la coherencia de los datos que notifica en las distintas sombras.
### Orden de los mensajes
No se garantiza que los mensajes del AWS IoT servicio lleguen al dispositivo en un orden específico. La siguiente situación muestra lo que sucede en este caso.
Documento de estado inicial:
```
{
"state": {
"reported": {
"color": "blue"
}
},
"version": 9,
"timestamp": 123456776
}
```
Actualización 1:
```
{
"state": {
"desired": {
"color": "RED"
}
},
"version": 10,
"timestamp": 123456777
}
```
Actualización 2:
```
{
"state": {
"desired": {
"color": "GREEN"
}
},
"version": 11,
"timestamp": 123456778
}
```
Documento de estado final:
```
{
"state": {
"reported": {
"color": "GREEN"
}
},
"version": 12,
"timestamp": 123456779
}
```
Se obtienen dos mensajes delta:
```
{
"state": {
"color": "RED"
},
"version": 11,
"timestamp": 123456778
}
```
```
{
"state": {
"color": "GREEN"
},
"version": 12,
"timestamp": 123456779
}
```
El dispositivo puede recibir estos mensajes de forma desordenada. Dado que el estado de estos mensajes es acumulable, un dispositivo puede descartar con toda seguridad todos los mensajes cuyo número de versión sea anterior a la del mensaje del cual se hace un seguimiento. Si el dispositivo recibe el delta de la versión 12 antes que el de la versión 11, puede descartar sin problemas el mensaje de la versión 11.
### Recorte de mensajes de sombra
Para reducir el tamaño de los mensajes de sombra que se envían al dispositivo, defina una regla que seleccione solo los campos que necesita el dispositivo y que después vuelva a publicar el mensaje en un tema MQTT al que el dispositivo esté escuchando.
La regla se especifica en JSON y debe tener el aspecto siguiente:
```
{
"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"
}
}
]
}
```
La instrucción SELECT determina qué campos del mensaje se volverán a publicar en el tema especificado. Se usa el comodín "\$1" para seleccionar todos los nombres de sombra. La regla especifica que todos los mensajes coincidentes deben volver a publicarse en el tema especificado. En tal caso, la función `"topic()"` se utiliza para especificar el tema en el que se vuelve a publicar. `topic(3)` toma el valor del nombre de objeto del tema original. Para obtener más información sobre la creación de reglas, consulte [Reglas para AWS IoT](iot-rules.md).
# Uso de sombras en dispositivos
En esta sección se describen las comunicaciones de los dispositivos con las sombras mediante mensajes MQTT, el método preferido para que los dispositivos se comuniquen con el servicio AWS IoT Device Shadow.
Las comunicaciones en sombra emulan un request/response modelo utilizando el modelo de comunicación de publicación/suscripción de MQTT. Cada acción de sombra consta de un tema de solicitud, un tema de respuesta correcta (`accepted`) y un tema de respuesta de error (`rejected`).
Si desea que las aplicaciones y servicios puedan determinar si un dispositivo está conectado, consulte [Detección de un dispositivo conectado](device-shadow-comms-app.md#thing-connection).
**importante**
Como MQTT utiliza un modelo de publish/subscribe comunicación, debe suscribirse a los temas de respuesta *antes* de publicar un tema de solicitud. Si no lo hace, es posible que no reciba la respuesta a la solicitud que publique.
Si utiliza un servicio [SDK para dispositivos con AWS IoT](iot-sdks.md)para llamar al servicio Device Shadow APIs, se gestionará por usted.
Los ejemplos de esta sección utilizan una forma abreviada del tema, en la que *ShadowTopicPrefix* pueden hacer referencia a una sombra con nombre o sin nombre, tal y como se describe en esta tabla.
Las sombras pueden ser con nombre o sin nombre (clásico). Los temas utilizados por cada uno solo difieren en el prefijo del tema. Esta tabla muestra el prefijo de tema utilizado por cada tipo de sombra.
| Valor de *ShadowTopicPrefix* | Tipo de sombra |
| --- | --- |
| \$1aws/things/thingName/shadow | Sombra sin nombre (clásica) |
| \$1aws/things/thingName/shadow/name/shadowName | Sombra con nombre |
**importante**
Asegúrese de que el uso de las sombras por parte de la aplicación o servicio sea coherente y compatible con las implementaciones correspondientes en los dispositivos. Por ejemplo, tenga en cuenta cómo se crean, actualizan y eliminan las sombras. Tenga en cuenta también cómo se tratan las actualizaciones en el dispositivo y en las aplicaciones o servicios que acceden al dispositivo a través de una sombra. El diseño debe ser claro respecto a cómo se actualiza y notifica el estado del dispositivo y cómo interactúan las aplicaciones y los servicios con el dispositivo y sus sombras.
Para crear un tema completo, seleccione el `ShadowTopicPrefix` para el tipo de sombra al que desea hacer referencia, reemplace `thingName` y `shadowName` si procede, con sus valores correspondientes y, a continuación, anexe el código auxiliar del tema como se muestra en la tabla siguiente. Recuerde que los temas distinguen entre mayúsculas y minúsculas.
Consulte [Temas de sombra](reserved-topics.md#reserved-topics-shadow) para obtener más información acerca de los temas reservados para las sombras.
## Inicializar el dispositivo en la primera conexión a AWS IoT
Una vez que un dispositivo se registre en él AWS IoT, debería suscribirse a estos mensajes MQTT para las sombras que admite.
| Topic | Significado | Acción que debe realizar un dispositivo cuando se recibe este tema |
| --- | --- | --- |
| `ShadowTopicPrefix/delete/accepted` | Se aceptó la `delete` solicitud y AWS IoT se eliminó la sombra. | Las acciones necesarias para incorporar la sombra eliminada, como detener la publicación de actualizaciones. |
| `ShadowTopicPrefix/delete/rejected` | La `delete` solicitud fue rechazada por AWS IoT y la sombra no se eliminó. El cuerpo del mensaje contiene la información de error. | Responda al mensaje de error en el cuerpo del mensaje. |
| `ShadowTopicPrefix/get/accepted` | La `get` solicitud fue aceptada por AWS IoT y el cuerpo del mensaje contiene el documento alternativo actual. | Las acciones necesarias para procesar el documento de estado en el cuerpo del mensaje. |
| `ShadowTopicPrefix/get/rejected` | La `get` solicitud fue rechazada por AWS IoT y el cuerpo del mensaje contiene la información del error. | Responda al mensaje de error en el cuerpo del mensaje. |
| `ShadowTopicPrefix/update/accepted` | La `update` solicitud fue aceptada por AWS IoT y el cuerpo del mensaje contiene el documento alternativo actual. | Confirme que los datos actualizados en el cuerpo del mensaje coinciden con el estado del dispositivo. |
| `ShadowTopicPrefix/update/rejected` | La `update` solicitud fue rechazada por AWS IoT y el cuerpo del mensaje contiene la información del error. | Responda al mensaje de error en el cuerpo del mensaje. |
| `ShadowTopicPrefix/update/delta` | El documento alternativo se actualizó mediante una solicitud dirigida a AWS IoT, y el cuerpo del mensaje contiene los cambios solicitados. | Actualice el estado del dispositivo para que coincida con el estado deseado en el cuerpo del mensaje. |
| `ShadowTopicPrefix/update/documents` | Recientemente se completó una actualización de la sombra y el cuerpo del mensaje contiene el documento de sombra actual. | Confirme que el estado actualizado en el cuerpo del mensaje coincide con el estado del dispositivo. |
Después de suscribirse a los mensajes de la tabla anterior para cada sombra, el dispositivo debe probar si las sombras que admite ya se han creado publicando un tema `/get` en cada sombra. Si se recibe un mensaje `/get/accepted`, el cuerpo del mensaje contiene el documento de sombra, que el dispositivo puede utilizar para inicializar su estado. Si se recibe un mensaje `/get/rejected`, la sombra debe crearse publicando un mensaje `/update` con el estado actual del dispositivo.
Por ejemplo, supongamos que tiene un objeto `My_IoT_Thing` sin sombras, ni clásicas ni con nombre. Si ahora publica una solicitud `/get` en el tema reservado `$aws/things/My_IoT_Thing/shadow/get`, se devolverá un error sobre el tema `$aws/things/My_IoT_Thing/shadow/get/rejected`, ya que el objeto no tiene sombras. Para resolver este error, publique primero un mensaje `/update` utilizando el tema `$aws/things/My_IoT_Thing/shadow/update` con el estado actual del dispositivo, como la siguiente carga.
```
{
"state": {
"reported": {
"welcome": "aws-iot",
"color": "yellow"
}
}
}
```
Ahora se creará una sombra clásica para el objeto y el mensaje se publicará en el tema `$aws/things/My_IoT_Thing/shadow/update/accepted`. Si publica en el tema `$aws/things/My_IoT_Thing/shadow/get`, se devuelve una respuesta al tema `$aws/things/My_IoT_Thing/shadow/get/accepted` con el estado del dispositivo.
En el caso de las sombras con nombre, debe crear primero la sombra con nombre o publicar una actualización con el nombre de la sombra antes de utilizar la solicitud get. Por ejemplo, para crear una sombra con nombre `namedShadow1`, publique primero la información del estado del dispositivo en el tema `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/update`. Para recuperar la información de estado, use la solicitud `/get` para la sombra con nombre (`$aws/things/My_IoT_Thing/shadow/name/namedShadow1/get`).
## Procesar los mensajes mientras el dispositivo está conectado a AWS IoT
Mientras un dispositivo está conectado AWS IoT, puede recibir mensajes **/update/delta** y debe mantener el estado del dispositivo adaptado a los cambios que se producen en sus sombras de la siguiente manera:
1. Leer todos los mensajes **/update/delta** recibidos y sincronizar el estado del dispositivo para que coincida.
1. Publicando un mensaje **/update** con un cuerpo de mensaje `reported` que tenga el estado actual del dispositivo, siempre que cambie el estado del dispositivo.
Mientras un dispositivo está conectado, debe publicar estos mensajes cuando se indique.
| Indicación | Topic | Carga útil |
| --- | --- | --- |
| El estado del dispositivo ha cambiado. | `ShadowTopicPrefix/update` | Un documento de sombra con la propiedad `reported`. |
| Es posible que el dispositivo no esté sincronizado con la sombra. | `ShadowTopicPrefix/get` | (empty) |
| Una acción en el dispositivo indica que el dispositivo ya no admite una sombra; por ejemplo, cuando se quita o se reemplaza el dispositivo. | `ShadowTopicPrefix/delete` | (empty) |
## Procesar los mensajes cuando el dispositivo se vuelve a conectar a AWS IoT
Cuando se conecta un dispositivo con una o más sombras AWS IoT, debe sincronizar su estado con el de todas las sombras que admite de la siguiente manera:
1. Leer todos los mensajes **/update/delta** recibidos y sincronizar el estado del dispositivo para que coincida.
1. Publicando un mensaje **/update** con un cuerpo de mensaje `reported` que tenga el estado actual del dispositivo.
# Uso de sombras en aplicaciones y servicios
En esta sección se describe cómo interactúa una aplicación o un servicio con el servicio AWS IoT Device Shadow. En este ejemplo se supone que la aplicación o el servicio solo interactúan con la sombra y, a través de la sombra, con el dispositivo. Este ejemplo no incluye ninguna acción de administración, como la creación o eliminación de sombras.
En este ejemplo, se utiliza la API REST del servicio AWS IoT Device Shadow para interactuar con las sombras. A diferencia del ejemplo utilizado en[Uso de sombras en dispositivos](device-shadow-comms-device.md), que utiliza un modelo de publish/subscribe communications model, this example uses the request/response comunicaciones de la API REST. Esto significa que la aplicación o el servicio deben realizar una solicitud antes de poder recibir una respuesta AWS IoT. Una desventaja de este modelo, sin embargo, es que no admite notificaciones. Si tu aplicación o servicio requieren notificaciones puntuales de los cambios de estado del dispositivo, considera usar los protocolos MQTT o MQTT sobre WSS, que admiten el modelo de publish/subscribe comunicación, tal y como se describe en. [Uso de sombras en dispositivos](device-shadow-comms-device.md)
**importante**
Asegúrese de que el uso de las sombras por parte de la aplicación o servicio sea coherente y compatible con las implementaciones correspondientes en los dispositivos. Tenga en cuenta, por ejemplo, cómo se crean, actualizan y eliminan las sombras, y cómo se tratan las actualizaciones en el dispositivo y en las aplicaciones o servicios que acceden a la sombra. El diseño debe especificar claramente cómo se actualiza y notifica el estado del dispositivo, y cómo interactúan las aplicaciones y los servicios con el dispositivo y sus sombras.
La URL de la API REST para sombras con nombre es:
```
https://endpoint/things/thingName/shadow?name=shadowName
```
y para una sombra sin nombre:
```
https://endpoint/things/thingName/shadow
```
donde:
punto de conexión
El punto de enlace que devuelve el comando de la CLI:
```
aws iot describe-endpoint --endpoint-type IOT:Data-ATS
```
thingName
El nombre del objeto al que pertenece la sombra
shadowName
El nombre de la sombra con nombre. Este parámetro no se utiliza con sombras sin nombre.
## Inicializar la aplicación o el servicio al conectarse a AWS IoT
Cuando la aplicación se conecte por primera vez AWS IoT, debería enviar una solicitud HTTP GET a URLs las sombras que utiliza para obtener el estado actual de las sombras que utiliza. Esto le permite sincronizar la aplicación o el servicio con la sombra.
## El estado del procesamiento cambia mientras la aplicación o el servicio están conectados a AWS IoT
Mientras la aplicación o el servicio están conectados AWS IoT, pueden consultar el estado actual de forma periódica enviando una solicitud HTTP GET URLs desde las sombras que utiliza.
Cuando un usuario final interactúa con la aplicación o el servicio para cambiar el estado del dispositivo, la aplicación o el servicio puede enviar una solicitud HTTP POST a una URLs de las sombras que utiliza para actualizar el `desired` estado de la sombra. Esta solicitud devuelve el cambio que se aceptó, pero es posible que tenga que sondear la sombra realizando solicitudes HTTP GET hasta que el dispositivo haya actualizado la sombra con su nuevo estado.
## Detección de un dispositivo conectado
Para determinar si un dispositivo está conectado actualmente, incluya una propiedad `connected` en el documento de sombra y use un mensaje MQTT Last Will and Testament (LWT) para establecer la propiedad `connected` en `false` si un dispositivo está desconectado debido a un error.
**nota**
El servicio AWS IoT Device Shadow ignora los mensajes LWT de MQTT enviados a temas AWS IoT reservados (temas que comienzan por \$1). Sin embargo, los procesan los clientes suscritos y el motor de AWS IoT reglas, por lo que tendrá que crear un mensaje LWT que se envíe a un tema no reservado y una regla que vuelva a publicar el mensaje LWT de MQTT como un mensaje de actualización paralelo para el tema de actualización reservado de la sombra. `ShadowTopicPrefix/update`
**Para enviar al servicio Device Shadow un mensaje LWT**
1. Cree una regla que vuelva a publicar el mensaje MQTT LWT en el tema reservado. El siguiente ejemplo es una regla que escucha mensajes sobre el tema `my/things/myLightBulb/update` y lo vuelve a publicar en `$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. Cuando el dispositivo se conecta a AWS IoT, registra un mensaje de LWT en un tema no reservado para que lo reconozca la regla de republicación. En este ejemplo, ese tema es `my/things/myLightBulb/update` y establece la propiedad conectada en `false`.
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Después de conectarse, el dispositivo publica un mensaje en su tema de actualización de sombra `$aws/things/myLightBulb/shadow/update`, para notificar su estado actual, que incluye establecer su propiedad `connected` en `true`.
```
{
"state": {
"reported": {
"connected":"true"
}
}
}
```
1. Antes de que el dispositivo se desconecte correctamente, publica un mensaje en su tema de actualización de sombras `$aws/things/myLightBulb/shadow/update`, para notificar su estado más reciente, que incluye establecer su propiedad `connected` en `false`.
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Si el dispositivo se desconecta debido a un error, el agente de mensajes publica el AWS IoT mensaje LWT del dispositivo en nombre del dispositivo. La regla de republicación detecta este mensaje y publica el mensaje de actualización de sombra para actualizar la propiedad `connected` de la sombra del dispositivo.
**nota**
Dada la naturaleza asíncrona del procesamiento de desconexiones, no se garantiza que los mensajes de LWT se envíen en orden durante la reconexión. Le recomendamos que utilice [los eventos del ciclo](life-cycle-events.md) de vida para mejorar la precisión de la detección del estado de la conectividad, ya que estos eventos proporcionan atributos para out-of-order gestionarlos.
# Simulación de comunicaciones del servicio Device Shadow
En este tema se muestra cómo el servicio Device Shadow actúa como intermediario y permite que los dispositivos y aplicaciones utilicen una sombra para actualizar, almacenar y recuperar el estado de un dispositivo.
Para demostrar la interacción descrita en este tema y explorarla más a fondo, necesitará un Cuenta de AWS sistema en el que pueda ejecutarla AWS CLI. Si no dispone de ello, aún puede ver la interacción en los ejemplos de código.
En este ejemplo, la AWS IoT consola representa el dispositivo. AWS CLI Representa la aplicación o el servicio que accede al dispositivo a través de la sombra. La AWS CLI interfaz es muy similar a la API con la que una aplicación puede comunicarse AWS IoT. El dispositivo de este ejemplo es una bombilla inteligente y la aplicación muestra el estado de la bombilla y puede cambiar el estado de la bombilla.
## Configuración de la simulación
Estos procedimientos inicializan la simulación abriendo la [consola de AWS IoT](https://console.aws.amazon.com/iot/home), que simula su dispositivo, y la ventana de línea de comandos que simula su aplicación.
**Para configurar el entorno de simulación**
1. Necesitarás ejecutar Cuenta de AWS los ejemplos de este tema por tu cuenta. Si no tiene uno Cuenta de AWS, cree uno, tal y como se describe en[Configurar Cuenta de AWS](setting-up.md).
1. Abra la [consola de AWS IoT](https://console.aws.amazon.com/iot/home) y, en el menú de la izquierda, elija **Probar** para abrir el **cliente MQTT**.
1. En otra ventana, abra una ventana de terminal en un sistema que tenga instalada la AWS CLI .
Debería tener dos ventanas abiertas: una con la AWS IoT consola en la página de **pruebas** y otra con una línea de comandos.
## Inicializar el dispositivo
En esta simulación, trabajaremos con un objeto llamado *mySimulatedThing*, y su sombra llamada *SimShadow1*.
**Creación de un objeto y de su política de IoT**
Para crear un objeto, haga lo siguiente en la **consola AWS IoT **:
1. Seleccione **Administrar** y **Objetos**.
1. Haga clic en el botón **Crear** si hay cosas en la lista; de lo contrario, haga clic en **Registrar una sola cosa** para crear una sola AWS IoT cosa.
1. Introduzca el nombre `mySimulatedThing`, deje los demás ajustes con los valores predeterminados y haga clic en **Siguiente**.
1. Utilice la creación de certificados en un clic para generar los certificados que autenticarán la conexión del dispositivo a AWS IoT. Haga clic en **Activar** para activar el certificado.
1. Puede asociar la política `My_IoT_Policy` que le daría permiso al dispositivo para publicar en los temas reservados de MQTT y suscribirse a estos. Para obtener pasos más detallados sobre cómo crear una AWS IoT cosa y cómo crear esta política, consulte[Crear un objeto](create-iot-resources.md#create-aws-thing).
**Creación de una sombra con nombre para el objeto**
Puede crear una sombra con nombre para un objeto publicando una solicitud de actualización en el tema `$aws/things/mySimulatedThing/shadow/name/simShadow1/update`, tal y como se describe a continuación.
O para crear una sombra con nombre:
1. En la **consola AWS IoT **, seleccione el objeto que desee de la lista de objetos y seleccione **Sombras**.
1. Seleccione **Agregar una sombra**, introduzca el nombre `simShadow1` y seleccione **Crear** para agregar la sombra con nombre.
**Suscripción a temas reservados de MQTT y publicación en estos**
En la consola, suscríbase a los temas de sombras MQTT reservados. Estos temas son las respuestas a las acciones `get`, `update` y `delete` para que el dispositivo esté listo para recibir las respuestas después de publicar una acción.
**Para suscribirse a un tema MQTT en el **cliente MQTT****
1. En el **Cliente de MQTT**, elija **Suscribirse a un tema**.
1. Introduzca los temas `get`, `update` y `delete` a los que desea suscribirse. Copie un tema a la vez de la siguiente lista, péguelo en el campo **Filtro de temas** y haga clic en **Suscribirse**. Los temas deberían aparecer en **Suscripciones**.
+ `$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`
En este punto, el dispositivo simulado está listo para recibir los temas a medida que los publica AWS IoT.
**Para publicar en un tema MQTT, en el **Cliente de MQTT****
Después de que un dispositivo se haya inicializado y suscrito a los temas de respuesta, debe consultar las sombras que admite. Esta simulación solo admite una sombra, la sombra que soporta un objeto llamado *SimShadow1*. *mySimulatedThing*
**Para obtener el estado actual de la sombra desde el **Cliente MQTT****
1. En el **cliente MQTT**, elija **Publicar en un tema**.
1. En **Publicar**, introduzca el siguiente tema y elimine cualquier contenido de la ventana del cuerpo del mensaje, debajo del lugar en el que ha introducido el tema que desea obtener. A continuación, seleccione **Publicar en tema** para publicar la solicitud `$aws/things/mySimulatedThing/shadow/name/simShadow1/get`.
Si no ha creado la sombra con nombre `simShadow1`, recibirá un mensaje en el tema `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected` y el `code` será `404`, como se ve en este ejemplo en el que no se ha creado una sombra; a continuación, vamos a crearla.
```
{
"code": 404,
"message": "No shadow exists with name: 'simShadow1'"
}
```
**Para crear una sombra con el estado actual del dispositivo**
1. En **Cliente de MQTT**, elija **Publicar en tema** e introduzca este tema:
```
$aws/things/mySimulatedThing/shadow/name/simShadow1/update
```
1. En la ventana del cuerpo del mensaje debajo donde introdujo el tema, escriba este documento de sombra para mostrar que el dispositivo está notificando su ID y su color actual en valores RGB. Seleccione **Publicar** para publicar la solicitud.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
A continuación, se describe el significado de los mensajes recibidos en el tema.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`: significa que la sombra se ha creado y que el cuerpo del mensaje contiene el documento de sombra actual.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`: revise el error en el cuerpo del mensaje.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`: la sombra ya existe y el cuerpo del mensaje tiene el estado de sombra actual, como en este ejemplo. Con esto, puedes configurar su dispositivo o confirmar que coincide con el estado de sombra.
```
{
"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"
}
```
## Enviar una actualización desde la aplicación
En esta sección se utiliza AWS CLI para demostrar cómo una aplicación puede interactuar con una sombra.
**Para obtener el estado actual de la sombra, utilice el AWS CLI**
Desde la línea de comandos, escriba este comando:
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
En las plataformas Windows, puede utilizar `con` en lugar de `/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
Dado que la sombra existe y la ha inicializado el dispositivo para reflejar su estado actual, debe devolver el siguiente documento de sombra.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591141111
}
```
La aplicación puede usar esta respuesta para inicializar su representación del estado del dispositivo.
Si la aplicación actualiza el estado, como cuando un usuario final cambia el color de nuestra bombilla inteligente a amarillo, la aplicación enviará un comando **update-thing-shadow**. Este comando corresponde a la API REST `UpdateThingShadow`.
**Para actualizar una sombra desde una aplicación**
Desde la línea de comandos, escriba este comando:
------
#### [ 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 tiene éxito, este comando debe devolver el siguiente documento de sombra.
```
{
"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"
}
```
## Responder a la actualización en el dispositivo
Volviendo al **cliente MQTT** de la AWS consola, debería ver los mensajes AWS IoT publicados que reflejan el comando de actualización emitido en la sección anterior.
**Para ver los mensajes de actualización en el **Cliente MQTT****
En el **cliente MQTT**, elija **\$1 aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta** en la columna **Suscripciones**. Si el nombre del tema está truncado, puede ponerlo en pausa para ver el tema completo. En el registro de temas para este tema, debería ver un mensaje `/delta` similar a este.
```
{
"version": 4,
"timestamp": 1591141596,
"state": {
"ColorRGB": [
255,
255,
0
]
},
"metadata": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
El dispositivo procesaría el contenido de este mensaje para establecer el estado del dispositivo para que coincida con el estado `desired` del mensaje.
Una vez que el dispositivo actualice el estado para que coincida con el `desired` estado del mensaje, debe devolver el nuevo estado informado AWS IoT mediante la publicación de un mensaje de actualización. Este procedimiento simula esto en el **cliente MQTT**.
**Para actualizar la sombra desde el dispositivo**
1. En el **cliente MQTT**, elija **Publicar en un tema**.
1. En el campo de temas situado encima de la ventana del cuerpo del mensaje, introduzca el tema de la sombra seguido de la acción `/update` `$aws/things/mySimulatedThing/shadow/name/simShadow1/update`; en el cuerpo del mensaje, introduzca este documento de sombra actualizado, que describe el estado actual del dispositivo. Elija **Publicar** para publicar el estado actualizado del dispositivo.
```
{
"state": {
"reported": {
"ColorRGB": [255,255,0]
}
},
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Si el mensaje se ha recibido correctamente AWS IoT, debería aparecer una nueva respuesta en el registro de aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted mensajes **\$1** del **cliente MQTT** con el estado de sombra actual, como en este ejemplo.
```
{
"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"
}
```
Si se actualiza correctamente el estado registrado del dispositivo, también se AWS IoT envía una descripción completa del estado de sombra en un mensaje dedicado al `update/documents` tema, como el cuerpo del mensaje resultante de la actualización oculta realizada por el dispositivo en el procedimiento anterior.
```
{
"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"
}
```
## Ver la actualización en la aplicación
La aplicación ahora puede consultar la sombra del estado actual según haya notificado el dispositivo.
**Para obtener el estado actual de la sombra, utilice el AWS CLI**
1. Desde la línea de comandos, escriba este comando:
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
En las plataformas Windows, puede utilizar `con` en lugar de `/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
1. Dado que el dispositivo acaba de actualizar la sombra para reflejar su estado actual, debe devolver el siguiente documento de sombra.
```
{
"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
}
```
## Más allá de la simulación
Experimente con la interacción entre la AWS CLI (que representa a la aplicación) y la consola (que representa al dispositivo) a fin de modelar su solución de IoT.
# Interacción con sombras
En este tema se describen los mensajes asociados a cada uno de los tres métodos que proporciona AWS IoT para trabajar con sombras. Estos métodos incluyen lo siguiente:
`UPDATE`
Crea una sombra si no existe o actualiza el contenido de una sombra existente con la información de estado proporcionada en el cuerpo del mensaje. AWS IoT registra una marca temporal con cada actualización para indicar cuándo se actualizó el estado por última vez. Cuando el estado de la sombra cambia, AWS IoT envía `/delta` mensajes a todos los suscriptores de MQTT con la diferencia entre los estados `desired` y los `reported` estados. Los dispositivos o aplicaciones que reciben un mensaje `/delta` pueden realizar acciones en función de la diferencia. Por ejemplo, un dispositivo puede actualizar su estado al estado deseado o una aplicación puede actualizar su interfaz de usuario para mostrar el cambio de estado del dispositivo.
`GET`
Recupera un documento de sombra actual que contiene el estado completo de la sombra, incluidos los metadatos.
`DELETE`
Elimina la sombra de dispositivo y todo su contenido.
No puede restaurar un documento sombra de dispositivo eliminado, pero puede crear un nuevo documento con el nombre de un documento sombra de dispositivo eliminado. Si crea un documento de sombra de dispositivo con el mismo nombre que uno que se haya eliminado en las últimas 48 horas, el número de versión del nuevo documento de sombra de dispositivo será el mismo que el del documento eliminado. Si se ha eliminado un documento de sombra de dispositivo desde hace más de 48 horas, el número de versión de un nuevo documento de sombra de dispositivo con el mismo nombre será 0.
## Compatibilidad del protocolo
AWS IoT admite [MQTT](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) y una API REST a través de protocolos HTTPS para interactuar con las sombras. AWS IoT proporciona un conjunto de temas de solicitud y respuesta reservados para las acciones de publicación y suscripción de MQTT. Los dispositivos y las aplicaciones deben suscribirse a los temas de respuesta antes de publicarlos en un tema de solicitud para obtener información sobre cómo AWS IoT se gestionó la solicitud. Para obtener más información, consulte [Temas MQTT de sombra de dispositivo](device-shadow-mqtt.md) y [API REST de sombra de dispositivo](device-shadow-rest-api.md).
## Estado de solicitud y notificación
Al diseñar su solución de IoT utilizando AWS IoT y sombras, debe determinar las aplicaciones o dispositivos que solicitarán cambios y los que los implementarán. Normalmente, un dispositivo implementa y notifica los cambios a la sombra y las aplicaciones y los servicios responden y solicitan cambios en la sombra. Su solución podría ser diferente, pero en los ejemplos de este tema se supone que la aplicación cliente o el servicio solicita cambios en la sombra y el dispositivo realiza los cambios y los notifica de nuevo a la sombra.
## Actualización de la sombra
La aplicación o el servicio pueden actualizar el estado de una sombra mediante la API [UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow) o publicando en el tema [/update](device-shadow-mqtt.md#update-pub-sub-topic). Las actualizaciones afectan únicamente a los campos especificados en la solicitud.
### Actualización de una sombra cuando un cliente solicita un cambio de estado
**Cuando un cliente solicita un cambio de estado en una sombra mediante el protocolo MQTT**
1. El cliente debe tener un documento de sombra actual para que pueda identificar las propiedades que se van a cambiar. Consulte la acción /get para ver cómo obtener el documento de sombra actual.
1. El cliente se suscribe a los siguientes temas de MQTT:
+ `$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. El cliente publica un tema de solicitud de `$aws/things/thingName/shadow/name/shadowName/update` con un documento de estado que contiene el estado deseado de la sombra. Solo las propiedades que se van a cambiar deben incluirse en el documento. Este es un ejemplo de un documento con el estado deseado.
```
{
"state": {
"desired": {
"color": {
"r": 10
},
"engine": "ON"
}
}
}
```
1. Si la solicitud de actualización es válida, AWS IoT actualiza el estado deseado de forma oculta y publica mensajes sobre los siguientes temas:
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/delta`
El mensaje `/update/accepted` incluye un documento de sombra [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) y el mensaje `/update/delta` incluye un documento de sombra [Documento de estado de la respuesta /delta](device-shadow-document.md#device-shadow-example-response-json-delta).
1. Si la solicitud de actualización no es válida, AWS IoT publica un mensaje con el `$aws/things/thingName/shadow/name/shadowName/update/rejected` tema junto con un documento [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) paralelo en el que se describe el error.
**Cuando un cliente solicita un cambio de estado en una sombra mediante el uso de la API**
1. El cliente llama a la API `UpdateThingShadow` con un documento de estado [Documento de estado de la solicitud](device-shadow-document.md#device-shadow-example-request-json) como cuerpo del mensaje.
1. Si la solicitud era válida, AWS IoT devuelve un código HTTP de respuesta correcta y un documento [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) alternativo como cuerpo del mensaje de respuesta.
AWS IoT también publicará un mensaje MQTT `$aws/things/thingName/shadow/name/shadowName/update/delta` sobre el tema con un documento [Documento de estado de la respuesta /delta](device-shadow-document.md#device-shadow-example-response-json-delta) paralelo para todos los dispositivos o clientes que estén suscritos a él.
1. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta a un error HTTP [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) como cuerpo del mensaje de respuesta.
Cuando el dispositivo recibe el estado `/desired` en el tema `/update/delta`, realiza los cambios deseados en el dispositivo. A continuación, envía un mensaje al tema `/update` para notificar su estado actual a la sombra.
### Actualización de una sombra cuando un dispositivo notifica su estado actual
**Cuando un dispositivo notifica su estado actual a la sombra mediante el protocolo MQTT**
1. El dispositivo debe suscribirse a estos temas de MQTT antes de actualizar la sombra:
+ `$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. El dispositivo notifica su estado actual publicando un mensaje en el tema `$aws/things/thingName/shadow/name/shadowName/update` que notifica estado actual, como en este ejemplo.
```
{
"state": {
"reported" : {
"color" : { "r" : 10 },
"engine" : "ON"
}
}
}
```
1. Si AWS IoT acepta la actualización, publica un mensaje `$aws/things/thingName/shadow/name/shadowName/update/accepted` sobre los temas con un documento [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo.
1. Si la solicitud de actualización no es válida, AWS IoT publica un mensaje con el `$aws/things/thingName/shadow/name/shadowName/update/rejected` tema junto con un documento [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) alternativo que describa el error.
**Cuando un dispositivo notifica su estado actual a la sombra mediante la API**
1. El dispositivo llama a la API `UpdateThingShadow` con un documento de estado [Documento de estado de la solicitud](device-shadow-document.md#device-shadow-example-request-json) como cuerpo del mensaje.
1. Si la solicitud era válida, AWS IoT actualiza la sombra y devuelve un código HTTP de respuesta correcta con un documento [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo como cuerpo del mensaje de respuesta.
AWS IoT también publicará un mensaje MQTT `$aws/things/thingName/shadow/name/shadowName/update/delta` sobre el tema junto con un documento [Documento de estado de la respuesta /delta](device-shadow-document.md#device-shadow-example-response-json-delta) alternativo para todos los dispositivos o clientes que estén suscritos a él.
1. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta a un error HTTP [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) como cuerpo del mensaje de respuesta.
### Bloqueo optimista
Puede utilizar la versión del documento de estado para asegurarse de que actualiza la versión más reciente del documento de sombra de un dispositivo. Cuando se suministra una versión con una solicitud de actualización, el servicio rechaza la solicitud con un código de respuesta de conflicto HTTP 409 si la versión actual del documento de estado no coincide con la versión suministrada. El código de respuesta de conflicto también puede aparecer en cualquier API que modifique a `ThingShadow`, lo que incluye `DeleteThingShadow`.
Por ejemplo:
Documento inicial:
```
{
"state": {
"desired": {
"colors": [
"RED",
"GREEN",
"BLUE"
]
}
},
"version": 10
}
```
Actualización: (la versión no coincide; se rechazará esta solicitud)
```
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 9
}
```
Resultado:
```
{
"code": 409,
"message": "Version conflict",
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
Actualización: (la versión coincide; esta solicitud se aceptará)
```
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 10
}
```
Estado final:
```
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 11
}
```
## Recuperación de un documento de sombra
Puede recuperar un documento de sombra utilizando la API [GetThingShadow](device-shadow-rest-api.md#API_GetThingShadow) o suscribiéndose y publicando en el tema [/get](device-shadow-mqtt.md#get-pub-sub-topic). Esto recupera un documento de sombra completo, incluido cualquier delta entre los estados `desired` y `reported`. El procedimiento para esta tarea es el mismo si el dispositivo o un cliente está realizando la solicitud.
**Para recuperar un documento de sombra mediante el protocolo MQTT**
1. El dispositivo o cliente debe suscribirse a estos temas de MQTT antes de actualizar la sombra:
+ `$aws/things/thingName/shadow/name/shadowName/get/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/get/rejected`
1. El dispositivo o cliente publica un mensaje en el tema `$aws/things/thingName/shadow/name/shadowName/get` con un cuerpo de mensaje vacío.
1. Si la solicitud se realiza correctamente, AWS IoT publica un mensaje en el `$aws/things/thingName/shadow/name/shadowName/get/accepted` tema con una [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) en el cuerpo del mensaje.
1. Si la solicitud no era válida, AWS IoT publica un mensaje en el `$aws/things/thingName/shadow/name/shadowName/get/rejected` tema con una [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) en el cuerpo del mensaje.
**Para recuperar un documento de sombra mediante una API REST**
1. El dispositivo o cliente llama a la API `GetThingShadow` con un cuerpo de mensaje vacío.
1. Si la solicitud es válida, AWS IoT devuelve un código HTTP de respuesta correcta con un documento [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo como cuerpo del mensaje de respuesta.
1. Si la solicitud no es válida, AWS IoT devuelve un código de respuesta de error HTTP an [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) como cuerpo del mensaje de respuesta.
## Eliminación de datos de sombra
Hay dos formas de eliminar datos de sombra: puede eliminar propiedades específicas en el documento de sombra y puede eliminar la sombra por completo.
+ Para eliminar propiedades específicas de una sombra, actualice la sombra; sin embargo, establezca el valor de las propiedades que desea eliminar en `null`. Los campos con un valor `null` se quitan del documento de sombra.
+ Para eliminar toda la sombra, use la API [DeleteThingShadow](device-shadow-rest-api.md#API_DeleteThingShadow) o publique en el tema [/delete](device-shadow-mqtt.md#delete-pub-sub-topic).
**nota**
Al eliminar una sombra, no se restablece su número de versión a cero de forma inmediata. Se restablecerá a cero después de 48 horas.
### Eliminación de una propiedad de un documento de sombra
**Para eliminar una propiedad de una sombra mediante el protocolo MQTT**
1. El dispositivo o cliente debe tener un documento de sombra actual para que pueda identificar las propiedades que se van a cambiar. Consulte [Recuperación de un documento de sombra](#retrieving-device-shadow) para obtener más información sobre cómo obtener el documento de sombra actual.
1. El dispositivo o cliente se suscribe a estos temas de MQTT:
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/rejected`
1. El dispositivo o cliente publica un tema de solicitud `$aws/things/thingName/shadow/name/shadowName/update` con un documento de estado que asigna valores `null` a las propiedades de la sombra que se va a eliminar. Solo las propiedades que se van a cambiar deben incluirse en el documento. Este es un ejemplo de un documento que elimina la propiedad `engine`.
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. Si la solicitud de actualización es válida, AWS IoT elimina las propiedades especificadas en la sombra y publica un mensaje con el `$aws/things/thingName/shadow/name/shadowName/update/accepted` tema con un documento [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo en el cuerpo del mensaje.
1. Si la solicitud de actualización no es válida, AWS IoT publique un mensaje con el `$aws/things/thingName/shadow/name/shadowName/update/rejected` tema junto con un documento [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) paralelo en el que se describa el error.
**Para eliminar una propiedad de una sombra mediante la API REST**
1. El dispositivo o cliente llama a la API `UpdateThingShadow` con un [Documento de estado de la solicitud](device-shadow-document.md#device-shadow-example-request-json) que asigna valores `null` a las propiedades de la sombra para eliminar. Incluya solo las propiedades que desee eliminar en el documento. Este es un ejemplo de un documento que elimina la propiedad `engine`.
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. Si la solicitud era válida, AWS IoT devuelve un código HTTP de respuesta correcta y un documento [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) alternativo como cuerpo del mensaje de respuesta.
1. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta de error HTTP an [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) como cuerpo del mensaje de respuesta.
### Eliminación de una sombra
Estos son algunos factores que debemos tener en cuenta al eliminar la sombra de un dispositivo.
+ Al establecer el estado de sombra del dispositivo en `null` no se elimina la sombra. La versión de sombra se incrementará en la próxima actualización.
+ La eliminación de la sombra de un dispositivo no elimina el objeto. La eliminación de un objeto no elimina la sombra del dispositivo correspondiente.
+ Al eliminar una sombra, no se restablece su número de versión a cero de forma inmediata. Se restablecerá a cero después de 48 horas.
**Para eliminar una sombra mediante el protocolo MQTT**
1. El dispositivo o cliente se suscribe a estos temas de MQTT:
+ `$aws/things/thingName/shadow/name/shadowName/delete/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/delete/rejected`
1. El dispositivo o cliente publica un `$aws/things/thingName/shadow/name/shadowName/delete` con un búfer de mensaje vacío.
1. Si la solicitud de eliminación es válida, AWS IoT elimina la sombra y publica un mensaje con el `$aws/things/thingName/shadow/name/shadowName/delete/accepted` tema y un documento [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo abreviado en el cuerpo del mensaje. Este es un ejemplo del mensaje de eliminación aceptado:
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Si la solicitud de actualización no es válida, AWS IoT publique un mensaje con el `$aws/things/thingName/shadow/name/shadowName/delete/rejected` tema junto con un documento [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) alternativo que describa el error.
**Para eliminar una sombra mediante la API REST**
1. El dispositivo o cliente llama a la API `DeleteThingShadow` con un búfer de mensaje vacío.
1. Si la solicitud era válida, AWS IoT devuelve un código HTTP de respuesta correcta [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) y un documento [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted) alternativo abreviado en el cuerpo del mensaje. Este es un ejemplo del mensaje de eliminación aceptado:
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta de error HTTP an [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json) como cuerpo del mensaje de respuesta.
# API REST de sombra de dispositivo
Una sombra expone el siguiente URI para actualizar la información de estado:
```
https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow
```
El punto final es específico de su Cuenta de AWS. Para buscar el punto de conexión, puede hacer lo siguiente:
+ Utilice el comando [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) desde la AWS CLI.
+ Utilice la configuración AWS IoT de la consola. En **Configuración**, el punto de conexión aparece en **Punto de conexión personalizado**
+ Usa la página de detalles de la AWS IoT consola. En la consola de :
1. Abra **Administrar** y, en **Administrar**, seleccione **Objetos**.
1. En la lista de objetos, seleccione el objeto para el que desea obtener la URI del punto de conexión.
1. Seleccione la pestaña **Sombras de dispositivo** y seleccione la sombra. Puede ver el URI del punto de conexión en la sección **URL de la sombra de dispositivo** de la página **Detalles de la sombra de dispositivo**.
El formato del punto de enlace es el siguiente:
```
identifier.iot.region.amazonaws.com
```
La API REST oculta sigue las mismas protocols/port asignaciones HTTPS que se describen en. [Protocolos de comunicación de dispositivos](protocols.md)
**nota**
Para utilizarla APIs, debe utilizarla `iotdevicegateway` como nombre de servicio para la autenticación. Para obtener más información, consulte [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)
También puede usar la API para crear una sombra con nombre proporcionándole `name=shadowName` como parte del parámetro de consulta de la API.
## GetThingShadow
Obtiene la sombra de objeto especificado.
El documento de estado de respuesta incluye el delta entre los estados `desired` y `reported`.
**Solicitud**
La solicitud incluye los encabezados HTTP estándar y el URI siguiente:
```
HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
El parámetro de consulta `name` no es necesario para sombras sin nombre (clásicas).
**Respuesta**
En caso de éxito, la respuesta incluye encabezados HTTP estándar, así como el código y el cuerpo siguientes:
```
HTTP 200
Response Body: response state document
```
Para obtener más información, consulte [Ejemplo de documento de estado de respuesta](device-shadow-document.md#device-shadow-example-response-json).
**Autorización**
Para recuperar una sombra, se necesita una política que permita al intermediario ejecutar la acción `iot:GetThingShadow`. El servicio de sombra de dispositivo acepta dos formas de autenticación: Signature Version 4 con credenciales IAM o autenticación mutua TLS con un certificado de cliente.
A continuación, se muestra una política de ejemplo que permite a un intermediario recuperar la sombra de un dispositivo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:GetThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## UpdateThingShadow
Actualiza la sombra del objeto especificado.
Las actualizaciones solo afectan a los campos especificados en el documento de estado de la solicitud. Todos los campos que tengan el valor `null` se eliminarán de la sombra del dispositivo.
**Solicitud**
La solicitud incluye los encabezados HTTP estándar, así como el URI y el cuerpo siguientes:
```
HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document
```
El parámetro de consulta `name` no es necesario para sombras sin nombre (clásicas).
Para obtener más información, consulte [Ejemplo de documento de estado de solicitud](device-shadow-document.md#device-shadow-example-request-json).
**Respuesta**
En caso de éxito, la respuesta incluye encabezados HTTP estándar, así como el código y el cuerpo siguientes:
```
HTTP 200
Response body: response state document
```
Para obtener más información, consulte [Ejemplo de documento de estado de respuesta](device-shadow-document.md#device-shadow-example-response-json).
**Autorización**
Para actualizar una sombra se necesita una política que permita al intermediario ejecutar la acción `iot:UpdateThingShadow`. El servicio de sombra de dispositivo acepta dos formas de autenticación: Signature Version 4 con credenciales IAM o autenticación mutua TLS con un certificado de cliente.
A continuación, se muestra una política de ejemplo que permite a un intermediario actualizar la sombra de un dispositivo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:UpdateThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## DeleteThingShadow
Elimina la sombra de objeto especificado.
**Solicitud**
La solicitud incluye los encabezados HTTP estándar y el URI siguiente:
```
HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
El parámetro de consulta `name` no es necesario para sombras sin nombre (clásicas).
**Respuesta**
En caso de éxito, la respuesta incluye encabezados HTTP estándar, así como el código y el cuerpo siguientes:
```
HTTP 200
Response body: Empty response state document
```
Tenga en cuenta que, al eliminar una sombra, no se restablece su número de versión a 0.
**Autorización**
Para eliminar la sombra de un dispositivo se necesita una política que permita al intermediario ejecutar la acción `iot:DeleteThingShadow`. El servicio de sombra de dispositivo acepta dos formas de autenticación: Signature Version 4 con credenciales IAM o autenticación mutua TLS con un certificado de cliente.
A continuación, se muestra una política de ejemplo que permite a un intermediario eliminar la sombra de un dispositivo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DeleteThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## ListNamedShadowsForThing
Muestra las sombras del objeto especificado.
**Solicitud**
La solicitud incluye los encabezados HTTP estándar y el URI siguiente:
```
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
```
nextToken
El token para recuperar el siguiente grupo de resultados.
Este valor se devuelve en los resultados paginados y se utiliza en la llamada que devuelve la página siguiente.
pageSize
El número de nombres de sombra que devolver en cada llamada. Véase también `nextToken`.
thingName
El nombre del objeto para el que mostrar las sombras con nombre.
**Respuesta**
En caso de éxito, la respuesta incluye encabezados HTTP estándar, así como el código de respuesta siguiente y un [Documento de respuesta de lista de nombres de sombra](device-shadow-document.md#device-shadow-list-json).
**nota**
La sombra sin nombre (clásica) no aparece en esta lista. La respuesta es una lista vacía si solo tiene una sombra clásica o si el `thingName` que ha especificado no existe.
```
HTTP 200
Response body: Shadow name list document
```
**Autorización**
Para incluir la sombra de un dispositivo, se necesita una política que permita que el intermediario ejecute la acción `iot:ListNamedShadowsForThing`. El servicio de sombra de dispositivo acepta dos formas de autenticación: Signature Version 4 con credenciales IAM o autenticación mutua TLS con un certificado de cliente.
A continuación, se muestra una política de ejemplo que permite a un intermediario mostrar las sombras con nombre de un objeto:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:ListNamedShadowsForThing",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
# Temas MQTT de sombra de dispositivo
El servicio Device Shadow utiliza temas MQTT reservados para permitir a los dispositivos y las aplicaciones obtener, actualizar o eliminar la información de estado de un dispositivo (sombra).
La publicación y suscripción de temas de sombra requiere una autorización basada en temas. AWS IoT se reserva el derecho a añadir nuevos temas a la estructura de temas existente. Por este motivo, le recomendamos que evite las suscripciones de tipo comodín a los temas de sombra. Por ejemplo, evite suscribirse a filtros de temas, `$aws/things/thingName/shadow/#` ya que el número de temas que coinciden con este filtro podría aumentar a medida que se AWS IoT introduzcan nuevos temas ocultos. Para consultar ejemplos de mensajes publicados en estos temas vaya a [Interacción con sombras](device-shadow-data-flow.md).
Las sombras pueden ser con nombre o sin nombre (clásico). Los temas utilizados por cada uno solo difieren en el prefijo del tema. Esta tabla muestra el prefijo de tema utilizado por cada tipo de sombra.
| Valor de *ShadowTopicPrefix* | Tipo de sombra |
| --- | --- |
| \$1aws/things/thingName/shadow | Sombra sin nombre (clásica) |
| \$1aws/things/thingName/shadow/name/shadowName | Sombra con nombre |
Para crear un tema completo, seleccione el `ShadowTopicPrefix` para el tipo de sombra al que desea hacer referencia, reemplace `thingName` y `shadowName` si procede, por sus valores correspondientes y, a continuación, anéxelo al código auxiliar del tema como se muestra en las secciones siguientes.
A continuación se muestran los temas MQTT utilizados para interactuar con las sombras.
**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
Publique un mensaje vacío en este tema para obtener la sombra de objeto:
```
ShadowTopicPrefix/get
```
AWS IoT responde publicando en uno de los dos[/get/accepted](#get-accepted-pub-sub-topic). [/get/rejected](#get-rejected-pub-sub-topic)
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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 publica un documento paralelo de respuesta sobre este tema al devolver la sombra del dispositivo:
```
ShadowTopicPrefix/get/accepted
```
Para obtener más información, consulte [Documentos de estado de la respuesta](device-shadow-document.md#device-shadow-example-response-json).
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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 publica un documento de respuesta a errores sobre este tema cuando no puede mostrar la sombra del dispositivo:
```
ShadowTopicPrefix/get/rejected
```
Para obtener más información, consulte [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json).
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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
Publique un documento de estado de solicitud en este tema para actualizar la sombra del dispositivo:
```
ShadowTopicPrefix/update
```
El cuerpo del mensaje contiene un [documento de estado de solicitud parcial](device-shadow-document.md#device-shadow-example-request-json).
Un cliente que intente actualizar el estado de un dispositivo enviaría un documento de estado de solicitud JSON con la propiedad `desired` como esta:
```
{
"state": {
"desired": {
"color": "red",
"power": "on"
}
}
}
```
Un dispositivo que actualice su sombra enviaría un documento de estado de solicitud JSON con la propiedad `reported`, como esta:
```
{
"state": {
"reported": {
"color": "red",
"power": "on"
}
}
}
```
AWS IoT responde publicando en una de las [/update/accepted](#update-accepted-pub-sub-topic) dos[/update/rejected](#update-rejected-pub-sub-topic).
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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 publica un documento de estado de respuesta sobre este tema cuando acepta un cambio en la sombra del dispositivo, y el documento de estado de respuesta contiene valores `desired` y `reported` estados diferentes:
```
ShadowTopicPrefix/update/delta
```
El búfer del mensaje contiene un [Documento de estado de la respuesta /delta](device-shadow-document.md#device-shadow-example-response-json-delta).
### Detalles del cuerpo del mensaje
+ Un mensaje publicado en `update/delta` incluye únicamente los atributos deseados que difieren entre las secciones `desired` y `reported`. Contiene todos estos atributos, independientemente de si se encuentran en el mensaje de actualización actual o si ya estaban almacenados en AWS IoT. No se incluyen los atributos que no difieren entre las secciones `desired` y `reported`.
+ Si un atributo se encuentra en la sección `reported`, pero no tiene equivalente en la sección `desired`, no se incluye.
+ Si un atributo se encuentra en la sección `desired`, pero no tiene equivalente en la sección `reported`, se incluye.
+ Si se elimina un atributo de la sección `reported`, pero sigue existiendo en la sección `desired`, se incluye.
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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 publica un documento de estado de respuesta sobre este tema cuando acepta un cambio en la sombra del dispositivo:
```
ShadowTopicPrefix/update/accepted
```
El búfer del mensaje contiene un [Documento de estado de la respuesta /aceptado](device-shadow-document.md#device-shadow-example-response-json-accepted).
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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 publica un documento de estado sobre este tema cada vez que se realiza correctamente una actualización de la sombra:
```
ShadowTopicPrefix/update/documents
```
El cuerpo del mensaje contiene un [Documento de estado de respuesta /documentos](device-shadow-document.md#device-shadow-example-response-json-documents).
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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 publica un documento de respuesta a errores sobre este tema cuando rechaza un cambio en la sombra del dispositivo:
```
ShadowTopicPrefix/update/rejected
```
El cuerpo del mensaje contiene un [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json).
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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
Para eliminar la sombra de un dispositivo, publique un mensaje vacío para eliminar el tema:
```
ShadowTopicPrefix/delete
```
El contenido del mensaje no se tiene en cuenta.
Tenga en cuenta que, al eliminar una sombra, no se restablece su número de versión a 0.
AWS IoT responde publicando en una de las [/delete/accepted](#delete-accepted-pub-sub-topic) dos[/delete/rejected](#delete-rejected-pub-sub-topic).
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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 publica un mensaje sobre este tema cuando se elimina la sombra de un dispositivo:
```
ShadowTopicPrefix/delete/accepted
```
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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 publica un documento de respuesta a errores sobre este tema cuando no puede eliminar la sombra del dispositivo:
```
ShadowTopicPrefix/delete/rejected
```
El cuerpo del mensaje contiene un [Documento de respuesta de error](device-shadow-document.md#device-shadow-example-error-json).
### Ejemplo de política de
A continuación, mostramos un ejemplo de la política requerida:
****
```
{
"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"
]
}
]
}
```
# Documentos del servicio Device Shadow
El servicio Device Shadow respeta todas las reglas de la especificación JSON. Los valores, objetos y matrices se almacenan en el documento de sombra del dispositivo.
**Topics**
+ [Ejemplos de documento de sombra](#device-shadow-document-syntax)
+ [Propiedades del documento](#document-structure)
+ [Estado delta](#delta-state)
+ [Control de versiones de documentos de sombra](#versioning)
+ [Tokens de cliente en documentos de sombra](#client-token)
+ [Propiedades de documento de sombra vacío](#device-shadow-empty-fields)
+ [Valores de matriz en documentos sombra](#device-shadow-arrays)
## Ejemplos de documento de sombra
El servicio Device Shadow utiliza estos documentos en las operaciones UPDATE, GET y DELETE mediante la [API REST](device-shadow-rest-api.md) o los [ Pub/Sub mensajes MQTT](device-shadow-mqtt.md).
**Topics**
+ [Documento de estado de la solicitud](#device-shadow-example-request-json)
+ [Documentos de estado de la respuesta](#device-shadow-example-response-json)
+ [Documento de respuesta de error](#device-shadow-example-error-json)
+ [Documento de respuesta de lista de nombres de sombra](#device-shadow-list-json)
### Documento de estado de la solicitud
Un documento de estado de solicitud tiene el siguiente formato:
```
{
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer1,
"attribute2": "string1",
...
"attributeN": boolean1
}
},
"clientToken": "token",
"version": version
}
```
+ `state`: las actualizaciones solo afectan a los campos especificados. Normalmente, utilizará la propiedad `desired` o la propiedad `reported`, pero no ambas en la misma solicitud.
+ `desired`: las propiedades y los valores de estado que estamos solicitando actualizar en el dispositivo.
+ `reported`: las propiedades y los valores de estado informados por el dispositivo.
+ `clientToken`: si se usa, puede encontrar la correspondencia entre la solicitud y la respuesta mediante el token del cliente.
+ `version`: si se utiliza, el servicio Device Shadow procesa la actualización solo si la versión especificada coincide con la versión más reciente que tiene.
### Documentos de estado de la respuesta
Los documentos de estado de respuesta tienen el siguiente formato en función del tipo de respuesta.
#### Documento de estado de la respuesta /aceptado
```
{
"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
}
```
#### Documento de estado de la respuesta /delta
```
{
"state": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"metadata": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"timestamp": timestamp,
"clientToken": "token",
"version": version
}
```
#### Documento de estado de respuesta /documentos
```
{
"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"
}
```
#### Propiedades del documento de estado de la respuesta
+ `previous`: tras una actualización correcta, contiene el `state` del objeto antes de la actualización.
+ `current`: tras una actualización correcta, contiene el `state` del objeto después de la actualización.
+ `state`
+ `reported`: solo ocurre si un objeto ha notificado datos en la sección `reported` y contiene únicamente los campos que se encontraban en el documento de estado de la solicitud.
+ `desired`: solo ocurre si un dispositivo ha notificado datos en la sección `desired` y contiene únicamente los campos que se encontraban en el documento de estado de la solicitud.
+ `metadata`: contiene las marcas temporales de cada atributo de las secciones `desired` y `reported` para que se pueda determinar cuándo se actualizó el estado.
+ `timestamp`— La época, fecha y hora en que se generó la respuesta. AWS IoT
+ `clientToken` solo está presente si se ha utilizando un token de cliente al publicar un JSON válido en el tema `/update`.
+ `version`: la versión actual del documento de la sombra del dispositivo compartido en AWS IoT. Se aumenta en una unidad con relación a la versión anterior del documento.
### Documento de respuesta de error
Un documento de respuesta de error tiene el formato siguiente:
```
{
"code": error-code,
"message": "error-message",
"timestamp": timestamp,
"clientToken": "token"
}
```
+ `code` código de respuesta HTTP que indica el tipo de error.
+ `message` mensaje de texto que proporciona información adicional.
+ `timestamp`— La fecha y la hora en que se generó la respuesta. AWS IoT Esta propiedad no está presente en todos los documentos de respuesta de error.
+ `clientToken`: solo ocurre si se ha utilizado un token de cliente en el mensaje publicado.
Para obtener más información, consulte [Mensajes de error de Device Shadow](device-shadow-error-messages.md).
### Documento de respuesta de lista de nombres de sombra
Un documento de respuesta de lista de nombre de sombra tiene el siguiente formato:
```
{
"results": [
"shadowName-1",
"shadowName-2",
"shadowName-3",
"shadowName-n"
],
"nextToken": "nextToken",
"timestamp": timestamp
}
```
+ `results`: la matriz de nombres de sombras.
+ `nextToken`: el valor del token que se utilizará en las solicitudes paginadas para obtener la siguiente página de la secuencia. Esta propiedad no está presente cuando no hay más nombres de sombra que devolver.
+ `timestamp`— La fecha y la hora en que se generó la respuesta AWS IoT.
## Propiedades del documento
El documento de sombra de un dispositivo tiene las propiedades siguientes:
`state`
`desired`
El estado deseado del dispositivo. Las aplicaciones pueden escribir en esta parte del documento para actualizar el estado de un dispositivo directamente, sin tener que conectarse al mismo.
`reported`
El estado notificado del dispositivo. Los dispositivos escriben en esta parte del documento para notificar su nuevo estado. Las aplicaciones leen esta parte del documento para determinar el último estado notificado del dispositivo.
`metadata`
Información acerca de los datos almacenados en la sección `state` del documento. Esto incluye las marcas de tiempo, según la fecha de inicio Unix, para cada atributo de la sección `state`, lo que le permite determinar cuándo se actualizaron.
Los metadatos no contribuyen al tamaño de documento para establecer los límites del servicio o el precio. Para obtener más información, consulte [AWS IoT Límites de servicio](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot).
`timestamp`
Indica cuándo se envió el mensaje AWS IoT. Mediante el uso de la marca temporal en el mensaje y las marcas temporales para atributos individuales en la sección `desired` o `reported`, un dispositivo puede determinar la antigüedad de una propiedad, incluso si el dispositivo no tiene un reloj interno.
`clientToken`
Una cadena única del dispositivo que le permite asociar respuestas a solicitudes en un entorno de MQTT.
`version`
La versión del documento. Cada vez que el documento se actualiza, su número de versión se incrementa. Se utiliza para garantizar que la versión del documento que se actualiza sea la más reciente.
Para obtener más información, consulte [Ejemplos de documento de sombra](#device-shadow-document-syntax).
## Estado delta
El estado delta es un tipo de estado virtual que contiene la diferencia entre los estados `desired` y `reported`. Los campos de la sección `desired` que no están incluidos en la sección `reported` se incluyen en el delta. Los campos que están en la sección `reported` y no están en la sección `desired` no se incluyen en el delta. El delta contiene metadatos, y sus valores son iguales a los metadatos del campo `desired`. Por ejemplo:
```
{
"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
}
}
```
Cuando los objetos anidados difieren, el delta contiene la ruta de acceso a la raíz.
```
{
"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
}
```
El servicio Device Shadow calcula la diferencia iterando por cada campo con el estado `desired` y comparándolo con el estado `reported`.
Las matrices se tratan como valores. Si una matriz de la sección `desired` no coincide con la matriz de la sección `reported`, toda la matriz deseada se copia en el delta.
## Control de versiones de documentos de sombra
El servicio Device Shadow admite el control de versiones en cada mensaje de actualización, tanto de solicitud como de respuesta. Esto significa que con cada actualización de una sombra, se incrementa la versión del documento JSON. Esto permite garantizar dos cosas:
+ Un cliente puede recibir un error si intenta sobrescribir una sombra con una versión más antigua. Se informa al cliente de que debe volver a sincronizarlo para poder actualizar la sombra de un dispositivo.
+ Un cliente puede decidir omitir un mensaje recibido si su versión es anterior a la que tiene almacenada.
Un cliente puede omitir la coincidencia de versiones al no incluir una versión en el documento de sombra.
## Tokens de cliente en documentos de sombra
Puede utilizar un token de cliente con mensajes basados en MQTT para verificar que el mismo token de cliente esté contenido en una solicitud y en la respuesta a dicha solicitud. De esta forma se garantiza que la respuesta y la solicitud estén asociadas.
**nota**
El token de cliente no puede ser superior a 64 bytes. Un token de cliente que sea superior a 64 bytes provocará una respuesta 400 (solicitud errónea) y un mensaje de error *clientToken no válido*.
## Propiedades de documento de sombra vacío
Las propiedades `reported` y `desired` de un documento de sombra pueden estar vacías u omitidas cuando no se aplican al estado de sombra actual. Por ejemplo, un documento de sombra contiene una propiedad `desired` solo si tiene un estado deseado. A continuación se muestra un ejemplo válido de un documento de estado sin propiedad `desired`:
```
{
"reported" : { "temp": 55 }
}
```
La propiedad `reported` también puede estar vacía, por ejemplo, si el dispositivo no ha actualizado la sombra:
```
{
"desired" : { "color" : "RED" }
}
```
Si una actualización hace que las propiedades `desired` o `reported` se conviertan en nulas, se quita del documento. A continuación se muestra cómo quitar la propiedad `desired` estableciéndola en `null`. Puede hacerlo cuando un dispositivo actualice su estado, por ejemplo.
```
{
"state": {
"reported": {
"color": "red"
},
"desired": null
}
}
```
Un documento de sombra también puede no tener ni la propiedad `desired` ni `reported`, lo que hace que el documento de sombra esté vacío. Este es un ejemplo de un documento de sombra vacío pero válido.
```
{
}
```
## Valores de matriz en documentos sombra
Las sombras son compatibles con las matrices, pero las tratan como valores normales, en el sentido de que la actualización de una matriz sustituye toda la matriz. No es posible actualizar parte de una matriz.
Estado inicial:
```
{
"desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}
```
Actualizar:
```
{
"desired" : { "colors" : ["RED"] }
}
```
Estado final:
```
{
"desired" : { "colors" : ["RED"] }
}
```
Las matrices no pueden tener valores nulos. Por ejemplo, la matriz siguiente no es válida y se rechazará.
```
{
"desired" : {
"colors" : [ null, "RED", "GREEN" ]
}
}
```
# Mensajes de error de Device Shadow
El servicio Device Shadow publica un mensaje en el tema de errores (a través de MQTT) si se produce un error al intentar cambiar el documento de estado. Este mensaje solo se genera como respuesta a una solicitud de publicación en uno de los temas `$aws` reservados. Si el cliente actualiza el documento mediante la API REST, recibe el código de error HTTP como parte de su respuesta y no se genera un mensaje de error MQTT.
****
| Código de error HTTP | Mensajes de error |
| --- | --- |
| 400 (solicitud errónea) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/device-shadow-error-messages.html) |
| 401 (sin autorización) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/device-shadow-error-messages.html) |
| 403 (prohibido) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/device-shadow-error-messages.html) |
| 404 (no encontrado) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/device-shadow-error-messages.html) |
| 409 (conflicto) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/device-shadow-error-messages.html) |
| 413 (carga demasiado grande) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/device-shadow-error-messages.html) |
| 415 (tipo de medio incompatible) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/device-shadow-error-messages.html) |
| 429 (demasiadas solicitudes) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/device-shadow-error-messages.html) |
| 500 (error de servidor interno) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/device-shadow-error-messages.html) |