MQTTTópicos do Device Shadow - AWS IoT Core
/get/get/accepted/get/rejected/update/update/delta/update/accepted/update/documents/update/rejected/delete/delete/accepted/delete/rejected

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

MQTTTópicos do Device Shadow

O serviço Device Shadow usa MQTT tópicos reservados para permitir que dispositivos e aplicativos obtenham, atualizem ou excluam as informações de estado de um dispositivo (sombra).

Para publicar e inscrever-se em tópicos de shadow, é necessário ter autorização baseada em tópicos. A AWS IoT reserva-se o direito de adicionar novos tópicos à estrutura de tópicos existente. Por esse motivo, recomendamos que você evite assinaturas curinga para os tópicos de shadow. Por exemplo, evite assinar filtros de tópicos, $aws/things/thingName/shadow/# pois o número de tópicos que correspondem a esse filtro de tópicos pode aumentar à medida que novos tópicos paralelos AWS IoT são introduzidos. Para ver exemplos de mensagens publicadas nesses tópicos, consulte Interagir com sombras.

As sombras podem ser nomeadas ou sem nome (clássica). Os tópicos usados por cada uma diferem apenas no prefixo do tópico. Esta tabela mostra o prefixo do tópico usado em cada tipo de sombra.

ShadowTopicPrefix valor Tipo de sombra
$aws/things/thingName/shadow Sombra sem nome (clássica)
$aws/things/thingName/shadow/name/shadowName Sombra nomeada

Para criar um tópico completo, selecione o ShadowTopicPrefix do tipo de sombra ao qual você quer fazer referência, substitua thingName e shadowName, se aplicável, por seus valores correspondentes e acrescente isso com o stub de tópico, conforme mostrado nas seguintes seções.

A seguir estão os MQTT tópicos usados para interagir com sombras.

/get

Publique uma mensagem vazia nesse tópico para obter a shadow de dispositivo:

ShadowTopicPrefix/get

AWS IoT responde publicando em um /get/accepted ou/get/rejected.

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 um documento paralelo de resposta para este tópico ao retornar a sombra do dispositivo:

ShadowTopicPrefix/get/accepted

Para obter mais informações, consulte Documentos de estado da resposta.

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 um documento de resposta de erro para este tópico quando não consegue retornar a sombra do dispositivo:

ShadowTopicPrefix/get/rejected

Para obter mais informações, consulte Documento de resposta de erro.

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 um documento de estado da solicitação nesse tópico para atualizar a shadow de dispositivo:

ShadowTopicPrefix/update

O corpo da mensagem contém um documento de estado de solicitação parcial.

Um cliente que tentasse atualizar o estado de um dispositivo enviaria um documento de estado de JSON solicitação com a desired propriedade, como esta:

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

Um dispositivo atualizando sua sombra enviaria um documento de estado de JSON solicitação com a reported propriedade, como este:

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

AWS IoT responde publicando em um /update/accepted ou/update/rejected.

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 um documento de estado de resposta para esse tópico quando aceita uma alteração na sombra do dispositivo, e o documento de estado da solicitação contém valores diferentes para desired e reported estados:

ShadowTopicPrefix/update/delta

O buffer de mensagens contém um Documento de estado da resposta /delta.

Detalhes do corpo da mensagem

  • Uma mensagem publicada em update/delta inclui apenas os atributos desejados que diferem entre as seções desired e reported. Ela contém todos esses atributos, independentemente de esses atributos estarem contidos na mensagem de atualização atual ou de já estarem armazenados na AWS IoT. Os atributos que não diferem entre as seções desired e reported não são incluídos.

  • Se um atributo estiver na seção reported, mas não tiver equivalente na seção desired, ele não será incluído.

  • Se um atributo estiver na seção desired, mas não tiver equivalente na seção reported, ele será incluído.

  • Se um atributo for excluído da seção reported, mas ainda existir na seção desired, ele será incluído.

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 um documento de estado de resposta a esse tópico quando aceita uma alteração na sombra do dispositivo:

ShadowTopicPrefix/update/accepted

O buffer de mensagens contém um Documento de estado da resposta /accepted.

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 um documento de estado neste tópico sempre que uma atualização na sombra for executada com sucesso:

ShadowTopicPrefix/update/documents

O corpo da mensagem contém um Documento de estado da resposta /documents.

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 um documento de resposta de erro para esse tópico quando rejeita uma alteração na sombra do dispositivo:

ShadowTopicPrefix/update/rejected

O corpo da mensagem contém um Documento de resposta de erro.

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 excluir uma shadow de dispositivo, publique uma mensagem vazia no tópico de exclusão:

ShadowTopicPrefix/delete

O conteúdo da mensagem é ignorado.

Observe que a exclusão de uma sombra não redefine seu número da versão para 0.

AWS IoT responde publicando em um /delete/accepted ou/delete/rejected.

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 uma mensagem neste tópico quando a sombra de um dispositivo é excluída:

ShadowTopicPrefix/delete/accepted

Exemplo de política

Veja a seguir um exemplo da política necessária:

{
  "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 um documento de resposta de erro para este tópico quando não consegue excluir a sombra do dispositivo:

ShadowTopicPrefix/delete/rejected

O corpo da mensagem contém um Documento de resposta de erro.

Exemplo de política

Veja a seguir um exemplo da política necessária:

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