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

# Tópicos MQTT da Sombra do Dispositivo
<a name="device-shadow-mqtt"></a>

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
<a name="get-pub-sub-topic"></a>

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
<a name="get-policy"></a>

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
<a name="get-accepted-pub-sub-topic"></a>

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
<a name="get-accepted-policy"></a>

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
<a name="get-rejected-pub-sub-topic"></a>

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
<a name="get-rejected-policy"></a>

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
<a name="update-pub-sub-topic"></a>

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
<a name="update-policy"></a>

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
<a name="update-delta-pub-sub-topic"></a>

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
<a name="update-delta-rules"></a>
+ 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
<a name="update-delta-policy"></a>

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
<a name="update-accepted-pub-sub-topic"></a>

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
<a name="update-accepted-policy"></a>

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
<a name="update-documents-pub-sub-topic"></a>

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
<a name="update-documents-policy"></a>

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
<a name="update-rejected-pub-sub-topic"></a>

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
<a name="update-rejected-policy"></a>

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
<a name="delete-pub-sub-topic"></a>

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
<a name="delete-policy"></a>

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
<a name="delete-accepted-pub-sub-topic"></a>

AWS IoT publica uma mensagem neste tópico quando a sombra de um dispositivo é excluída:

```
ShadowTopicPrefix/delete/accepted
```

### Exemplo de política
<a name="delete-accepted-policy"></a>

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
<a name="delete-rejected-pub-sub-topic"></a>

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
<a name="delete-rejected-policy"></a>

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"
            ]
        }
    ]
}
```