Temas MQTT de sombra de dispositivo - AWS IoT Core
/get/get/accepted/get/rejected/update/update/delta/update/accepted/update/documents/update/rejected/delete/delete/accepted/delete/rejected

Temas MQTT de sombra de dispositivo

El servicio Device Shadow utiliza temas MQTT reservados para permitir a los dispositivos y las aplicaciones obtener, actualizar o eliminar la información de estado de un dispositivo (sombra).

La publicación y suscripción de temas de sombra requiere una autorización basada en temas. AWS IoT se reserva el derecho a añadir nuevos temas a la estructura de temas existente. Por este motivo, le recomendamos que evite las suscripciones de tipo comodín a los temas de sombra. Por ejemplo, evite suscribirse a filtros de temas como $aws/things/thingName/shadow/#, ya que el número de temas que coinciden con este filtro de temas puede aumentar a medida que AWS IoT incorpora nuevos temas de sombra. Para consultar ejemplos de mensajes publicados en estos temas vaya a Interacción con sombras.

Las sombras pueden ser con nombre o sin nombre (clásico). Los temas utilizados por cada uno solo difieren en el prefijo del tema. Esta tabla muestra el prefijo de tema utilizado por cada tipo de sombra.

Valor ShadowTopicPrefix Tipo de sombra
$aws/things/thingName/shadow Sombra sin nombre (clásica)
$aws/things/thingName/shadow/name/shadowName Sombra con nombre

Para crear un tema completo, seleccione el ShadowTopicPrefix para el tipo de sombra al que desea hacer referencia, reemplace thingName y shadowName si procede, por sus valores correspondientes y, a continuación, anéxelo al código auxiliar del tema como se muestra en las secciones siguientes.

A continuación se muestran los temas MQTT utilizados para interactuar con las sombras.

/get

Publique un mensaje vacío en este tema para obtener la sombra de objeto:

ShadowTopicPrefix/get

AWS IoT responde publicando en /get/accepted o en /get/rejected.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Publish"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get"
      ]
    }
  ]
}

/get/accepted

AWS IoT publica un documento de sombra de respuesta en este tema cuando devuelve la sombra del dispositivo:

ShadowTopicPrefix/get/accepted

Para obtener más información, consulte Documentos de estado de la respuesta.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/accepted"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get/accepted"
      ]
    }
  ]
}

/get/rejected

AWS IoT publica un documento de respuesta de error en este tema cuando no puede devolver la sombra del dispositivo:

ShadowTopicPrefix/get/rejected

Para obtener más información, consulte Documento de respuesta de error.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/rejected"
      ]
    },
    {
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get/rejected"
      ]
    }
  ]
}

/update

Publique un documento de estado de solicitud en este tema para actualizar la sombra del dispositivo:

ShadowTopicPrefix/update

El cuerpo del mensaje contiene un documento de estado de solicitud parcial.

Un cliente que intente actualizar el estado de un dispositivo enviaría un documento de estado de solicitud JSON con la propiedad desired como esta:

{
  "state": {
    "desired": {
      "color": "red",
      "power": "on"
    }
  }
}

Un dispositivo que actualice su sombra enviaría un documento de estado de solicitud JSON con la propiedad reported, como esta:

{
  "state": {
    "reported": {
      "color": "red",
      "power": "on"
    }
  }
}

AWS IoT responde publicando en /update/accepted o en /update/rejected.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Publish"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update"
      ]
    }
  ]
}

/update/delta

AWS IoT publica un documento de estado de respuesta en este tema cuando acepta un cambio de la sombra del dispositivo y el documento de estado de solicitud contiene valores distintos para los estados desired y reported:

ShadowTopicPrefix/update/delta

El búfer del mensaje contiene un Documento de estado de la respuesta /delta.

Detalles del cuerpo del mensaje

  • Un mensaje publicado en update/delta incluye únicamente los atributos deseados que difieren entre las secciones desired y reported. Contiene todos estos atributos, independientemente de si se encuentran en el mensaje de actualización actual o si ya estaban almacenados en AWS IoT. No se incluyen los atributos que no difieren entre las secciones desired y reported.

  • Si un atributo se encuentra en la sección reported, pero no tiene equivalente en la sección desired, no se incluye.

  • Si un atributo se encuentra en la sección desired, pero no tiene equivalente en la sección reported, se incluye.

  • Si se elimina un atributo de la sección reported, pero sigue existiendo en la sección desired, se incluye.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/delta"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/delta"
      ]
    }
  ]
}

/update/accepted

AWS IoT publica un documento de estado de respuesta en este tema cuando acepta un cambio de la sombra del dispositivo:

ShadowTopicPrefix/update/accepted

El búfer del mensaje contiene un Documento de estado de la respuesta /aceptado.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/accepted"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/accepted"
      ]
    }
  ]
}

/update/documents

AWS IoT publica un documento de estado en este tema siempre que se realiza una actualización correcta de la sombra:

ShadowTopicPrefix/update/documents

El cuerpo del mensaje contiene un Documento de estado de respuesta /documentos.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/documents"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/documents"
      ]
    }
  ]
}

/update/rejected

AWS IoT publica un documento de respuesta de error en este tema cuando rechaza un cambio de la sombra del dispositivo:

ShadowTopicPrefix/update/rejected

El cuerpo del mensaje contiene un Documento de respuesta de error.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/rejected"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update/rejected"
      ]
    }
  ]
}

/delete

Para eliminar la sombra de un dispositivo, publique un mensaje vacío para eliminar el tema:

ShadowTopicPrefix/delete

El contenido del mensaje no se tiene en cuenta.

Tenga en cuenta que, al eliminar una sombra, no se restablece su número de versión a 0.

AWS IoT responde publicando en /delete/accepted o en /delete/rejected.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Publish"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/delete"
      ]
    }
  ]
}

/delete/accepted

AWS IoT publica un mensaje en este tema cuando se elimina la sombra de un dispositivo:

ShadowTopicPrefix/delete/accepted

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/delete/accepted"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/delete/accepted"
      ]
    }
  ]
}

/delete/rejected

AWS IoT publica un documento de respuesta de error en este tema cuando no puede eliminar la sombra del dispositivo:

ShadowTopicPrefix/delete/rejected

El cuerpo del mensaje contiene un Documento de respuesta de error.

Ejemplo de política de

A continuación, mostramos un ejemplo de la política requerida:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/delete/rejected"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/delete/rejected"
      ]
    }
  ]
}