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á. # Tutorial: interagindo com a Sombra do Dispositivo usando o aplicativo de amostra e o cliente de teste MQTT Para interagir com o aplicativo de amostra `shadow.py`, insira um valor no terminal para o valor `desired`. Por exemplo, você pode especificar cores que se assemelhem aos semáforos e AWS IoT respondam à solicitação e atualizem os valores relatados. **Neste tutorial, você aprenderá:** + Usar o aplicativo de amostra `shadow.py` para especificar os estados desejados e atualizar o estado atual da sombra. + Editar o documento Shadow para observar os eventos delta e como o aplicativo de amostra `shadow.py` responde a eles. + Utilizar o cliente de teste MQTT para assinar tópicos de sombra e observar atualizações ao executar o programa de amostra. **Antes de executar este tutorial, você precisa:** Configure seu Conta da AWS, configure seu dispositivo Raspberry Pi e crie uma AWS IoT coisa e uma política. Você também deve ter instalado o software necessário, o Device SDK, os arquivos de certificado e executado o programa de amostra no terminal. Para obter mais informações, consulte os tutoriais anteriores [Tutorial: preparando seu Raspberry Pi para executar o aplicativo de sombra](create-resources-shadow.md) e [Etapa 1: execute o aplicativo de exemplo shadow.py](lightbulb-shadow-application.md#run-sample-application-shadows). Você deve concluir esses tutoriais, caso ainda não o tenha feito. **Topics** + [Etapa 1: atualizar os valores desejados e relatados usando o aplicativo de amostra `shadow.py`](#update-desired-shadow-sample) + [Etapa 2: exibir mensagens do aplicativo de amostra `shadow.py` no cliente de teste MQTT](#shadow-sample-view-msg) + [Etapa 3: solucionar problemas com as interações da Sombra do Dispositivo](#shadow-observe-messages-troubleshoot) + [Etapa 4: revisar os resultados e as próximas etapas](#sample-shadow-review) Este tutorial leva cerca de 45 minutos para ser concluído. ## Etapa 1: atualizar os valores desejados e relatados usando o aplicativo de amostra `shadow.py` No tutorial anterior[Etapa 1: execute o aplicativo de exemplo shadow.py](lightbulb-shadow-application.md#run-sample-application-shadows), você aprendeu a observar uma mensagem publicada no documento Shadow no AWS IoT console ao inserir o valor desejado, conforme descrito na seção[Tutorial: instalando o Device SDK e executando o aplicativo de amostra para Sombras do Dispositivo](lightbulb-shadow-application.md). No exemplo anterior, definimos a cor desejada como `yellow`. Depois de inserir cada valor, o terminal solicita que você insira outro valor `desired`. Se você inserir novamente o mesmo valor (`yellow`), o aplicativo reconhecerá isso e solicitará que você insira um novo valor `desired`. ``` Enter desired value: yellow Local value is already 'yellow'. Enter desired value: ``` Agora, digamos que você insira a cor`green`. AWS IoT responde à solicitação e atualiza o `reported` valor para`green`. É assim que a atualização acontece quando o estado `desired` é diferente do estado `reported`, causando um delta. **Como o aplicativo de amostra `shadow.py` simula as interações da Sombra do Dispositivo:** 1. Insira um valor `desired` (digamos `yellow`) no terminal para publicar o estado desejado. 1. Como o estado `desired` é diferente do estado `reported` (digamos, a cor `green`), ocorre um delta e o aplicativo que está inscrito no delta recebe essa mensagem. 1. O aplicativo responde à mensagem e atualiza seu estado para o valor `desired`, `yellow`. 1. O aplicativo então publica uma mensagem de atualização com o novo valor relatado do estado do dispositivo, `yellow`. A seguir, são mostradas as mensagens exibidas no terminal que mostram como a solicitação de atualização é publicada. ``` Enter desired value: green Changed local shadow value to 'green'. Updating reported shadow value to 'green'... Update request published. Finished updating reported shadow value to 'green'. ``` No AWS IoT console, o documento Shadow reflete o valor atualizado `green` para os `desired` campos `reported` e, e o número da versão é incrementado em 1. Por exemplo, se o número da versão anterior foi exibido como 10, o número da versão atual será exibido como 11. **nota** A exclusão de uma sombra não redefine o número da versão para 0. Você verá que a versão sombra é incrementada em 1 quando você publica uma solicitação de atualização ou cria outra sombra com o mesmo nome. **Edite o documento Shadow para observar eventos delta** O aplicativo de amostra `shadow.py` também está inscrito em eventos `delta` e responde quando há uma alteração no valor `desired`. Por exemplo, você pode alterar o valor `desired` para a cor `red`. Para fazer isso, no AWS IoT console, edite o documento Shadow clicando em **Editar** e defina o `desired` valor como `red` no JSON, mantendo o `reported` valor como`green`. Antes de salvar as alterações, mantenha o terminal do Raspberry Pi aberto, pois você verá as mensagens exibidas no terminal quando a alteração ocorrer. ``` { "desired": { "welcome": "aws-iot", "color": "red" }, "reported": { "welcome": "aws-iot", "color": "green" } } ``` Depois de salvar o novo valor, o aplicativo de amostra `shadow.py` responde a essa alteração e exibe mensagens no terminal indicando o delta. Em seguida, você deverá ver as seguintes mensagens aparecerem abaixo da solicitação para inserir o valor `desired`. ``` Enter desired value: Received shadow delta event. Delta reports that desired value is 'red'. Changing local value... Changed local shadow value to 'red'. Updating reported shadow value to 'red'... Finished updating reported shadow value to 'red'. Enter desired value: Update request published. Finished updating reported shadow value to 'red'. ``` ## Etapa 2: exibir mensagens do aplicativo de amostra `shadow.py` no cliente de teste MQTT Você pode usar o **cliente de teste do MQTT** no **AWS IoT console** para monitorar as mensagens do MQTT que são passadas no seu Conta da AWS. Ao assinar tópicos MQTT reservados usados ​​pelo serviço Sombra do Dispositivo, você pode observar as mensagens recebidas pelos tópicos ao executar o aplicativo de amostra. Se você ainda não usou o cliente de teste MQTT, pode revisar [Exibir mensagens MQTT com o cliente AWS IoT MQTT](view-mqtt-messages.md). Isso ajudará você a aprender a usar o **cliente de teste MQTT** no **console do AWS IoT ** para visualizar as mensagens MQTT à medida que elas passam pelo agente de mensagens. 1. **Abra o cliente de teste MQTT** Abra o [cliente de teste do MQTT no console do AWS IoT](https://console.aws.amazon.com//iot/home#/test) em uma nova janela para que você possa observar as mensagens recebidas pelos tópicos do MQTT sem perder a configuração do seu cliente de teste do MQTT. O cliente de teste MQTT não retém assinaturas ou logs de mensagens se você deixá-lo para ir para outra página no console. Nesta seção do tutorial, você pode abrir o documento Shadow do seu AWS IoT produto e o cliente de teste MQTT em janelas separadas para observar mais facilmente a interação com o Device Shadows. 1. **Assine os tópicos Shadow reservados do MQTT** Você pode usar o cliente de teste MQTT para inserir os nomes dos tópicos reservados do MQTT da Sombra do Dispositivo e se inscrever neles para receber atualizações ao executar o aplicativo de amostra `shadow.py`. Para se inscrever nos tópicos: 1. No **cliente de teste MQTT** no **AWS IoT console**, escolha **Subscribe to a topic (Se inscreva em um tópico)**. 1. Na seção **Filtro de tópicos**, digite: **\$1aws/things/ /shadow/update/ \$1 *thingname***. Aqui, `thingname` é o nome do recurso de objeto que você criou anteriormente (por exemplo, `My_light_bulb`). 1. Mantenha os valores padrão para as configurações adicionais e escolha **Inscrever-se**. Ao usar o caractere curinga **\$1** na assinatura do tópico, você pode se inscrever em vários tópicos do MQTT ao mesmo tempo e observar todas as mensagens trocadas entre o dispositivo e sua sombra em uma única janela. Para obter mais informações sobre os caracteres curinga e seu uso, consulte[Tópicos do MQTT](topics.md). 1. **Execute um programa de amostra `shadow.py` e observe as mensagens** Na janela de linha de comando do Raspberry Pi, se você desconectou o programa, execute o aplicativo de exemplo novamente e observe as mensagens no **cliente de teste MQTT** no **console AWS IoT **. 1. Execute o comando a seguir para reiniciar o programa de amostra. *your-iot-endpoint*Substitua *your-iot-thing-name* e pelos nomes da AWS IoT coisa que você criou anteriormente (por exemplo,`My_light_bulb`) e pelo endpoint para interagir com o dispositivo. ``` cd ~/aws-iot-device-sdk-python-v2/samples/service-clients python3 shadow.py --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint --thing_name your-iot-thing-name ``` Em seguida, o aplicativo de amostra `shadow.py` é executado e recupera o estado de sombra atual. Se você excluiu a sombra ou limpou os estados atuais, o programa define o valor atual como `off` e, em seguida, solicita que você insira um valor `desired`. ``` Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'... Connected! Subscribing to Delta events... Subscribing to Update responses... Subscribing to Get responses... Requesting current shadow state... Launching thread to read user input... Finished getting initial shadow state. Shadow document lacks 'color' property. Setting defaults... Changed local shadow value to 'off'. Updating reported shadow value to 'off'... Update request published. Finished updating reported shadow value to 'off'... Enter desired value: ``` Por outro lado, se o programa estava em execução e você o reiniciou, você verá o valor de cor mais recente relatado no terminal. **No cliente de teste do MQTT, você verá uma atualização nos tópicos **\$1aws/things/ /shadow/get e *thingname* \$1aws/things/**/. *thingname* shadow/get/accepted** Suponha que a última cor relatada tenha sido `green`. A seguir, mostra o conteúdo do arquivo ***thingname*\$1aws/things/**/JSON. shadow/get/accepted ``` { "state": { "desired": { "welcome": "aws-iot", "color": "green" }, "reported": { "welcome": "aws-iot", "color": "green" } }, "metadata": { "desired": { "welcome": { "timestamp": 1620156892 }, "color": { "timestamp": 1620161643 } }, "reported": { "welcome": { "timestamp": 1620156892 }, "color": { "timestamp": 1620161643 } } }, "version": 10, "timestamp": 1620173908 } ``` 1. Insira um valor `desired` no terminal, como `yellow`. O aplicativo de amostra `shadow.py` responde e exibe as seguintes mensagens no terminal que mostram a alteração no valor `reported` para `yellow`. ``` Enter desired value: yellow Changed local shadow value to 'yellow'. Updating reported shadow value to 'yellow'... Update request published. Finished updating reported shadow value to 'yellow'. ``` No **cliente de teste do MQTT** no **console da AWS IoT **, em **Assinaturas**, você vê que os seguintes tópicos receberam uma mensagem: + **\$1aws/things/ *thingname* /shadow/update**: mostra que os valores e os valores mudam para a cor. `desired` `updated` `yellow` + **\$1aws/things/*thingname*/shadow/update/accepted**: mostra os valores atuais dos `reported` estados `desired` e e seus metadados e informações de versão. + **\$1aws/things/*thingname*/shadow/update/documents**: mostra os valores anteriores e atuais dos `reported` estados e e seus metadados `desired` e informações de versão. Como o documento **\$1aws/things/*thingname*/shadow/update/documents**também contém informações contidas nos outros dois tópicos, podemos revisá-lo para ver as informações do estado. O estado anterior mostra o valor relatado definido como `green`, seus metadados e informações de versão e o estado atual que mostra o valor relatado atualizado para `yellow`. ``` { "previous": { "state": { "desired": { "welcome": "aws-iot", "color": "green" }, "reported": { "welcome": "aws-iot", "color": "green" } }, "metadata": { "desired": { "welcome": { "timestamp": 1617297888 }, "color": { "timestamp": 1617297898 } }, "reported": { "welcome": { "timestamp": 1617297888 }, "color": { "timestamp": 1617297898 } } }, "version": 10 }, "current": { "state": { "desired": { "welcome": "aws-iot", "color": "yellow" }, "reported": { "welcome": "aws-iot", "color": "yellow" } }, "metadata": { "desired": { "welcome": { "timestamp": 1617297888 }, "color": { "timestamp": 1617297904 } }, "reported": { "welcome": { "timestamp": 1617297888 }, "color": { "timestamp": 1617297904 } } }, "version": 11 }, "timestamp": 1617297904 } ``` 1. Agora, se você inserir outro valor `desired`, verá mais alterações nos valores `reported` e nas atualizações de mensagens recebidas por esses tópicos. O número da versão também aumenta em 1. Por exemplo, se você inserir o valor `green`, o estado anterior reportará o valor `yellow` e o estado atual relatará o valor `green`. 1. **Edite o documento de sombra para observar eventos delta** Para observar as alterações no tópico delta, edite o documento de sombra no console AWS IoT . Por exemplo, você pode alterar o valor `desired` para a cor `red`. Para fazer isso, no AWS IoT console, escolha **Editar** e defina o `desired` valor como vermelho no JSON, mantendo o `reported` valor definido como. `green` Antes de salvar a alteração, mantenha o terminal aberto, pois você verá a mensagem delta relatada no terminal. ``` { "desired": { "welcome": "aws-iot", "color": "red" }, "reported": { "welcome": "aws-iot", "color": "green" } } ``` O aplicativo de amostra `shadow.py` responde a essa alteração e exibe mensagens no terminal indicando o delta. No cliente de teste MQTT, os tópicos `update` receberão uma mensagem mostrando as alterações nos valores `desired` e `reported`. Você também vê que o tópico **\$1aws/things//*thingname***recebeu uma mensagem. shadow/update/delta Para ver a mensagem, escolha esse tópico, que está listado em **Assinaturas**. ``` { "version": 13, "timestamp": 1617318480, "state": { "color": "red" }, "metadata": { "color": { "timestamp": 1617318480 } } } ``` ## Etapa 3: solucionar problemas com as interações da Sombra do Dispositivo Ao executar o aplicativo de amostra de sombra, você pode encontrar problemas ao observar as interações com o serviço Sombra do Dispositivo. Se o programa for executado com êxito e solicitar que você insira um valor `desired`, você poderá observar as interações da Sombra do Dispositivo usando o documento de sombra e o cliente de teste MQTT, conforme descrito anteriormente. No entanto, se você não conseguir ver as interações, aqui estão algumas objetos que você pode verificar: + **Verifique o nome da coisa e sua sombra no AWS IoT console** Se você não vê as mensagens no documento de sombra, revise o comando e verifique se ele corresponde ao nome do objeto no **AWS IoT console**. Você também pode verificar se tem uma sombra clássica escolhendo seu recurso e, em seguida, escolhendo **Sombras**. Este tutorial se concentra, principalmente, nas interações com a sombra clássica. Você também pode confirmar se o dispositivo usado está conectado à Internet. No **AWS IoT console**, escolha o que você criou anteriormente e, em seguida, escolha **Interagir**. Na página de detalhes do objeto, você deve ver uma mensagem aqui que diz: `This thing already appears to be connected.` + **Verifique os tópicos reservados do MQTT nos quais você se inscreveu** Se você não vir as mensagens aparecendo no cliente de teste MQTT, verifique se os tópicos que você assinou estão formatados corretamente. Os tópicos do MQTT Device Shadow têm um formato **\$1aws/things/ *thingname* /shadow/** e podem ter`update`, ou `delete` segui-lo`get`, dependendo das ações que você deseja realizar na sombra. **Este tutorial usa o tópico **\$1aws/things/ *thingname* /shadow/ \$1**. Portanto, certifique-se de inseri-lo corretamente ao assinar o tópico na seção Filtro de tópicos do cliente de teste.** Ao inserir o nome do tópico, certifique-se de que *thingname* seja igual ao nome da AWS IoT coisa que você criou anteriormente. Você também pode se inscrever em tópicos adicionais do MQTT para ver se uma atualização foi realizada com sucesso. Por exemplo, você pode se inscrever no tópico **\$1aws/things/*thingname*/**para receber uma mensagem sempre que uma solicitação de atualização falhar, shadow/update/rejected para que você possa depurar problemas de conexão. Para obter mais informações sobre os tópicos reservados, consulte [Tópicos de sombra](reserved-topics.md#reserved-topics-shadow) e [Tópicos MQTT da Sombra do Dispositivo](device-shadow-mqtt.md). ## Etapa 4: revisar os resultados e as próximas etapas **Neste tutorial, você aprendeu a:** + Usar o aplicativo de amostra `shadow.py` para especificar os estados desejados e atualizar o estado atual da sombra. + Editar o documento Shadow para observar os eventos delta e como o aplicativo de amostra `shadow.py` responde a eles. + Utilizar o cliente de teste MQTT para assinar tópicos de sombra e observar atualizações ao executar o programa de amostra. **Próximas etapas** Você pode assinar tópicos adicionais reservados do MQTT para observar atualizações no aplicativo da sombra. Por exemplo, se você se inscrever apenas no tópico **\$1aws/things/*thingname*/shadow/update/accepted**, verá somente as informações do estado atual quando uma atualização for realizada com sucesso. Você também pode assinar tópicos de sombra adicionais para depurar problemas ou aprender mais sobre as interações da Sombra do Dispositivo e também depurar quaisquer problemas com as interações da Sombra do Dispositivo. Para obter mais informações, consulte [Tópicos de sombra](reserved-topics.md#reserved-topics-shadow) e [Tópicos MQTT da Sombra do Dispositivo](device-shadow-mqtt.md). Você também pode optar por estender seu aplicativo usando sombras nomeadas ou usando hardware adicional conectado ao Raspberry Pi LEDs e observar alterações em seu estado usando mensagens enviadas do terminal. Para obter mais informações sobre o serviço Sombra do Dispositivo e como usar o serviço em dispositivos, aplicativos e serviços, consulte [AWS IoT Serviço Device Shadow](iot-device-shadows.md), [Usar sombras em dispositivos](device-shadow-comms-device.md) e [Usar sombras em aplicativos e serviços](device-shadow-comms-app.md).