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 MQTT suscriptores 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 soportes MQTTy REST API más HTTPS protocolos para interactuar con las sombras. AWS IoT proporciona un conjunto de temas de solicitud y respuesta reservados para las acciones de MQTT publicación y suscripción. 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 MQTTTemas sobre Device Shadow y Device Shadow REST API.

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

Tu aplicación o servicio puede actualizar el estado de una sombra utilizando el /update tema UpdateThingShadow API o publicándolo en él. 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 MQTT protocolo

  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 estos MQTT temas:

    • $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 de forma oculta mediante el API

  1. El cliente lo llama UpdateThingShadow API con un documento de Documento de estado de la solicitud estado 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 MQTT mensaje $aws/things/thingName/shadow/name/shadowName/update/delta sobre el tema 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 de HTTP error an 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 informa de su estado actual a la sombra mediante el MQTT protocolo

  1. El dispositivo debe suscribirse a estos MQTT temas 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, publicará un mensaje $aws/things/thingName/shadow/name/shadowName/update/accepted sobre los temas junto con un documento Documento de estado de la respuesta /aceptado alternativo.

  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 informa de su estado actual a la sombra mediante el API

  1. El dispositivo llama UpdateThingShadow API con un documento de Documento de estado de la solicitud estado 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 alternativo como cuerpo del mensaje de respuesta.

    AWS IoT también publicará un MQTT mensaje $aws/things/thingName/shadow/name/shadowName/update/delta sobre el tema 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 de HTTP error an 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. Al proporcionar una versión con una solicitud de actualización, el servicio rechaza la solicitud con un código HTTP 409 de respuesta al conflicto si la versión actual del documento de estado no coincide con la versión proporcionada. El código de respuesta a conflictos también puede aparecer en cualquier código API que se modifiqueThingShadow, por ejemploDeleteThingShadow.

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 paralelo utilizando el tema GetThingShadow API o suscribiéndose al tema y publicándolo. /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 paralelo mediante el protocolo MQTT

  1. El dispositivo o el cliente deben suscribirse a estos MQTT temas 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 es correcta, 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 paralelo mediante un REST API

  1. El dispositivo o el cliente lo llaman GetThingShadow API con el cuerpo del 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 HTTP error 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, usa DeleteThingShadow API o publica en el /delete tema.

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 MQTT protocolo

  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 el cliente se suscriben a estos MQTT temas:

    • $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 $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 el REST API

  1. El dispositivo o el cliente llama al UpdateThingShadow API con un Documento de estado de la solicitud que asigna null valores a las propiedades de la sombra que se va a 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 paralelo como cuerpo del mensaje de respuesta.

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

  1. El dispositivo o el cliente se suscriben a estos MQTT temas:

    • $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 el REST API

  1. El dispositivo o el cliente llama DeleteThingShadow API con el búfer de mensajes vacío.

  2. Si la solicitud era válida, AWS IoT devuelve un HTTP código de respuesta correcta Documento de estado de la respuesta /aceptado 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
}

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