Usar sombras em aplicativos e serviços

Esta seção descreve como um aplicativo ou serviço interage com o serviço AWS IoT Device Shadow. Este exemplo pressupõe que o aplicativo ou serviço esteja interagindo apenas com a sombra e, por meio da sombra, com o dispositivo. Este exemplo não inclui nenhuma ação de gerenciamento, como criação ou exclusão de sombras.

Este exemplo usa a API REST do serviço AWS IoT Device Shadow para interagir com sombras. Ao contrário do exemplo usado no Usar sombras em dispositivos, que usa um modelo de comunicação de publicação/assinatura, este exemplo usa o modelo de comunicação de solicitação/resposta da API REST. Isso significa que o aplicativo ou serviço deve fazer uma solicitação antes de receber uma resposta de AWS IoT. Uma desvantagem deste modelo, no entanto, é que ele não é compatível com notificações. Se seu aplicativo ou serviço exigir notificações oportunas de alterações de estado do dispositivo, considere os protocolos MQTT ou MQTT sobre WSS, que são compatíveis com o modelo de comunicação de publicação/assinatura, conforme descrito em Usar sombras em dispositivos.

Importante

Verifique se o uso de sombras por seu aplicativo ou serviço é consistente e compatível com as implementações correspondentes em seus dispositivos. Considere, por exemplo, como as sombras são criadas, atualizadas e excluídas e como as atualizações são processadas no dispositivo e nos aplicativos ou serviços que acessam a sombra. Seu design deve especificar claramente como o estado do dispositivo é atualizado e relatado, e como seus aplicativos e serviços interagem com o dispositivo e suas sombras.

O URL da API REST para sombras nomeadas é:

https://endpoint/things/thingName/shadow?name=shadowName

e para uma sombra sem nome:

https://endpoint/things/thingName/shadow

em que:

endpoint

O endpoint retornado pelo comando da CLI:

aws iot describe-endpoint --endpoint-type IOT:Data-ATS

thingName

O nome do objeto do objeto ao qual a sombra pertence

shadowName

O nome da sombra nomeada. Esse parâmetro não é usado com sombras sem nome.

Inicializando o aplicativo ou serviço em conexão com AWS IoT

Quando o aplicativo se conecta pela primeira vez AWS IoT, ele deve enviar uma solicitação HTTP GET aos URLs das sombras que usa para obter o estado atual das sombras que está usando. Isso permite que ele sincronize o aplicativo ou serviço com a sombra.

O estado de processamento muda enquanto o aplicativo ou serviço está conectado ao AWS IoT

Enquanto o aplicativo ou serviço está conectado AWS IoT, ele pode consultar o estado atual periodicamente enviando uma solicitação HTTP GET nos URLs das sombras que usa.

Quando um usuário final interage com o aplicativo ou serviço para alterar o estado do dispositivo, o aplicativo ou serviço pode enviar uma solicitação HTTP POST aos URLs das sombras que usa para atualizar o estado desired da sombra. Essa solicitação retorna a alteração que foi aceita, mas talvez você precise pesquisar a sombra fazendo solicitações HTTP GET até que o dispositivo atualize a sombra com seu novo estado.

Detectar se um dispositivo está conectado

Para determinar se um dispositivo está conectado no momento, inclua uma propriedade connected no documento de sombra e use uma mensagem MQTT Last Will and Testament (LWT) para definir a propriedade connected como false se um dispositivo for desconectado devido a um erro.

nota

As mensagens MQTT LWT enviadas para tópicos AWS IoT reservados (tópicos que começam com $) são ignoradas pelo serviço AWS IoT Device Shadow. No entanto, eles são processados por clientes inscritos e pelo mecanismo de AWS IoT regras, portanto, você precisará criar uma mensagem LWT que seja enviada para um tópico não reservado e uma regra que republique a mensagem MQTT LWT como uma mensagem de atualização paralela para o tópico de atualização reservado da sombra,. ShadowTopicPrefix/update

Como enviar ao serviço Sombra do Dispositivo uma mensagem LWT

1. Crie uma regra que republica a mensagem MQTT LWT no tópico reservado. O exemplo a seguir é uma regra que escuta mensagens sobre o tópico my/things/myLightBulb/update e republica-a no $aws/things/myLightBulb/shadow/update.

   {
       "rule": {
       "ruleDisabled": false,
       "sql": "SELECT * FROM 'my/things/myLightBulb/update'",
       "description": "Turn my/things/ into $aws/things/",
       "actions": [
           {
           "republish": {
               "topic": "$$aws/things/myLightBulb/shadow/update",
               "roleArn": "arn:aws:iam:123456789012:role/aws_iot_republish"
               }
           }
        ]
      }
   }

2. Quando o dispositivo se conecta AWS IoT, ele registra uma mensagem LWT em um tópico não reservado para que a regra de republicação reconheça. Neste exemplo, esse tópico é my/things/myLightBulb/update e define a propriedade conectada como false.

   {
       "state": {        
           "reported": {
               "connected":"false"
           }
       }
   }

3. Após a conexão, o dispositivo publica uma mensagem em seu tópico de atualização de sombra, $aws/things/myLightBulb/shadow/update, para relatar seu estado atual, o que inclui a configuração de sua propriedade connected como true.

   {
        "state": {        
           "reported": {
               "connected":"true"
           }
       }
   }

4. Antes de desconectar-se corretamente, o dispositivo publica uma mensagem em seu tópico de atualização de sombra, $aws/things/myLightBulb/shadow/update, para relatar seu estado mais recente, que inclui a configuração de sua propriedade connected como false.

   {
       "state": {        
           "reported": {
               "connected":"false"
           }
       }
   }

5. Se o dispositivo se desconectar devido a um erro, o agente de mensagens publicará a AWS IoT mensagem LWT do dispositivo em nome do dispositivo. A regra de republicação detecta essa mensagem e publica a mensagem de atualização de sombra para atualizar a connected propriedade da sombra do dispositivo.