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á. # 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 assinantes do MQTT 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 suporta [MQTT](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) e uma API REST sobre protocolos HTTPS para interagir com sombras. AWS IoT fornece um conjunto de tópicos reservados de solicitação e resposta para ações de publicação e assinatura do MQTT. Dispositivos e aplicativos devem se inscrever nos tópicos de resposta antes de publicar em um tópico de solicitação para obter informações sobre como a solicitação AWS IoT foi tratada. Para obter mais informações, consulte [Tópicos MQTT da Sombra do Dispositivo](device-shadow-mqtt.md) e [API REST da Sombra do Dispositivo](device-shadow-rest-api.md). ## 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 a API [UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow) ou publicando no tópico [/update](device-shadow-mqtt.md#update-pub-sub-topic). 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 alteração de estado em uma sombra usando o protocolo MQTT** 1. 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. 1. O cliente assina estes tópicos MQTT: + `$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` 1. 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" } } } ``` 1. 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](device-shadow-document.md#device-shadow-example-response-json-accepted), e a mensagem `/update/delta` contém um documento de sombra [Documento de estado da resposta /delta](device-shadow-document.md#device-shadow-example-response-json-delta). 1. 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](device-shadow-document.md#device-shadow-example-error-json) paralelo que descreve o erro. **Quando um cliente solicita uma alteração de estado em uma sombra usando a API** 1. O cliente chama a API `UpdateThingShadow` com um documento de estado [Documento de estado de solicitação](device-shadow-document.md#device-shadow-example-request-json) como corpo da mensagem. 1. Se a solicitação for válida, AWS IoT retornará um código HTTP de resposta bem-sucedida e um documento [Documento de estado da resposta /accepted](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo como corpo da mensagem de resposta. AWS IoT também publicará uma mensagem MQTT no `$aws/things/thingName/shadow/name/shadowName/update/delta` tópico com um documento [Documento de estado da resposta /delta](device-shadow-document.md#device-shadow-example-response-json-delta) paralelo para todos os dispositivos ou clientes que a assinarem. 1. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e [Documento de resposta de erro](device-shadow-document.md#device-shadow-example-error-json) 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 para a sombra usando o protocolo MQTT** 1. O dispositivo deve assinar estes tópicos MQTT 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` 1. 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" } } } ``` 1. 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](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo. 1. 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](device-shadow-document.md#device-shadow-example-error-json) paralelo que descreve o erro. **Quando um dispositivo relata seu estado atual para a sombra usando a API** 1. O dispositivo chama a API `UpdateThingShadow` com um documento de estado [Documento de estado de solicitação](device-shadow-document.md#device-shadow-example-request-json) como corpo da mensagem. 1. 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 [Documento de estado da resposta /accepted](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo como corpo da mensagem de resposta. AWS IoT também publicará uma mensagem MQTT no `$aws/things/thingName/shadow/name/shadowName/update/delta` tópico com um documento [Documento de estado da resposta /delta](device-shadow-document.md#device-shadow-example-response-json-delta) paralelo para todos os dispositivos ou clientes que a assinarem. 1. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e [Documento de resposta de erro](device-shadow-document.md#device-shadow-example-error-json) 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. Ao fornecer uma versão com uma solicitação de atualização, o serviço rejeitará 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 de conflito também pode ocorrer em qualquer API que modifique `ThingShadow`, incluindo `DeleteThingShadow`. 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 de sombra usando a API [GetThingShadow](device-shadow-rest-api.md#API_GetThingShadow) ou assinando e publicando no tópico [/get](device-shadow-mqtt.md#get-pub-sub-topic). 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. **Como recuperar um documento de sombra usando o protocolo MQTT** 1. O dispositivo ou o cliente deve assinar estes tópicos MQTT antes de atualizar a sombra: + `$aws/things/thingName/shadow/name/shadowName/get/accepted` + `$aws/things/thingName/shadow/name/shadowName/get/rejected` 1. O dispositivo ou o cliente publica uma mensagem no tópico `$aws/things/thingName/shadow/name/shadowName/get` com um corpo de mensagem vazio. 1. 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](device-shadow-document.md#device-shadow-example-response-json-accepted) no corpo da mensagem. 1. 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](device-shadow-document.md#device-shadow-example-error-json) no corpo da mensagem. **Como recuperar um documento de sombra usando uma API REST** 1. O dispositivo ou o cliente chama a API `GetThingShadow` com um corpo de mensagem vazio. 1. Se a solicitação for válida, AWS IoT retornará um código HTTP de resposta bem-sucedida com um documento [Documento de estado da resposta /accepted](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo como corpo da mensagem de resposta. 1. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e [Documento de resposta de erro](device-shadow-document.md#device-shadow-example-error-json) 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 a API [DeleteThingShadow](device-shadow-rest-api.md#API_DeleteThingShadow) ou publique no tópico [/delete](device-shadow-mqtt.md#delete-pub-sub-topic). **nota** Excluir uma sombra não zera o número da versão imediatamente. Ele será redefinido para zero após 48 horas. ### Excluir uma propriedade de um documento de sombra **Como excluir uma propriedade de uma sombra usando o protocolo MQTT** 1. 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](#retrieving-device-shadow) para acessar informações sobre como ter o documento de sombra atual. 1. O dispositivo ou o cliente assina estes tópicos MQTT: + `$aws/things/thingName/shadow/name/shadowName/update/accepted` + `$aws/things/thingName/shadow/name/shadowName/update/rejected` 1. 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 } } } ``` 1. 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](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo no corpo da mensagem. 1. 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](device-shadow-document.md#device-shadow-example-error-json) paralelo que descreve o erro. **Como excluir uma propriedade de uma sombra usando a API REST** 1. O dispositivo ou o cliente chama a API `UpdateThingShadow` com um [Documento de estado de solicitação](device-shadow-document.md#device-shadow-example-request-json) que atribui valores `null` às propriedades da sombra a ser excluída. 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 } } } ``` 1. Se a solicitação for válida, AWS IoT retornará um código HTTP de resposta bem-sucedida e um documento [Documento de estado da resposta /accepted](device-shadow-document.md#device-shadow-example-response-json-accepted) paralelo como corpo da mensagem de resposta. 1. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e [Documento de resposta de erro](device-shadow-document.md#device-shadow-example-error-json) 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. + Excluir uma sombra não zera o número da versão imediatamente. Ele será redefinido para zero após 48 horas. **Como excluir uma sombra usando o protocolo MQTT** 1. O dispositivo ou o cliente assina estes tópicos MQTT: + `$aws/things/thingName/shadow/name/shadowName/delete/accepted` + `$aws/things/thingName/shadow/name/shadowName/delete/rejected` 1. O dispositivo ou o cliente publica um `$aws/things/thingName/shadow/name/shadowName/delete` com um buffer de mensagens vazio. 1. 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](device-shadow-document.md#device-shadow-example-response-json-accepted) documento-sombra abreviado no corpo da mensagem. Este é um exemplo de mensagem de exclusão aceita: ``` { "version": 4, "timestamp": 1591057529 } ``` 1. 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](device-shadow-document.md#device-shadow-example-error-json) paralelo que descreve o erro. **Como excluir uma sombra usando a API REST** 1. O dispositivo ou o cliente chama a API `DeleteThingShadow` com um buffer de mensagens vazio. 1. Se a solicitação for válida, AWS IoT retornará um código de resposta de sucesso HTTP [Documento de estado da resposta /accepted](device-shadow-document.md#device-shadow-example-response-json-accepted) e um [Documento de estado da resposta /accepted](device-shadow-document.md#device-shadow-example-response-json-accepted) documento-sombra abreviado no corpo da mensagem. Este é um exemplo de mensagem de exclusão aceita: ``` { "version": 4, "timestamp": 1591057529 } ``` 1. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e [Documento de resposta de erro](device-shadow-document.md#device-shadow-example-error-json) como corpo da mensagem de resposta.