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

# Documentos do serviço Sombra do Dispositivo
<a name="device-shadow-document"></a>

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
<a name="device-shadow-document-syntax"></a><a name="device-shadow-example"></a>

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
<a name="device-shadow-example-request-json"></a>

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
<a name="device-shadow-example-response-json"></a>

Os documentos de estado de resposta têm o seguinte formato, dependendo do tipo de resposta.

#### Documento de estado da resposta /accepted
<a name="device-shadow-example-response-json-accepted"></a>

```
{
    "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
<a name="device-shadow-example-response-json-delta"></a>

```
{
    "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
<a name="device-shadow-example-response-json-documents"></a>

```
{
  "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
<a name="device-shadow-example-response-json-properties"></a>
+ `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
<a name="device-shadow-example-error-json"></a>

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
<a name="device-shadow-list-json"></a>

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
<a name="document-structure"></a>

Um documento de shadow de dispositivo tem as seguintes propriedades:

`state`  <a name="state"></a>  
`desired`  <a name="desired"></a>
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`  <a name="reported"></a>
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`  <a name="metadata"></a>
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`  <a name="timestamp"></a>
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`  <a name="clientToken"></a>
Uma string exclusiva do dispositivo que permite associar respostas com as solicitações em um ambiente MQTT.

`version`  <a name="version"></a>
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
<a name="delta-state"></a><a name="observing-state-changes"></a>

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

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
<a name="client-token"></a>

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
<a name="device-shadow-empty-fields"></a>

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

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