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.

Ejemplos de documento de sombra

El servicio Device Shadow utiliza los siguientes documentos en operaciones UPDATE, GET y DELETE mediante la API REST o mensajes de publicación/suscripción MQTT.

Ejemplos

• Documento de estado de la solicitud
• Documentos de estado de la respuesta
• Documento de respuesta de error
• Documento de respuesta de lista de nombres de sombra

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.

  • delta: solo ocurre solo si los datos desired difieren de los datos reported actuales de la sombra.

• 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.

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.

nota

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 Service Limits.

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.

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" ]
    }
}