Suporte ao protocolo Solicitar e declarar o estado Atualizar uma shadow Recuperar um documento de shadow Excluir dados de sombra

Interagir com sombras

Este tópico descreve as mensagens associadas a cada um dos três métodos que o AWS IoT fornece para trabalhar com sombras. Esses métodos incluem o seguinte:

UPDATE

Cria uma sombra, se ela não existir, ou atualiza o conteúdo de uma sombra existente com as informações de estado fornecidas no corpo da mensagem. O AWS IoT registra um carimbo de data/hora com cada atualização para indicar quando o estado foi atualizado pela última vez. Quando o estado da sombra muda, AWS IoT envia /delta mensagens para todos os MQTT assinantes com a diferença entre os reported estados desired e os. Os dispositivos ou aplicativos que recebem uma mensagem /delta podem executar ações com base na diferença. Por exemplo, um dispositivo pode atualizar seu estado para o estado desejado, ou um aplicativo pode atualizar sua interface do usuário (UI) para mostrar a alteração no estado do dispositivo.

GET

Recupera um documento de sombra atual que contém o estado completo da sombra, incluindo os metadados.

DELETE

Exclui a sombra do dispositivo e o seu conteúdo.

Você não pode restaurar um documento de sombra do dispositivo excluído, mas pode criar um novo documento de sombra do dispositivo com o nome de um documento de sombra do dispositivo excluído. Se você criar um documento de sombra do dispositivo com o mesmo nome daquele que foi excluído nas últimas 48 horas, o número da versão do novo documento de sombra do dispositivo seguirá o do excluído. Se um documento de sombra do dispositivo tiver sido excluído por mais de 48 horas, o número da versão de um novo documento de sombra do dispositivo com o mesmo nome será 0.

Suporte ao protocolo

AWS IoT suportes MQTTe REST API mais HTTPS protocolos para interagir com sombras. AWS IoT fornece um conjunto de tópicos reservados de solicitação e resposta para ações de MQTT publicação e assinatura. Dispositivos e aplicativos devem se inscrever nos tópicos de resposta antes de publicar um tópico de solicitação para obter informações sobre como a solicitação AWS IoT foi tratada. Para ter mais informações, consulte MQTTTópicos do Device Shadow e Device Shadow REST API.

Solicitar e declarar o estado

Ao projetar sua solução de IoT usando AWS IoT sombras, você deve determinar os aplicativos ou dispositivos que solicitarão alterações e aqueles que as implementarão. Normalmente, um dispositivo implementa e relata alterações na sombra e os aplicativos e os serviços respondem e solicitam alterações na sombra. Sua solução pode ser diferente, mas os exemplos neste tópico pressupõem que o aplicativo cliente ou o serviço solicita alterações na sombra e o dispositivo executa as alterações e relata-as de volta à sombra.

Atualizar uma shadow

Seu aplicativo ou serviço pode atualizar o estado de uma sombra usando UpdateThingShadow API ou publicando no /update tópico. As atualizações afetam apenas os campos especificados na solicitação.

Atualizar uma sombra quando um cliente solicita uma alteração de estado

Quando um cliente solicita uma mudança de estado em uma sombra usando o MQTT protocolo

O cliente deve ter um documento da sombra atual para que ele possa identificar as propriedades a serem alteradas. Consulte a ação /get para saber como obter o documento de sombra atual.
O cliente se inscreve nos seguintes MQTT tópicos:
- $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
O cliente publica um tópico de solicitação $aws/things/thingName/shadow/name/shadowName/update com um documento de estado que contém o estado desejado da sombra. Somente as propriedades a serem alteradas precisam ser incluídas no documento. Este é um exemplo de um documento com o estado desejado.
```
{
  "state": {
    "desired": {
      "color": {
        "r": 10
      },
      "engine": "ON"
    }
  }
}
```
Se a solicitação de atualização for válida, AWS IoT atualiza o estado desejado na sombra e publica mensagens sobre estes tópicos:
- $aws/things/thingName/shadow/name/shadowName/update/accepted
- $aws/things/thingName/shadow/name/shadowName/update/delta
A mensagem /update/accepted contém um documento de sombra Documento de estado da resposta /accepted, e a mensagem /update/delta contém um documento de sombra Documento de estado da resposta /delta.
Se a solicitação de atualização não for válida, AWS IoT publica uma mensagem com o $aws/things/thingName/shadow/name/shadowName/update/rejected tópico com um documento Documento de resposta de erro paralelo que descreve o erro.

Quando um cliente solicita uma mudança de estado em uma sombra usando o API

O cliente chama o UpdateThingShadow API com um documento de Documento de estado de solicitação estado como corpo da mensagem.
Se a solicitação for válida, AWS IoT retornará um código de resposta HTTP bem-sucedida e um documento Documento de estado da resposta /accepted paralelo como corpo da mensagem de resposta.

AWS IoT também publicará uma MQTT mensagem no $aws/things/thingName/shadow/name/shadowName/update/delta tópico com um documento Documento de estado da resposta /delta paralelo para todos os dispositivos ou clientes que o assinarem.
Se a solicitação não for válida, AWS IoT retornará um código HTTP de resposta de erro e Documento de resposta de erro como corpo da mensagem de resposta.

Quando o dispositivo recebe o estado /desired no tópico /update/delta, ele faz as alterações desejadas no dispositivo. Depois, ele envia uma mensagem ao tópico /update para relatar seu estado atual para a sombra.

Atualizar uma sombra quando um dispositivo relata seu estado atual

Quando um dispositivo relata seu estado atual à sombra usando o MQTT protocolo

O dispositivo deve se inscrever nesses MQTT tópicos antes de atualizar a 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
O dispositivo relata seu estado atual publicando uma mensagem no tópico $aws/things/thingName/shadow/name/shadowName/update que relata o estado atual, como neste exemplo.
```
{
    "state": {
        "reported" : {
            "color" : { "r" : 10 },
            "engine" : "ON"
        }
    }
}
```
Se AWS IoT aceitar a atualização, ele publicará uma mensagem nos $aws/things/thingName/shadow/name/shadowName/update/accepted tópicos com um documento Documento de estado da resposta /accepted paralelo.
Se a solicitação de atualização não for válida, AWS IoT publica uma mensagem com o $aws/things/thingName/shadow/name/shadowName/update/rejected tópico com um documento Documento de resposta de erro paralelo que descreve o erro.

Quando um dispositivo relata seu estado atual à sombra usando o API

O dispositivo chama o UpdateThingShadow API com um documento de Documento de estado de solicitação estado como corpo da mensagem.
Se a solicitação for válida, AWS IoT atualiza a sombra e retorna um código de resposta HTTP bem-sucedida com um Documento de estado da resposta /accepted documento-sombra como corpo da mensagem de resposta.

AWS IoT também publicará uma MQTT mensagem no $aws/things/thingName/shadow/name/shadowName/update/delta tópico com um documento Documento de estado da resposta /delta paralelo para todos os dispositivos ou clientes que o assinarem.
Se a solicitação não for válida, AWS IoT retornará um código HTTP de resposta de erro e Documento de resposta de erro como corpo da mensagem de resposta.

Bloqueio otimista

Você pode usar a versão do documento de estado para garantir que está atualizando a versão mais recente de um documento de sombra do dispositivo. Quando você fornece uma versão com uma solicitação de atualização, o serviço rejeita a solicitação com um código de resposta de conflito HTTP 409 se a versão atual do documento de estado não corresponder à versão fornecida. O código de resposta ao conflito também pode ocorrer em qualquer um API que seja modificadoThingShadow, inclusiveDeleteThingShadow.

Por exemplo:

Documento inicial:


{
  "state": {
    "desired": {
      "colors": [
        "RED",
        "GREEN",
        "BLUE"
      ]
    }
  },
  "version": 10
}

Atualização: (versão não corresponde, a solicitação será rejeitada)


{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 9
}

Resultado:


{
  "code": 409,
  "message": "Version conflict",
  "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}

Atualização: (a versão corresponde; a solicitação será aceita)


{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 10
}

Estado final:


{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 11
}

Recuperar um documento de shadow

Você pode recuperar um documento paralelo usando o GetThingShadow API ou assinando e publicando no /get tópico. Isso recupera um documento de sombra completo, incluindo qualquer delta entre os estados reported e desired. O procedimento para esta tarefa é o mesmo para um dispositivo ou para um cliente que faz a solicitação.

Para recuperar um documento paralelo usando o protocolo MQTT

O dispositivo ou cliente deve se inscrever nesses MQTT tópicos antes de atualizar a sombra:
- $aws/things/thingName/shadow/name/shadowName/get/accepted
- $aws/things/thingName/shadow/name/shadowName/get/rejected
O dispositivo ou o cliente publica uma mensagem no tópico $aws/things/thingName/shadow/name/shadowName/get com um corpo de mensagem vazio.
Se a solicitação for bem-sucedida, AWS IoT publica uma mensagem no $aws/things/thingName/shadow/name/shadowName/get/accepted tópico com um Documento de estado da resposta /accepted no corpo da mensagem.
Se a solicitação não for válida, AWS IoT publica uma mensagem no $aws/things/thingName/shadow/name/shadowName/get/rejected tópico com um Documento de resposta de erro no corpo da mensagem.

Para recuperar um documento de sombra usando um REST API

O dispositivo ou cliente chama o GetThingShadow API com um corpo de mensagem vazio.
Se a solicitação for válida, AWS IoT retornará um código de resposta HTTP bem-sucedida com um documento Documento de estado da resposta /accepted paralelo como corpo da mensagem de resposta.
Se a solicitação não for válida, AWS IoT retornará um código HTTP de resposta de erro e Documento de resposta de erro como corpo da mensagem de resposta.

Excluir dados de sombra

Existem duas maneiras de excluir dados de sombra: você pode excluir propriedades específicas no documento de sombra e excluir a sombra completamente.

Para excluir propriedades específicas de uma sombra, atualize a sombra. No entanto, defina o valor das propriedades que você deseja excluir como null. Os campos com um valor de null são removidos do documento de sombra.
Para excluir a sombra inteira, use DeleteThingShadow API ou publique no /delete tópico.

nota

A exclusão de uma sombra não redefine seu número de versão para zero de uma só vez. Ele será redefinido para zero após 48 horas.

Excluir uma propriedade de um documento de sombra

Para excluir uma propriedade de uma sombra usando o MQTT protocolo

O dispositivo ou o cliente deve ter um documento de sombra atual para que possa identificar as propriedades a serem alteradas. Consulte Recuperar um documento de shadow para obter informações sobre como obter o documento de sombra atual.
O dispositivo ou cliente se inscreve nos seguintes MQTT tópicos:
- $aws/things/thingName/shadow/name/shadowName/update/accepted
- $aws/things/thingName/shadow/name/shadowName/update/rejected
O dispositivo ou o cliente publica um tópico de solicitação $aws/things/thingName/shadow/name/shadowName/update com um documento de estado que atribui valores null às propriedades da sombra a ser excluída. Somente as propriedades a serem alteradas precisam ser incluídas no documento. Este é um exemplo de um documento que exclui a propriedade engine.
```
{
  "state": {
    "desired": {
      "engine": null
    }
  }
}
```
Se a solicitação de atualização for válida, AWS IoT excluirá as propriedades especificadas na sombra e publicará uma mensagem com o $aws/things/thingName/shadow/name/shadowName/update/accepted tópico com um documento Documento de estado da resposta /accepted paralelo no corpo da mensagem.
Se a solicitação de atualização não for válida, AWS IoT publica uma mensagem com o $aws/things/thingName/shadow/name/shadowName/update/rejected tópico com um documento Documento de resposta de erro paralelo que descreve o erro.

Para excluir uma propriedade de uma sombra usando o REST API

O dispositivo ou cliente chama o UpdateThingShadow API com um Documento de estado de solicitação que atribui null valores às propriedades da sombra a serem excluídas. Inclua apenas as propriedades que você deseja excluir no documento. Este é um exemplo de um documento que exclui a propriedade engine.
```
{
  "state": {
    "desired": {
      "engine": null
    }
  }
}
```
Se a solicitação for válida, AWS IoT retornará um código de resposta HTTP bem-sucedida e um documento Documento de estado da resposta /accepted paralelo como corpo da mensagem de resposta.
Se a solicitação não for válida, AWS IoT retornará um código HTTP de resposta de erro e Documento de resposta de erro como corpo da mensagem de resposta.

Excluir uma shadow

Veja a seguir algumas considerações ao excluir a sombra de um dispositivo.

Definir o estado da sombra do dispositivo como null não exclui a sombra. A versão da sombra será incrementada na próxima atualização.
A exclusão de uma sobra de dispositivo não exclui o objeto. A exclusão de um objeto não exclui a sombra do dispositivo correspondente.
A exclusão de uma sombra não redefine seu número de versão para zero de uma só vez. Ele será redefinido para zero após 48 horas.

Para excluir uma sombra usando o MQTT protocolo

O dispositivo ou cliente se inscreve nos seguintes MQTT tópicos:
- $aws/things/thingName/shadow/name/shadowName/delete/accepted
- $aws/things/thingName/shadow/name/shadowName/delete/rejected
O dispositivo ou o cliente publica um $aws/things/thingName/shadow/name/shadowName/delete com um buffer de mensagens vazio.
Se a solicitação de exclusão for válida, AWS IoT excluirá a sombra e publicará uma mensagem com o $aws/things/thingName/shadow/name/shadowName/delete/accepted tópico e um Documento de estado da resposta /accepted documento-sombra abreviado no corpo da mensagem. Este é um exemplo de mensagem de exclusão aceita:
```
{
  "version": 4,
  "timestamp": 1591057529
}
```
Se a solicitação de atualização não for válida, AWS IoT publica uma mensagem com o $aws/things/thingName/shadow/name/shadowName/delete/rejected tópico com um documento Documento de resposta de erro paralelo que descreve o erro.

Para excluir uma sombra usando o REST API

O dispositivo ou cliente chama o DeleteThingShadow API com um buffer de mensagens vazio.
Se a solicitação for válida, AWS IoT retornará um código de resposta HTTP bem-sucedida Documento de estado da resposta /accepted e um Documento de estado da resposta /accepted documento-sombra abreviado no corpo da mensagem. Este é um exemplo de mensagem de exclusão aceita:
```
{
  "version": 4,
  "timestamp": 1591057529
}
```
Se a solicitação não for válida, AWS IoT retornará um código HTTP de resposta de erro e Documento de resposta de erro como corpo da mensagem de resposta.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Simulando comunicações de serviço Sombra do Dispositivo

Device Shadow REST API