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.
# 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" ]
}
}
```