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.

Exemplos de documentos de sombra

O serviço Sombra do Dispositivo usa estes documentos nas operações UPDATE, GET e DELETE usando a API REST ou as Mensagens de publicação/assinatura do MQTT.

Exemplos

• Documento de estado de solicitação
• Documentos de estado da resposta
• Documento de resposta de erro
• Documento de resposta da lista de nomes de sombra

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.

  • delta — Presente apenas se os dados desired diferirem dos dados atuais da sombra reported.

• 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 hora da Epoch pela qual 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 ter mais informações, consulte Mensagens de erro da Sombra do Dispositivo.

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.

nota

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.

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 ter mais informações, consulte Exemplos de documentos de sombra.

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