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á.

# Usar sombras em dispositivos
<a name="device-shadow-comms-device"></a>

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
<a name="device-shadow-comms-device-first-connect"></a>

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
<a name="device-shadow-comms-device-while-connected"></a>

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
<a name="device-shadow-comms-device-reconnect"></a>

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.