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á.
# AWS IoT Serviço Device Shadow
O serviço AWS IoT Device Shadow adiciona sombras aos objetos AWS IoT físicos. As sombras podem disponibilizar o estado de um dispositivo para aplicativos e outros serviços, independentemente de o dispositivo estar conectado AWS IoT ou não. AWS IoT objetos físicos podem ter várias sombras nomeadas para que sua solução de IoT tenha mais opções para conectar seus dispositivos a outros aplicativos e serviços.
AWS IoT objetos de coisas não têm sombras até serem criados explicitamente. As sombras podem ser criadas, atualizadas e excluídas usando o AWS IoT console. Dispositivos, outros clientes da web e serviços podem criar, atualizar e excluir sombras usando o MQTT e os [tópicos MQTT reservados](reserved-topics.md#reserved-topics-shadow), o HTTP usando a Sombra do Dispositivo[ API REST](device-shadow-rest-api.md), e o [AWS CLI para AWS IoT](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html). Como as sombras são armazenadas AWS na nuvem, elas podem coletar e relatar dados de estado do dispositivo de aplicativos e outros serviços em nuvem, independentemente de o dispositivo estar conectado ou não.
## Usar shadows
As sombras fornecem um armazenamento de dados confiável para dispositivos, aplicativos e outros serviços na nuvem para compartilhamento de dados. Eles permitem que dispositivos, aplicativos e outros serviços na nuvem se conectem e desconectem sem perder o estado de um dispositivo.
Enquanto dispositivos, aplicativos e outros serviços em nuvem estão conectados AWS IoT, eles podem acessar e controlar o estado atual de um dispositivo por meio de suas sombras. Por exemplo, um aplicativo pode solicitar uma alteração no estado de um dispositivo atualizando uma sombra. AWS IoT publica uma mensagem que indica a alteração no dispositivo. O dispositivo recebe essa mensagem, atualiza seu estado de forma correspondente e publica uma mensagem com o estado atualizado. O serviço Sombra do Dispositivo reflete esse estado atualizado na sombra correspondente. O aplicativo pode se inscrever na atualização da sombra ou consultar a sombra para saber seu estado atual.
Quando um dispositivo fica off-line, um aplicativo ainda pode se comunicar com AWS IoT as sombras do dispositivo. Quando o dispositivo se reconecta, ele recebe o estado atual de suas sombras para que possa atualizar seu estado de forma correspondente a elas, e possa publicar uma mensagem com seu estado atualizado. Da mesma forma, quando o estado do dispositivo muda enquanto ele está offline, o dispositivo mantém a sombra atualizada para que o aplicativo possa consultar as sombras para saber o estado atual quando ele se reconectar.
Se seus dispositivos ficam offline com frequência e você deseja configurá-los para receber mensagens delta após se reconectarem, você pode usar o atributo de sessão persistente. Para obter mais informações sobre o período de expiração da sessão persistente, consulte [Período de expiração da sessão persistente](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits).
### Optar por usar sombras nomeadas ou sem nome
O serviço Sombra do Dispositivo oferece suporte a sombras nomeadas e sem nome ou clássicas. Um objeto pode ter várias sombras nomeadas e não mais do que uma sombra sem nome. O objeto também pode ter uma sombra nomeada reservada, que opera de forma semelhante a uma sombra nomeada, exceto que você não pode atualizar seu nome. Para obter mais informações, consulte [Sombra nomeada reservada](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow).
Um objeto pode ter sombras nomeadas e sem nome ao mesmo tempo. No entanto, a API usada para acessar cada uma é ligeiramente diferente, portanto, talvez seja mais eficiente decidir o tipo de sombra que funcionará melhor para sua solução e usar somente esse tipo. Para obter mais informações sobre a API para acessar as sombras, consulte [Tópicos de sombra](reserved-topics.md#reserved-topics-shadow).
Com sombras nomeadas, você pode criar diferentes visualizações do estado de um objeto. Por exemplo, é possível dividir um objeto com muitas propriedades em sombras com grupos lógicos de propriedades, cada um identificado por seu nome de sombra. Também é possível limitar o acesso às propriedades agrupando-as em diferentes sombras e usando políticas para controlar o acesso. Para obter mais informações sobre políticas a serem usadas com sombras do dispositivos, consulte [Ações, recursos e chaves de condição AWS IoT](https://docs.aws.amazon.com//service-authorization/latest/reference/list_awsiot.html) e [AWS IoT Core políticas](https://docs.aws.amazon.com//iot/latest/developerguide/iot-policies.html).
As sombras clássicas e sem nome são mais simples, mas um pouco mais limitadas do que as sombras nomeadas. Cada AWS IoT objeto pode ter apenas uma sombra sem nome. Se você espera que sua solução de IoT tenha uma necessidade limitada de dados de sombra, talvez essa seja a maneira como você quer começar a usar sombras. No entanto, se você espera adicionar sombras adicionais no futuro, considere usar sombras nomeadas desde o início.
A indexação de frota oferece suporte a sombras sem nome e sombras com nomes diferentes. Para acessar mais informações, consulte [Gerenciar a indexação de frotas](managing-fleet-index.md).
### Acessar sombras
Cada sombra tem um [tópico do MQTT](reserved-topics.md#reserved-topics-shadow) e um [URL HTTP](device-shadow-rest-api.md) reservados que comportam as ações `get`, `update` e `delete` na sombra.
As sombras usam [documentos JSON de sombra](device-shadow-document.md) para armazenar e recuperar dados. Um documento de sombra contém uma propriedade de estado que descreve estes aspectos do estado do dispositivo:
+ `desired`
Os aplicativos especificam os estados desejados das propriedades do dispositivo atualizando o objeto `desired`.
+ `reported`
Os dispositivos relatam seu estado atual no objeto `reported`.
+ `delta`
AWS IoT relata diferenças entre o estado desejado e o estado relatado no `delta` objeto.
Os dados armazenados em uma sombra são determinados pela propriedade de estado do corpo da mensagem da ação de atualização. As ações de atualização subsequentes podem modificar os valores de um objeto de dados existente e também adicionar e excluir chaves e outros elementos no objeto de estado da sombra. Para receber mais informações sobre como acessar sombras, consulte [Usar sombras em dispositivos](device-shadow-comms-device.md) e [Usar sombras em aplicativos e serviços](device-shadow-comms-app.md).
**Importante**
A permissão para fazer solicitações de atualização deve ser limitada a aplicativos e dispositivos confiáveis. Isso impede que a propriedade de estado da sombra seja alterada inesperadamente. Caso contrário, os dispositivos e aplicativos que usam a sombra devem ser projetados para esperar que as chaves na propriedade de estado sejam alteradas.
### Usar sombras em dispositivos, aplicativos e outros serviços na nuvem
O uso de sombras em dispositivos, aplicativos e outros serviços na nuvem requer consistência e coordenação entre todos eles. O serviço AWS IoT Device Shadow armazena o estado de sombra, envia mensagens quando o estado de sombra muda e responde às mensagens que mudam de estado. Os dispositivos, aplicativos e outros serviços na nuvem em sua solução de IoT devem gerenciar seu estado e mantê-lo consistente com o estado da sombra do dispositivo.
Os dados de estado de sombra são dinâmicos e podem ser alterados pelos dispositivos, aplicativos e outros serviços na nuvem com permissão para acessar a sombra. Por esse motivo, é importante considerar como cada dispositivo, aplicativo e outro serviço de nuvem interagirão com a sombra. Por exemplo:
+ Os *dispositivos* devem gravar somente na propriedade `reported` do estado de sombra ao comunicar dados de estado à sombra.
+ *Os aplicativos e outros serviços na nuvem* devem gravar somente na propriedade `desired` ao comunicar solicitações de alteração de estado ao dispositivo por meio da sombra.
**Importante**
Os dados contidos em um objeto de dados de sombra são independentes dos de outras sombras e de outras propriedades de objeto, como os atributos de um objeto e o conteúdo de mensagens MQTT que um dispositivo de objeto pode publicar. Um dispositivo pode, no entanto, relatar os mesmos dados em diferentes tópicos MQTT e sombras, se necessário.
Um dispositivo compatível com várias sombras deve manter a consistência dos dados que ele relata nas diferentes sombras.
### Ordem das mensagens
Não há garantia de que as mensagens do AWS IoT serviço chegarão ao dispositivo em qualquer ordem específica. O cenário a seguir mostra o que acontece nesse caso.
Documento de estado inicial:
```
{
"state": {
"reported": {
"color": "blue"
}
},
"version": 9,
"timestamp": 123456776
}
```
Atualização 1:
```
{
"state": {
"desired": {
"color": "RED"
}
},
"version": 10,
"timestamp": 123456777
}
```
Atualização 2:
```
{
"state": {
"desired": {
"color": "GREEN"
}
},
"version": 11,
"timestamp": 123456778
}
```
Documento de estado final:
```
{
"state": {
"reported": {
"color": "GREEN"
}
},
"version": 12,
"timestamp": 123456779
}
```
Isso resulta em duas mensagens delta:
```
{
"state": {
"color": "RED"
},
"version": 11,
"timestamp": 123456778
}
```
```
{
"state": {
"color": "GREEN"
},
"version": 12,
"timestamp": 123456779
}
```
O dispositivo pode receber essas mensagens fora de ordem. Como o estado nessas mensagens é cumulativo, um dispositivo pode descartar com segurança as mensagens que contêm um número da versão anterior ao que ele está rastreando. Se o dispositivo receber o delta para a versão 12 antes da versão 11, pele poderá descartar a mensagem da versão 11 com segurança.
### Reduzir mensagens de shadow
Para reduzir o tamanho das mensagens de shadow enviadas para o dispositivo, defina uma regra que selecione apenas os campos de que o dispositivo precisa e, em seguida, publique novamente a mensagem em um tópico MQTT que o dispositivo esteja escutando.
A regra é especificada no JSON e deve ser semelhante ao seguinte:
```
{
"sql": "SELECT state, version FROM '$aws/things/+/shadow/update/delta'",
"ruleDisabled": false,
"actions": [
{
"republish": {
"topic": "${topic(3)}/delta",
"roleArn": "arn:aws:iam:123456789012:role/my-iot-role"
}
}
]
}
```
A declaração de SELECT determina quais campos da mensagem serão publicados novamente no tópico especificado. Um caractere curinga "\$1" é usado para corresponder a todos os nomes de shadow. A regra especifica que todas as mensagens correspondentes devem ser publicadas novamente no tópico especificado. Nesse caso, a função `"topic()"` é usada para especificar o tópico no qual a publicação deverá ser refeita. O `topic(3)` avalia o nome do objeto no tópico original. Para obter mais informações sobre como criar regras, consulte [Regras para AWS IoT](iot-rules.md).
# Usar sombras em dispositivos
Esta seção descreve as comunicações de dispositivos com sombras usando mensagens MQTT, o método preferido para dispositivos se comunicarem com o serviço AWS IoT Device Shadow.
As comunicações paralelas emulam um request/response modelo usando o modelo de comunicação de publicação/assinatura do MQTT. Cada ação de sombra consiste em um tópico de solicitação, um tópico de resposta bem-sucedido (`accepted`) e um tópico de resposta de erro (`rejected`).
Para que os aplicativos e serviços possam determinar se um dispositivo está conectado, consulte [Detectar se um dispositivo está conectado](device-shadow-comms-app.md#thing-connection).
**Importante**
Como o MQTT usa um modelo de publish/subscribe comunicação, você deve se inscrever nos tópicos de resposta *antes de* publicar um tópico de solicitação. Caso contrário, você não deve receber a resposta à solicitação que publicar.
Se você usa um [AWS IoT Device SDK](iot-sdks.md)para chamar o serviço Device Shadow APIs, isso é feito para você.
Os exemplos desta seção usam uma forma abreviada do tópico em que *ShadowTopicPrefix* podem se referir a uma sombra nomeada ou não nomeada, conforme descrito nesta tabela.
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.
| Valor do *ShadowTopicPrefix* | Tipo de sombra |
| --- | --- |
| \$1aws/things/thingName/shadow | Sombra sem nome (clássica) |
| \$1aws/things/thingName/shadow/name/shadowName | Sombra nomeada |
**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. Por exemplo, considere como as sombras são criadas, atualizadas e excluídas. Considere também como as atualizações são processadas no dispositivo e nos aplicativos ou serviços que acessam o dispositivo por meio de uma sombra. Seu design deve ser claro sobre como o estado do dispositivo é atualizado e relatado e como seus aplicativos e serviços interagem com o dispositivo e suas sombras.
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 ao stub de tópico, conforme mostrado na seguinte tabela. Lembre-se de que os tópicos diferenciam maiúsculas de minúsculas.
Consulte [Tópicos de sombra](reserved-topics.md#reserved-topics-shadow) para receber mais informações sobre os tópicos reservados para sombras.
## Inicializando o dispositivo na primeira conexão com AWS IoT
Depois que um dispositivo se registra AWS IoT, ele deve assinar essas mensagens MQTT para as sombras que ele suporta.
| Tópico | Significado | Ação que um dispositivo deve executar quando este tópico é recebido |
| --- | --- | --- |
| `ShadowTopicPrefix/delete/accepted` | A `delete` solicitação foi aceita e a sombra foi AWS IoT excluída. | As ações necessárias para acomodar a sombra excluída, como interromper a publicação de atualizações. |
| `ShadowTopicPrefix/delete/rejected` | A `delete` solicitação foi rejeitada AWS IoT e a sombra não foi excluída. O corpo da mensagem contém as informações do erro. | Responda à mensagem de erro no corpo da mensagem. |
| `ShadowTopicPrefix/get/accepted` | A `get` solicitação foi aceita por AWS IoT, e o corpo da mensagem contém o documento paralelo atual. | As ações necessárias para processar o documento de estado no corpo da mensagem. |
| `ShadowTopicPrefix/get/rejected` | A `get` solicitação foi rejeitada por AWS IoT, e o corpo da mensagem contém as informações do erro. | Responda à mensagem de erro no corpo da mensagem. |
| `ShadowTopicPrefix/update/accepted` | A `update` solicitação foi aceita por AWS IoT, e o corpo da mensagem contém o documento paralelo atual. | Confirme se os dados atualizados no corpo da mensagem correspondem ao estado do dispositivo. |
| `ShadowTopicPrefix/update/rejected` | A `update` solicitação foi rejeitada por AWS IoT, e o corpo da mensagem contém as informações do erro. | Responda à mensagem de erro no corpo da mensagem. |
| `ShadowTopicPrefix/update/delta` | O documento paralelo foi atualizado por meio de uma solicitação para AWS IoT, e o corpo da mensagem contém as alterações solicitadas. | Atualize o estado do dispositivo para que corresponda ao estado desejado no corpo da mensagem. |
| `ShadowTopicPrefix/update/documents` | Uma atualização na sombra foi concluída recentemente e o corpo da mensagem contém o documento de sombra atual. | Confirme se o estado atualizado no corpo da mensagem corresponde ao estado do dispositivo. |
Depois de assinar as mensagens na tabela anterior para cada sombra, o dispositivo deve testar para ver se as sombras às quais oferece suporte já foram criadas pela publicação de um tópico `/get` para cada sombra. Se uma mensagem `/get/accepted` for recebida, o corpo da mensagem conterá o documento de sombra que o dispositivo pode usar para inicializar seu estado. Se uma mensagem `/get/rejected` for recebida, a sombra deverá ser criada publicando uma mensagem `/update` com o estado do dispositivo atual.
Por exemplo, suponha que você tenha uma `My_IoT_Thing` objeto que não tenha sombras clássicas ou nomeadas. Se você publicar agora uma solicitação `/get` no tópico `$aws/things/My_IoT_Thing/shadow/get` reservado, será retornado um erro no tópico `$aws/things/My_IoT_Thing/shadow/get/rejected` porque o objeto não tem sombras. Para resolver esse erro, primeiro publique uma mensagem `/update` usando o tópico `$aws/things/My_IoT_Thing/shadow/update` com o estado atual do dispositivo, como a carga útil a seguir.
```
{
"state": {
"reported": {
"welcome": "aws-iot",
"color": "yellow"
}
}
}
```
Uma sombra clássica agora é criada para o objeto e a mensagem é publicada no tópico `$aws/things/My_IoT_Thing/shadow/update/accepted`. Se você publicar no tópico `$aws/things/My_IoT_Thing/shadow/get`, ele retornará uma resposta ao tópico `$aws/things/My_IoT_Thing/shadow/get/accepted` com o estado do dispositivo.
Para sombras nomeadas, você deve primeiro criar a sombra nomeada ou publicar uma atualização com o nome da sombra antes de usar a solicitação get. Por exemplo, para criar uma sombra nomeada `namedShadow1`, primeiro publique as informações do estado do dispositivo no tópico `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/update`. Para recuperar as informações do estado, use a solicitação `/get` para a sombra nomeada, `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/get`.
## Processando mensagens enquanto o dispositivo está conectado ao AWS IoT
Enquanto um dispositivo está conectado AWS IoT, ele pode receber mensagens **/update/delta** e deve manter o estado do dispositivo compatível com as mudanças em suas sombras da seguinte forma:
1. Lendo todas as mensagens **/update/delta** recebidas e sincronizando o estado do dispositivo para que corresponda.
1. Publicando uma mensagem **/update** com um corpo de mensagem `reported` que tenha o estado atual do dispositivo, sempre que o estado do dispositivo for alterado.
Enquanto um dispositivo está conectado, ele deve publicar essas mensagens quando indicado.
| Indicação | Tópico | Carga útil |
| --- | --- | --- |
| O estado do dispositivo foi alterado. | `ShadowTopicPrefix/update` | Um documento de sombra com a propriedade `reported`. |
| O dispositivo pode não estar sincronizado com a sombra. | `ShadowTopicPrefix/get` | (empty) |
| Uma ação no dispositivo indica que uma sombra não será mais compatível com o dispositivo, como quando o dispositivo é removido ou substituído. | `ShadowTopicPrefix/delete` | (empty) |
## Processando mensagens quando o dispositivo se reconecta ao AWS IoT
Quando um dispositivo com uma ou mais sombras se conecta AWS IoT, ele deve sincronizar seu estado com o de todas as sombras que ele suporta por meio de:
1. Lendo todas as mensagens **/update/delta** recebidas e sincronizando o estado do dispositivo para que corresponda.
1. Publicando uma mensagem **/update** com um corpo de mensagem `reported` que tenha o estado atual do dispositivo.
# 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 em[Usar sombras em dispositivos](device-shadow-comms-device.md), que usa um modelo de publish/subscribe communications model, this example uses the request/response comunicação 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 sobre mudanças no estado do dispositivo, considere os protocolos MQTT ou MQTT over WSS, que oferecem suporte ao modelo de publish/subscribe comunicação, conforme descrito em. [Usar sombras em dispositivos](device-shadow-comms-device.md)
**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 às URLs 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 sobre URLs as 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 para as URLs sombras que ele usa para atualizar o `desired` estado 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 \$1) 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"
}
}
]
}
}
```
1. 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"
}
}
}
```
1. 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"
}
}
}
```
1. 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"
}
}
}
```
1. 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.
**nota**
Devido à natureza assíncrona do processamento de desconexão, não é garantido que as mensagens LWT sejam enviadas em ordem durante a reconexão. Recomendamos que você use [eventos de ciclo](life-cycle-events.md) de vida para melhorar a precisão da detecção do estado de conectividade, pois esses eventos fornecem atributos para gerenciar out-of-order eventos.
# Simulando comunicações de serviço Sombra do Dispositivo
Este tópico demonstra como o serviço Sombra do Dispositivo atua como intermediário e permite que dispositivos e aplicativos usem uma sombra para atualizar, armazenar e recuperar o estado de um dispositivo.
Para demonstrar a interação descrita neste tópico e explorá-la mais detalhadamente, você precisará de um Conta da AWS e um sistema no qual possa executar AWS CLI o. Se não os tiver, você ainda poderá ver a interação nos exemplos de código.
Neste exemplo, o AWS IoT console representa o dispositivo. O AWS CLI representa o aplicativo ou serviço que acessa o dispositivo por meio da sombra. A AWS CLI interface é muito semelhante à API que um aplicativo pode usar para se comunicar AWS IoT. O dispositivo neste exemplo é uma lâmpada inteligente, e o aplicativo exibe o estado da lâmpada e pode alterá-lo.
## Configurar a simulação
Estes procedimentos inicializam a simulação abrindo o [Console do AWS IoT](https://console.aws.amazon.com/iot/home), que simula o dispositivo, e a janela da linha de comando que simula o aplicativo.
**Como configurar o ambiente de simulação**
1. Você precisará Conta da AWS executar os exemplos deste tópico sozinho. Se você não tiver um Conta da AWS, crie um, conforme descrito em[Configurar Conta da AWS](setting-up.md).
1. Abra o [Console do AWS IoT](https://console.aws.amazon.com/iot/home), e, no menu esquerdo, escolha **Testar** para abrir o **Cliente MQTT**.
1. Em outra janela, abra uma janela de terminal em um sistema que tenha a AWS CLI instalada.
Você deve ter duas janelas abertas: uma com o AWS IoT console na página de **teste** e outra com um prompt de linha de comando.
## Inicializar o dispositivo
Nesta simulação, trabalharemos com um objeto chamado, *mySimulatedThing*, e sua sombra chamada *SimShadow1*.
**Criar objeto e sua política de IoT**
Para criar um objeto, no **AWS IoT Console**:
1. Escolha **Gerenciar** e em seguida, **Objetos**.
1. Clique no botão **Criar** se as coisas estiverem listadas, caso contrário, clique em **Registrar uma única coisa** para criar uma única AWS IoT coisa.
1. Insira o nome `mySimulatedThing`, deixe outras configurações como padrão e clique em **Próximo**.
1. Use a criação de certificado com um clique para gerar os certificados que autenticarão a conexão do dispositivo com o AWS IoT. Clique em **Ativar** para ativar o certificado.
1. Você pode anexar a política `My_IoT_Policy` que daria permissão ao dispositivo para publicar e assinar os tópicos reservados do MQTT. Para obter etapas mais detalhadas sobre como criar AWS IoT algo e como criar essa política, consulte[Criar um objeto](create-iot-resources.md#create-aws-thing).
**Crie uma sombra nomeada para o objeto-objeto**
Você pode criar uma sombra nomeada para algo publicando uma solicitação de atualização no tópico `$aws/things/mySimulatedThing/shadow/name/simShadow1/update` conforme descrito abaixo.
Ou crie uma sombra nomeada:
1. No **AWS IoT Console**, escolha seu objeto na lista de itens exibidos e, em seguida, escolha **Sombras**.
1. Escolha **Adicionar uma sombra**, insira o nome `simShadow1` e escolha **Criar** para adicionar a sombra nomeada.
**Inscreva-se e publique em tópicos reservados do MQTT**
No console, assine os shadow topics reservados do MQTT. Esses tópicos são as respostas às ações `get`, `update` e `delete` para que seu dispositivo esteja pronto para receber as respostas depois de publicar uma ação.
**Como assinar um tópico MQTT no **Cliente MQTT****
1. No **cliente MQTT**, escolha **Assinar um tópico**.
1. Insira os tópicos `get`, `update` e `delete` para se inscrever. Copie um tópico por vez da lista a seguir, cole-o no campo **Filtro de tópico** e clique em **Inscrever**. Você deverá ver os tópicos aparecerem em **Inscrições**.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/documents`
Neste ponto, seu dispositivo simulado está pronto para receber os tópicos conforme são publicados pelo AWS IoT.
**Como publicar um tópico MQTT no **Cliente MQTT****
Depois que um dispositivo se inicializar e assinar tópicos de resposta, ele deve consultar as sombras compatíveis. Essa simulação suporta apenas uma sombra, a sombra que suporta um objeto chamado, *mySimulatedThing*, chamado *SimShadow1*.
**Como obter o estado da sombra atual no **Cliente MQTT****
1. No **Cliente MQTT**, escolha **Publicar em um tópico**.
1. Em **Publicar**, insira o seguinte tópico e exclua qualquer conteúdo da janela do corpo da mensagem abaixo de onde você inseriu o tópico para obter. Em seguida, você pode escolher **Publicar no tópico** para publicar a solicitação. `$aws/things/mySimulatedThing/shadow/name/simShadow1/get`.
Se você não criou a sombra nomeada, `simShadow1`, você receberá uma mensagem no tópico `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected` e o `code` é `404`, como neste exemplo, a sombra não terá sido criada, portanto, vamos criá-la a seguir.
```
{
"code": 404,
"message": "No shadow exists with name: 'simShadow1'"
}
```
**Como criar uma sombra com o status atual do dispositivo**
1. No **Cliente MQTT**, escolha **Publicar em um tópico** e insira este tópico:
```
$aws/things/mySimulatedThing/shadow/name/simShadow1/update
```
1. Na janela de corpo da mensagem abaixo do local em que você inseriu o tópico, insira este documento de sombra para mostrar que o dispositivo está relatando seu ID e sua cor atual em valores RGB. Escolha **Publicar** para publicar a solicitação.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
Se você receber uma mensagem no tópico:
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`: a sombra foi criada e o corpo da mensagem contém o documento de sombra atual.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`: revise o erro no corpo da mensagem.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`: a sombra já existirá e o corpo da mensagem terá o estado da sombra atual, como neste exemplo. Com isso, você pode definir seu dispositivo ou confirmar que ele corresponde ao estado da sombra.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591140517,
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
## Enviar uma atualização do aplicativo
Esta seção usa o AWS CLI para demonstrar como um aplicativo pode interagir com uma sombra.
**Para obter o estado atual da sombra usando o AWS CLI**
Na linha de comando, insira este comando.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Nas plataformas Windows, você pode usar `con` ao invés de `/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
Como a sombra existe e foi inicializada pelo dispositivo para refletir seu estado atual, ela deve retornar o seguinte documento de sombra.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591141111
}
```
O aplicativo pode usar essa resposta para inicializar sua representação do estado do dispositivo.
Se o aplicativo atualizar o estado, como quando um usuário final altera a cor da nossa lâmpada inteligente para amarelo, o aplicativo enviará um comando **update-thing-shadow**. Esse comando corresponde à API REST `UpdateThingShadow`.
**Como atualizar uma sombra de um aplicativo**
Na linha de comando, insira este comando.
------
#### [ AWS CLI v2.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--cli-binary-format raw-in-base64-out \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
#### [ AWS CLI v1.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
Se for bem-sucedido, esse comando deverá retornar o seguinte documento de sombra.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
}
},
"version": 4,
"timestamp": 1591141596,
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
## Responder à atualização no dispositivo
Retornando ao **cliente MQTT** no AWS console, você deve ver as mensagens AWS IoT publicadas para refletir o comando de atualização emitido na seção anterior.
**Como exibir as mensagens de atualização no **Cliente MQTT****
No **cliente MQTT**, escolha **\$1 aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta** na coluna **Assinaturas**. Se o nome do tópico estiver truncado, você poderá pausar nele para ver o tópico completo. No log do tópico deste tópico, você deverá ver uma mensagem `/delta` semelhante a esta.
```
{
"version": 4,
"timestamp": 1591141596,
"state": {
"ColorRGB": [
255,
255,
0
]
},
"metadata": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
Seu dispositivo processará o conteúdo desta mensagem para definir o estado do dispositivo para que corresponda ao estado `desired` na mensagem.
Depois que o dispositivo atualizar o estado para corresponder ao `desired` estado na mensagem, ele deverá enviar o novo estado relatado de volta AWS IoT publicando uma mensagem de atualização. Este procedimento simula isso no **Cliente MQTT**.
**Como atualizar a sombra no dispositivo**
1. No **Cliente MQTT**, escolha **Publicar em um tópico**.
1. Na janela do corpo da mensagem, no campo de tópico acima da janela do corpo da mensagem, insira o tópico do shadow seguido da ação `/update`: `$aws/things/mySimulatedThing/shadow/name/simShadow1/update` e no corpo da mensagem, insira este documento shadow atualizado, que descreve o estado atual do dispositivo. Clique em **Publicar** para publicar o estado atualizado do dispositivo.
```
{
"state": {
"reported": {
"ColorRGB": [255,255,0]
}
},
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Se a mensagem foi recebida com sucesso por AWS IoT, você deverá ver uma nova resposta no registro de aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted mensagens **\$1** no **cliente MQTT** com o estado atual da sombra, como neste exemplo.
```
{
"state": {
"reported": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"reported": {
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Uma atualização bem-sucedida do estado relatado do dispositivo também faz AWS IoT com que uma descrição abrangente do estado de sombra em uma mensagem seja enviada ao `update/documents` tópico, como o corpo da mensagem resultante da atualização paralela realizada pelo dispositivo no procedimento anterior.
```
{
"previous": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 4
},
"current": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5
},
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
## Observar a atualização no aplicativo
O aplicativo agora pode consultar o estado atual da sombra conforme relatado pelo dispositivo.
**Para obter o estado atual da sombra usando o AWS CLI**
1. Na linha de comando, insira este comando.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Nas plataformas Windows, você pode usar `con` ao invés de `/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
1. Como a sombra acaba de ser atualizada pelo dispositivo para refletir seu estado atual, ele deve retornar o seguinte documento de sombra.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591143269
}
```
## Além da simulação
Experimente a interação entre a AWS CLI (representando o aplicativo) e o console (representando o dispositivo) para modelar sua solução de IoT.
# 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.
# API REST da Sombra do Dispositivo
Um shadow expõe a seguinte URI para atualizar as informações de estado:
```
https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow
```
O endpoint é específico para o seu Conta da AWS. Para encontrar o endpoint, você pode:
+ Usar o comando [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) do AWS CLI.
+ Use as configurações AWS IoT do console. Em **Configurações**, o endpoint está listado em **Endpoint personalizado**
+ Use a página de detalhes do item do AWS IoT console. No console do:
1. Abra **Gerenciar** e, em **Gerenciar**, escolha **Objetos**.
1. Na lista de itens, escolha o item para o qual você deseja obter o URI do endpoint.
1. Escolha a guia **Sombras do Dispositivo** e escolha sua sombra. Você pode visualizar o URI do endpoint na seção **URL Sombra do Dispositivo** da página de **detalhes da Sombra do Dispositivo**.
O formato do endpoint é o seguinte:
```
identifier.iot.region.amazonaws.com
```
A Shadow REST API segue os mesmos protocols/port mapeamentos HTTPS descritos em. [Protocolos de comunicação do dispositivo](protocols.md)
**nota**
Para usar o APIs, você deve usar `iotdevicegateway` como nome do serviço para autenticação. Para obter mais informações, consulte [Io TData Plane](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html).
**Topics**
+ [GetThingShadow](#API_GetThingShadow)
+ [UpdateThingShadow](#API_UpdateThingShadow)
+ [DeleteThingShadow](#API_DeleteThingShadow)
+ [ListNamedShadowsForThing](#API_ListNamedShadowsForThing)
Você também pode usar a API para criar uma sombra nomeada fornecendo `name=shadowName` como parte do parâmetro de consulta da API.
## GetThingShadow
Obtém o shadow do objeto especificada.
O documento de estado de resposta inclui o delta entre os estados `desired` e `reported`.
**Solicitação**
A solicitação inclui os cabeçalhos HTTP padrão, além da seguinte URI:
```
HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
O parâmetro de consulta `name` não é necessário para sombras sem nome (clássicas).
**Resposta**
Após o sucesso, a resposta incluirá os cabeçalhos HTTP padrão e os seguintes código e corpo:
```
HTTP 200
Response Body: response state document
```
Para obter mais informações, consulte [Exemplo de documento de estado de resposta](device-shadow-document.md#device-shadow-example-response-json).
**Autorização**
Recuperar um shadow requer uma política que permite que o chamador execute a ação `iot:GetThingShadow`. O serviço Sombra do Dispositivo aceita duas formas de autenticação: assinatura da versão 4 com credenciais do IAM ou autenticação mútua do TLS com um certificado cliente.
Veja a seguir um exemplo de política que permite que um chamador recupere uma shadow de dispositivo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:GetThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## UpdateThingShadow
Atualiza o shadow do objeto especificada.
As atualizações afetam apenas os campos especificados no documento de estado da solicitação. Os campos com um valor de `null` são removido da shadow de dispositivo.
**Solicitação**
A solicitação inclui os cabeçalhos HTTP padrão e os seguintes URI e corpo:
```
HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document
```
O parâmetro de consulta `name` não é necessário para sombras sem nome (clássicas).
Para obter mais informações, consulte [Exemplo de documento de estado de solicitação](device-shadow-document.md#device-shadow-example-request-json).
**Resposta**
Após o sucesso, a resposta incluirá os cabeçalhos HTTP padrão e os seguintes código e corpo:
```
HTTP 200
Response body: response state document
```
Para obter mais informações, consulte [Exemplo de documento de estado de resposta](device-shadow-document.md#device-shadow-example-response-json).
**Autorização**
Atualizar um shadow requer uma política que permite que o chamador execute a ação `iot:UpdateThingShadow`. O serviço Sombra do Dispositivo aceita duas formas de autenticação: assinatura da versão 4 com credenciais do IAM ou autenticação mútua do TLS com um certificado cliente.
Veja a seguir um exemplo de política que permite que um chamador atualize uma shadow de dispositivo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:UpdateThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## DeleteThingShadow
Apaga o shadow do objeto especificada.
**Solicitação**
A solicitação inclui os cabeçalhos HTTP padrão, além da seguinte URI:
```
HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
O parâmetro de consulta `name` não é necessário para sombras sem nome (clássicas).
**Resposta**
Após o sucesso, a resposta incluirá os cabeçalhos HTTP padrão e os seguintes código e corpo:
```
HTTP 200
Response body: Empty response state document
```
Observe que a exclusão de uma sombra não redefine seu número da versão para 0.
**Autorização**
Apagar uma shadow de dispositivo requer uma política que permite que o chamador execute a ação `iot:DeleteThingShadow`. O serviço Sombra do Dispositivo aceita duas formas de autenticação: assinatura da versão 4 com credenciais do IAM ou autenticação mútua do TLS com um certificado cliente.
Veja a seguir um exemplo de política que permite que um chamador exclua uma shadow de dispositivo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DeleteThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## ListNamedShadowsForThing
Lista as sombras do objeto especificada.
**Solicitação**
A solicitação inclui os cabeçalhos HTTP padrão, além da seguinte URI:
```
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
```
nextToken
O token para recuperação do próximo conjunto de resultados.
Esse valor é retornado nos resultados paginados e é usado na chamada que retorna a próxima página.
pageSize
O número de nomes de sombra a serem retornados em cada chamada. Consulte também `nextToken`.
thingName
O nome do objeto para a qual listar as sombras nomeadas.
**Resposta**
Quando bem-sucedido, a resposta incluirá os cabeçalhos HTTP padrão e o seguinte código de resposta e um [Documento de resposta da lista de nomes de sombra](device-shadow-document.md#device-shadow-list-json).
**nota**
A sombra sem nome (clássica) não aparece nesta lista. A resposta é uma lista vazia se você tiver apenas uma sombra clássica ou se a `thingName` especificada não existir.
```
HTTP 200
Response body: Shadow name list document
```
**Autorização**
Listar uma shadow de dispositivo requer uma política que permite que o chamador execute a ação `iot:ListNamedShadowsForThing`. O serviço Sombra do Dispositivo aceita duas formas de autenticação: assinatura da versão 4 com credenciais do IAM ou autenticação mútua do TLS com um certificado cliente.
Veja a seguir um exemplo de política que permite que um chamador liste as sombras nomeadas de um objeto:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:ListNamedShadowsForThing",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
# Tópicos MQTT da Sombra do Dispositivo
O serviço Sombra do Dispositivo usa tópicos MQTT reservados para permitir que aplicativos e dispositivos obtenham, atualizem ou apaguem 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](device-shadow-data-flow.md).
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.
| Valor do *ShadowTopicPrefix* | Tipo de sombra |
| --- | --- |
| \$1aws/things/thingName/shadow | Sombra sem nome (clássica) |
| \$1aws/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.
Veja a seguir os tópicos do MQTT usados para interagir com shadows.
**Topics**
+ [/get](#get-pub-sub-topic)
+ [/get/accepted](#get-accepted-pub-sub-topic)
+ [/get/rejected](#get-rejected-pub-sub-topic)
+ [/update](#update-pub-sub-topic)
+ [/update/delta](#update-delta-pub-sub-topic)
+ [/update/accepted](#update-accepted-pub-sub-topic)
+ [/update/documents](#update-documents-pub-sub-topic)
+ [/update/rejected](#update-rejected-pub-sub-topic)
+ [/delete](#delete-pub-sub-topic)
+ [/delete/accepted](#delete-accepted-pub-sub-topic)
+ [/delete/rejected](#delete-rejected-pub-sub-topic)
## /get
Publique uma mensagem vazia nesse tópico para obter a shadow de dispositivo:
```
ShadowTopicPrefix/get
```
AWS IoT responde publicando em um [/get/accepted](#get-accepted-pub-sub-topic) ou[/get/rejected](#get-rejected-pub-sub-topic).
### 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:us-east-1:123456789012: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](device-shadow-document.md#device-shadow-example-response-json).
### 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:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012: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](device-shadow-document.md#device-shadow-example-error-json).
### 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:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012: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](device-shadow-document.md#device-shadow-example-request-json).
Ao tentar atualizar o estado de um dispositivo, um cliente envia um documento de estado de solicitação JSON com a propriedade `desired` como este:
```
{
"state": {
"desired": {
"color": "red",
"power": "on"
}
}
}
```
Ao atualizar sua sombra, um dispositivo envia um documento de estado de solicitação JSON com a propriedade `reported`, como este:
```
{
"state": {
"reported": {
"color": "red",
"power": "on"
}
}
}
```
AWS IoT responde publicando em um [/update/accepted](#update-accepted-pub-sub-topic) ou[/update/rejected](#update-rejected-pub-sub-topic).
### 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:us-east-1:123456789012: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 de resposta contém valores `desired` e `reported` estados diferentes para:
```
ShadowTopicPrefix/update/delta
```
O buffer de mensagens contém um [Documento de estado da resposta /delta](device-shadow-document.md#device-shadow-example-response-json-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:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/delta"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012: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](device-shadow-document.md#device-shadow-example-response-json-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:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012: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](device-shadow-document.md#device-shadow-example-response-json-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:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/documents"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012: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](device-shadow-document.md#device-shadow-example-error-json).
### 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:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012: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](#delete-accepted-pub-sub-topic) ou[/delete/rejected](#delete-rejected-pub-sub-topic).
### 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:us-east-1:123456789012: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:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012: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](device-shadow-document.md#device-shadow-example-error-json).
### 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:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/rejected"
]
}
]
}
```
# Documentos do serviço Sombra do Dispositivo
O serviço Sombra do Dispositivo respeita todas as regras da especificação JSON. Os valores, objetos e matrizes são armazenados no documento de shadow do dispositivo.
**Topics**
+ [Exemplos de documentos de sombra](#device-shadow-document-syntax)
+ [Propriedades do documento](#document-structure)
+ [Estado delta](#delta-state)
+ [Versionamento de documentos de sombra](#versioning)
+ [Tokens de cliente em documentos de sombra](#client-token)
+ [Propriedades vazias do documento de sombra](#device-shadow-empty-fields)
+ [Valores de matriz em documentos de sombra](#device-shadow-arrays)
## Exemplos de documentos de sombra
O serviço Device Shadow usa esses documentos nas operações UPDATE, GET e DELETE usando a [API REST](device-shadow-rest-api.md) ou [ Pub/Sub mensagens MQTT](device-shadow-mqtt.md).
**Topics**
+ [Documento de estado de solicitação](#device-shadow-example-request-json)
+ [Documentos de estado da resposta](#device-shadow-example-response-json)
+ [Documento de resposta de erro](#device-shadow-example-error-json)
+ [Documento de resposta da lista de nomes de sombra](#device-shadow-list-json)
### Documento de estado de solicitação
Um documento de estado de solicitação tem o seguinte formato:
```
{
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer1,
"attribute2": "string1",
...
"attributeN": boolean1
}
},
"clientToken": "token",
"version": version
}
```
+ `state` — As atualizações afetam apenas os campos especificados. Normalmente, você usará a propriedade `reported` ou `desired`, mas não ambas na mesma solicitação.
+ `desired` — As propriedades de estado e os valores solicitados para serem atualizados no dispositivo.
+ `reported` — As propriedades de estado e os valores relatados pelo dispositivo.
+ `clientToken` — Se usado, é possível combinar a solicitação e a resposta correspondente pelo token do cliente.
+ `version` — Se usado, o serviço Sombra do Dispositivo processará a atualização somente se a versão especificada corresponder à versão mais recente que ele tem.
### Documentos de estado da resposta
Os documentos de estado de resposta têm o seguinte formato, dependendo do tipo de resposta.
#### Documento de estado da resposta /accepted
```
{
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"timestamp": timestamp,
"clientToken": "token",
"version": version
}
```
#### Documento de estado da resposta /delta
```
{
"state": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"metadata": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"timestamp": timestamp,
"clientToken": "token",
"version": version
}
```
#### Documento de estado da resposta /documents
```
{
"previous" : {
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer1,
"attribute2": "string1",
...
"attributeN": boolean1
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"reported": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"version": version-1
},
"current": {
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"reported": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"version": version
},
"timestamp": timestamp,
"clientToken": "token"
}
```
#### Propriedades do documento de estado de resposta
+ `previous` — Após uma atualização bem-sucedida, contém o `state` do objeto antes da atualização.
+ `current` — Após uma atualização bem-sucedida, contém o `state` do objeto após a atualização.
+ `state`
+ `reported` — Presente apenas se um objeto relatou algum dado na seção `reported` e tiver apenas campos que estavam no documento de estado da solicitação.
+ `desired` — Presente apenas se um dispositivo relatou algum dado na seção `desired` e tiver apenas campos que estavam no documento de estado da solicitação.
+ `metadata` — Contém as marcações de data e hora de cada atributo nas seções `desired` e `reported` para que você possa determinar quando o estado foi atualizado.
+ `timestamp`— A data e a hora da Epoch pelas quais a resposta foi gerada AWS IoT.
+ `clientToken` — Presente somente se um token cliente foi usado ao publicar um JSON válido no tópico `/update`.
+ `version` — A versão atual do documento da shadow de dispositivo compartilhado na AWS IoT. Ela é incrementada em um em relação à versão anterior do documento.
### Documento de resposta de erro
Um documento de resposta de erro tem o seguinte formato:
```
{
"code": error-code,
"message": "error-message",
"timestamp": timestamp,
"clientToken": "token"
}
```
+ `code` — Um código de resposta HTTP que indica o tipo de erro.
+ `message` — Uma mensagem de texto que fornece informações adicionais.
+ `timestamp`— A data e a hora pelas quais a resposta foi gerada AWS IoT. Esta propriedade não está presente em todos os documentos de resposta do erro.
+ `clientToken` — Presente somente se um token de cliente foi usado na mensagem publicada.
Para obter mais informações, consulte [Mensagens de erro da Sombra do Dispositivo](device-shadow-error-messages.md).
### Documento de resposta da lista de nomes de sombra
Um documento de resposta de lista de nomes de sombra tem o seguinte formato:
```
{
"results": [
"shadowName-1",
"shadowName-2",
"shadowName-3",
"shadowName-n"
],
"nextToken": "nextToken",
"timestamp": timestamp
}
```
+ `results` — A matriz de nomes de sombras.
+ `nextToken` — O valor do token a ser usado em solicitações paginadas para obter a próxima página na sequência. Essa propriedade não está presente quando não há mais nomes de sombra para retornar.
+ `timestamp`— A data e a hora pelas quais a resposta foi gerada AWS IoT.
## Propriedades do documento
Um documento de shadow de dispositivo tem as seguintes propriedades:
`state`
`desired`
O estado desejado do dispositivo. Os aplicativos podem gravar nessa parte do documento para atualizar o estado de um dispositivo diretamente, sem precisar se conectar a ele.
`reported`
O estado relatado do objeto. Os dispositivos gravam nessa parte do documento para relatar seu novo estado. Os aplicativos leem essa parte do documento para determinar o último estado relatado do dispositivo.
`metadata`
Informações sobre os dados armazenados na seção `state` do documento. Isso inclui marcações de data e hora, no tempo Epoch, para cada atributo na seção `state`, que permite determinar quando foram atualizados.
Os metadados não contribuem para o tamanho do documento para Limites de serviço ou definição de preço. Para obter mais informações, consulte [Limites de serviço da AWS IoT](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot).
`timestamp`
Indica quando a mensagem foi enviada por AWS IoT. Com o uso do carimbo de data/hora na mensagem e os carimbos de data/hora de atributos individuais na seção `desired` ou `reported`, um dispositivo pode determinar a idade de uma propriedade, mesmo que o dispositivo não tenha um relógio interno.
`clientToken`
Uma string exclusiva do dispositivo que permite associar respostas com as solicitações em um ambiente MQTT.
`version`
A versão do documento. Toda vez que o documento é atualizado, o número da versão é incrementado. Usado para garantir que a versão do documento que está sendo atualizado seja a mais recente.
Para obter mais informações, consulte [Exemplos de documentos de sombra](#device-shadow-document-syntax).
## Estado delta
Estado delta é um tipo virtual de estado que contém a diferença entre os estados `desired` e `reported`. Os campos na seção `desired` que não estão na seção `reported` são incluídos no delta. Os campos na seção `reported` e que não estão na seção `desired` não são incluídos no delta. O delta contém metadados, e seus valores são iguais aos metadados no campo `desired`. Por exemplo:
```
{
"state": {
"desired": {
"color": "RED",
"state": "STOP"
},
"reported": {
"color": "GREEN",
"engine": "ON"
},
"delta": {
"color": "RED",
"state": "STOP"
}
},
"metadata": {
"desired": {
"color": {
"timestamp": 12345
},
"state": {
"timestamp": 12345
}
},
"reported": {
"color": {
"timestamp": 12345
},
"engine": {
"timestamp": 12345
}
},
"delta": {
"color": {
"timestamp": 12345
},
"state": {
"timestamp": 12345
}
}
},
"version": 17,
"timestamp": 123456789
}
}
```
Quando os objetos aninhados diferem, o delta contém o caminho para a raiz.
```
{
"state": {
"desired": {
"lights": {
"color": {
"r": 255,
"g": 255,
"b": 255
}
}
},
"reported": {
"lights": {
"color": {
"r": 255,
"g": 0,
"b": 255
}
}
},
"delta": {
"lights": {
"color": {
"g": 255
}
}
}
},
"version": 18,
"timestamp": 123456789
}
```
O serviço Sombra do Dispositivo calcula o delta Percorrendo cada campo no estado `desired` e comparando-o com o estado `reported`.
As matrizes são processadas como valores. Se uma matriz na seção `desired` não corresponder à matriz na seção `reported`, toda a matriz desejada será copiada para o delta.
## Versionamento de documentos de sombra
O serviço Sombra do Dispositivo é compatível com o versionamento em cada mensagem de atualização, tanto de solicitação quanto de resposta. Isso indica que a cada atualização de uma sombra, a versão do documento JSON é incrementada. Isso garante duas objetos:
+ Um cliente poderá receber um erro se tentar substituir um shadow usando um número da versão mais antigo. O cliente é informado de que deve sincronizar novamente antes de atualizar uma shadow de dispositivo.
+ Um cliente poderá decidir não atuar em uma mensagem recebida se a mensagem tiver uma versão inferior à versão armazenada pelo cliente.
Um cliente pode ignorar a correspondência de versão não incluindo uma versão no documento de sombra.
## Tokens de cliente em documentos de sombra
Você pode usar um token cliente com um sistema de mensagens com base em MQTT para verificar se o mesmo token cliente está contido em uma solicitação e em uma resposta de solicitação. Isso garante que a resposta e a solicitação estejam associadas.
**nota**
O token do cliente pode ter até 64 bytes. Um token de cliente com mais de 64 bytes resulta em uma resposta 400 (Solicitação inválida) e na mensagem de erro *clientToken inválido*.
## Propriedades vazias do documento de sombra
As propriedades `reported` e `desired` em um documento de sombra podem estar vazias ou omitidas quando não se aplicam ao estado da sombra atual. Por exemplo, um documento de sombra contém uma propriedade `desired` somente se tiver um estado desejado. Veja a seguir um exemplo válido de um documento de estado sem a propriedade `desired`:
```
{
"reported" : { "temp": 55 }
}
```
A propriedade `reported` também pode estar vazia, como se a sombra não tivesse sido atualizada pelo dispositivo:
```
{
"desired" : { "color" : "RED" }
}
```
Se uma atualização fizer com que as propriedades `desired` ou `reported` se tornem nulas, ela será removida do documento. Veja a seguir como remover a propriedade `desired` definindo-a como `null`. Você pode fazer isso quando um dispositivo atualiza seu estado, por exemplo.
```
{
"state": {
"reported": {
"color": "red"
},
"desired": null
}
}
```
Um documento de sombra também pode ter nenhuma propriedade `desired` ou `reported`, tornando o documento de sombra vazio. Este é um exemplo de um documento de sombra vazio, mas válido.
```
{
}
```
## Valores de matriz em documentos de sombra
As shadows dão suporte a matrizes, mas as trata como valores normais em que uma atualização em uma matriz substitui toda a matriz. Não é possível atualizar parte de uma matriz.
Estado inicial:
```
{
"desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}
```
Atualização:
```
{
"desired" : { "colors" : ["RED"] }
}
```
Estado final:
```
{
"desired" : { "colors" : ["RED"] }
}
```
As matrizes não podem ter valores nulos. Por exemplo, a matriz a seguir não é válida e será rejeitada.
```
{
"desired" : {
"colors" : [ null, "RED", "GREEN" ]
}
}
```
# Mensagens de erro da Sombra do Dispositivo
O serviço Sombra do Dispositivo publica uma mensagem no tópico de erro (por MQTT) quando uma tentativa de alterar o documento de estado falha. Essa mensagem só é emitida como uma resposta a uma solicitação de publicação em um dos tópicos `$aws` reservados. Se o cliente atualizar o documento usando a API REST, ele receberá o código de erro HTTP como parte da resposta, e nenhuma mensagem de erro MQTT será emitida.
****
| Código de erro HTTP | Mensagens de erro |
| --- | --- |
| 400 (Solicitação inválida) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/device-shadow-error-messages.html) |
| 401 (Não autorizado) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/device-shadow-error-messages.html) |
| 403 (Proibido) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/device-shadow-error-messages.html) |
| 404 (Não encontrado) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/device-shadow-error-messages.html) |
| 409 (Conflito) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/device-shadow-error-messages.html) |
| 413 (Carga útil muito grande) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/device-shadow-error-messages.html) |
| 415 (Tipo de mídia incompatível) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/device-shadow-error-messages.html) |
| 429 (Muitas solicitações) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/device-shadow-error-messages.html) |
| 500 (Erro interno do servidor) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/device-shadow-error-messages.html) |