Interacción con sombras - AWS IoT Core
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 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 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 publicar 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 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 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 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 $aws/things/thingName/shadow/name/shadowName/update/rejected tema junto con un documento Documento de respuesta de error 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 como cuerpo del mensaje.

  2. 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 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 paralelo para todos los dispositivos o clientes que estén suscritos a él.

  3. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta a un error HTTP 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 $aws/things/thingName/shadow/name/shadowName/update/accepted sobre los temas con un documento Documento de estado de la respuesta /aceptado paralelo.

  4. 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 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 como cuerpo del mensaje.

  2. 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 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 alternativo para todos los dispositivos o clientes que estén suscritos a él.

  3. Si la solicitud no era válida, AWS IoT devuelve un código de respuesta a un error HTTP 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. 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 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 $aws/things/thingName/shadow/name/shadowName/get/accepted tema con una 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 $aws/things/thingName/shadow/name/shadowName/get/rejected tema con una 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 HTTP de respuesta correcta con un documento Documento de estado de la respuesta /aceptado paralelo 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 an 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 quitan del documento de sombra.

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

nota

Al eliminar una sombra no se restablece su número de versión a cero de una vez. 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 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 de 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 paralelo en el cuerpo del mensaje.

  5. 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 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 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 era válida, AWS IoT devuelve un código HTTP de respuesta correcta y un documento Documento de estado de la respuesta /aceptado alternativo 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 an Documento de respuesta de error 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 una vez. 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

  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 $aws/things/thingName/shadow/name/shadowName/delete/accepted tema y un documento Documento de estado de la respuesta /aceptado paralelo 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 publique un mensaje con el $aws/things/thingName/shadow/name/shadowName/delete/rejected tema junto con un documento Documento de respuesta de error 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.

  2. Si la solicitud era válida, AWS IoT devuelve un código HTTP de respuesta correcta Documento de estado de la respuesta /aceptado y un documento Documento de estado de la respuesta /aceptado alternativo 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 an Documento de respuesta de error como cuerpo del mensaje de respuesta.