Interacción con sombras - AWS IoT Core (Núcleo de AWS)
Compatibilidad del protocoloEstado de solicitud y notificaciónActualización de la sombraRecuperación de un documento de sombraEliminación de datos de sombra

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.

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 cambia el estado de la sombra, AWS IoT envía mensajes /delta a todos los suscriptores de MQTT con la diferencia entre los estados desired y reported. 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 y todo su contenido. No se puede restaurar una sombra de dispositivo eliminada, pero se puede crear otra con el mismo nombre.

Compatibilidad del protocolo

AWS IoT admite MQTT y una API REST a través de protocolos HTTPS para interactuar con sombras. AWS IoT proporciona un conjunto de temas de solicitud y respuesta reservados para acciones de publicación y suscripción de MQTT. Los dispositivos y las aplicaciones deben suscribirse a los temas de respuesta antes de publicar un tema de solicitud para obtener información sobre cómo trató AWS IoT la solicitud. Para obtener más información, consulte Temas MQTT de sombra de dispositivo y API REST de sombra de dispositivo.

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 o publicando en el tema /update. 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.

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

  3. 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"
    }
  }
}

  4. Si la solicitud de actualización es válida, AWS IoT actualiza el estado deseado en la sombra y publica mensajes sobre estos temas:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    El mensaje /update/accepted contiene un documento de sombra Documento de estado de la respuesta /aceptado y el mensaje /update/delta contiene un documento de sombra Documento de estado de la respuesta /delta.

  5. Si la solicitud de actualización no es válida, AWS IoT publica un mensaje con el tema $aws/things/thingName/shadow/name/shadowName/update/rejected con un documento de sombra Documento de respuesta de error que 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 como cuerpo del mensaje.

  2. Si la solicitud fuera válida, AWS IoT devuelve un código de respuesta HTTP correcta y un documento de sombra Documento de estado de la respuesta /aceptado como cuerpo del mensaje de respuesta.

    AWS IoT también publicará un mensaje MQTT en el tema $aws/things/thingName/shadow/name/shadowName/update/delta con un documento de sombra Documento de estado de la respuesta /delta para cualquier dispositivo o cliente que se suscriba a él.

  3. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta de error HTTP y Documento de respuesta de error 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

  2. 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"
        }
    }
}

  3. Si AWS IoT acepta la actualización, publica un mensaje en los temas $aws/things/thingName/shadow/name/shadowName/update/accepted con un documento de sombra Documento de estado de la respuesta /aceptado.

  4. Si la solicitud de actualización no es válida, AWS IoT publica un mensaje con el tema $aws/things/thingName/shadow/name/shadowName/update/rejected con un documento de sombra Documento de respuesta de error que describe 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 como cuerpo del mensaje.

  2. Si la solicitud era válida, AWS IoT actualiza la sombra y devuelve un código de respuesta HTTP correcto con un documento de sombra Documento de estado de la respuesta /aceptado como cuerpo del mensaje de respuesta.

    AWS IoT también publicará un mensaje MQTT en el tema $aws/things/thingName/shadow/name/shadowName/update/delta con un documento de sombra Documento de estado de la respuesta /delta para cualquier dispositivo o cliente que se suscriba a él.

  3. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta de error HTTP y Documento de respuesta de error 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.

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 o suscribiéndose y publicando en el tema /get. 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

  2. El dispositivo o cliente publica un mensaje en el tema $aws/things/thingName/shadow/name/shadowName/get con un cuerpo de mensaje vacío.

  3. Si la solicitud se realiza correctamente, AWS IoT publica un mensaje en el tema $aws/things/thingName/shadow/name/shadowName/get/accepted con un Documento de estado de la respuesta /aceptado en el cuerpo del mensaje.

  4. Si la solicitud no era válida, AWS IoT publica un mensaje en el tema $aws/things/thingName/shadow/name/shadowName/get/rejected con un Documento de respuesta de error 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.

  2. Si la solicitud es válida, AWS IoT devuelve un código de respuesta HTTP correcto con un documento de sombra Documento de estado de la respuesta /aceptado como cuerpo del mensaje de respuesta.

  3. Si la solicitud no es válida, AWS IoT devuelve un código de respuesta de error HTTP y Documento de respuesta de error 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 eliminan del documento de sombra.

  • Para eliminar toda la sombra, use la API DeleteThingShadow o publique en el tema /delete.

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 para obtener información sobre cómo obtener el documento de sombra actual.

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

  3. 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
    }
  }
}

  4. Si la solicitud de actualización es válida, AWS IoT elimina las propiedades especificadas en la sombra y publica un mensaje con el tema $aws/things/thingName/shadow/name/shadowName/update/accepted con un documento de sombra Documento de estado de la respuesta /aceptado en el cuerpo del mensaje.

  5. Si la solicitud de actualización no es válida, AWS IoT publica un mensaje con el tema $aws/things/thingName/shadow/name/shadowName/update/rejected con un documento de sombra Documento de respuesta de error que describe 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 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
    }
  }
}

  2. Si la solicitud fuera válida, AWS IoT devuelve un código de respuesta HTTP correcta y un documento de sombra Documento de estado de la respuesta /aceptado como cuerpo del mensaje de respuesta.

  3. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta de error HTTP y Documento de respuesta de error como cuerpo del mensaje de respuesta.

Eliminación de una sombra

nota

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.

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

  2. El dispositivo o cliente publica un $aws/things/thingName/shadow/name/shadowName/delete con un búfer de mensaje vacío.

  3. Si la solicitud de eliminación es válida, AWS IoT elimina la sombra y publica un mensaje con el tema $aws/things/thingName/shadow/name/shadowName/delete/accepted y un documento de sombra Documento de estado de la respuesta /aceptado abreviado en el cuerpo del mensaje. Este es un ejemplo del mensaje de eliminación aceptado: 

    {
  "version": 4,
  "timestamp": 1591057529
}

  4. Si la solicitud de actualización no es válida, AWS IoT publica un mensaje con el tema $aws/things/thingName/shadow/name/shadowName/delete/rejected con un documento de sombra Documento de respuesta de error que describe 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.

  2. Si la solicitud era válida, AWS IoT devuelve un código de respuesta HTTP correcta Documento de estado de la respuesta /aceptado y un documento de sombra Documento de estado de la respuesta /aceptado abreviado en el cuerpo del mensaje. Este es un ejemplo del mensaje de eliminación aceptado: 

    {
  "version": 4,
  "timestamp": 1591057529
}

  3. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta de error HTTP y Documento de respuesta de error como cuerpo del mensaje de respuesta.