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