Interagir com sombras - AWS IoT Core
Suporte ao protocoloSolicitar e declarar o estadoAtualizar uma shadowRecuperar um documento de shadowExcluir dados de sombra

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

Interagir com sombras

Este tópico descreve as mensagens associadas a cada um dos três métodos que o AWS IoT fornece para trabalhar com sombras. Esses métodos incluem o seguinte:

UPDATE

Cria uma sombra, se ela não existir, ou atualiza o conteúdo de uma sombra existente com as informações de estado fornecidas no corpo da mensagem. O AWS IoT registra um carimbo de data/hora com cada atualização para indicar quando o estado foi atualizado pela última vez. Quando o estado da sombra muda, AWS IoT envia /delta mensagens para todos os assinantes do MQTT com a diferença entre os reported estados desired e os. Os dispositivos ou aplicativos que recebem uma mensagem /delta podem executar ações com base na diferença. Por exemplo, um dispositivo pode atualizar seu estado para o estado desejado, ou um aplicativo pode atualizar sua interface do usuário (UI) para mostrar a alteração no estado do dispositivo.

GET

Recupera um documento de sombra atual que contém o estado completo da sombra, incluindo os metadados.

DELETE

Exclui a sombra do dispositivo e o seu conteúdo.

Você não pode restaurar um documento de sombra do dispositivo excluído, mas pode criar um novo documento de sombra do dispositivo com o nome de um documento de sombra do dispositivo excluído. Se você criar um documento de sombra do dispositivo com o mesmo nome daquele que foi excluído nas últimas 48 horas, o número da versão do novo documento de sombra do dispositivo seguirá o do excluído. Se um documento de sombra do dispositivo tiver sido excluído por mais de 48 horas, o número da versão de um novo documento de sombra do dispositivo com o mesmo nome será 0.

Suporte ao protocolo

AWS IoT suporta MQTT e uma API REST sobre protocolos HTTPS para interagir com sombras. AWS IoT fornece um conjunto de tópicos reservados de solicitação e resposta para ações de publicação e assinatura do MQTT. Dispositivos e aplicativos devem se inscrever nos tópicos de resposta antes de publicar um tópico de solicitação para obter informações sobre como a solicitação AWS IoT foi tratada. Para obter mais informações, consulte API REST da Sombra do Dispositivo e Tópicos MQTT da Sombra do Dispositivo.

Solicitar e declarar o estado

Ao projetar sua solução de IoT usando AWS IoT sombras, você deve determinar os aplicativos ou dispositivos que solicitarão alterações e aqueles que as implementarão. Normalmente, um dispositivo implementa e relata alterações na sombra e os aplicativos e os serviços respondem e solicitam alterações na sombra. Sua solução pode ser diferente, mas os exemplos neste tópico pressupõem que o aplicativo cliente ou o serviço solicita alterações na sombra e o dispositivo executa as alterações e relata-as de volta à sombra.

Atualizar uma shadow

Seu aplicativo ou serviço pode atualizar o estado de uma sombra usando a API UpdateThingShadow ou publicando no tópico /update. As atualizações afetam apenas os campos especificados na solicitação.

Atualizar uma sombra quando um cliente solicita uma alteração de estado

Quando um cliente solicita uma alteração de estado em uma sombra usando o protocolo MQTT

  1. O cliente deve ter um documento da sombra atual para que ele possa identificar as propriedades a serem alteradas. Consulte a ação /get para saber como obter o documento de sombra atual.

  2. O cliente assina estes tópicos MQTT:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  3. O cliente publica um tópico de solicitação $aws/things/thingName/shadow/name/shadowName/update com um documento de estado que contém o estado desejado da sombra. Somente as propriedades a serem alteradas precisam ser incluídas no documento. Este é um exemplo de um documento com o estado desejado.

    {
  "state": {
    "desired": {
      "color": {
        "r": 10
      },
      "engine": "ON"
    }
  }
}

  4. Se a solicitação de atualização for válida, AWS IoT atualiza o estado desejado na sombra e publica mensagens sobre estes tópicos:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    A mensagem /update/accepted contém um documento de sombra Documento de estado da resposta /accepted, e a mensagem /update/delta contém um documento de sombra Documento de estado da resposta /delta.

  5. Se a solicitação de atualização não for válida, AWS IoT publica uma mensagem com o $aws/things/thingName/shadow/name/shadowName/update/rejected tópico com um documento Documento de resposta de erro paralelo que descreve o erro.

Quando um cliente solicita uma alteração de estado em uma sombra usando a API

  1. O cliente chama a API UpdateThingShadow com um documento de estado Documento de estado de solicitação como o corpo da mensagem.

  2. Se a solicitação for válida, AWS IoT retornará um código HTTP de resposta bem-sucedida e um documento Documento de estado da resposta /accepted paralelo como corpo da mensagem de resposta.

    AWS IoT também publicará uma mensagem MQTT no $aws/things/thingName/shadow/name/shadowName/update/delta tópico com um documento Documento de estado da resposta /delta paralelo para todos os dispositivos ou clientes que a assinarem.

  3. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e Documento de resposta de erro como corpo da mensagem de resposta.

Quando o dispositivo recebe o estado /desired no tópico /update/delta, ele faz as alterações desejadas no dispositivo. Depois, ele envia uma mensagem ao tópico /update para relatar seu estado atual para a sombra.

Atualizar uma sombra quando um dispositivo relata seu estado atual

Quando um dispositivo relata seu estado atual para a sombra usando o protocolo MQTT

  1. O dispositivo deve assinar estes tópicos MQTT antes de atualizar a sombra:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  2. O dispositivo relata seu estado atual publicando uma mensagem no tópico $aws/things/thingName/shadow/name/shadowName/update que relata o estado atual, como neste exemplo.

    {
    "state": {
        "reported" : {
            "color" : { "r" : 10 },
            "engine" : "ON"
        }
    }
}

  3. Se AWS IoT aceitar a atualização, ele publicará uma mensagem nos $aws/things/thingName/shadow/name/shadowName/update/accepted tópicos com um documento Documento de estado da resposta /accepted paralelo.

  4. Se a solicitação de atualização não for válida, AWS IoT publica uma mensagem com o $aws/things/thingName/shadow/name/shadowName/update/rejected tópico com um documento Documento de resposta de erro paralelo que descreve o erro.

Quando um dispositivo relata seu estado atual para a sombra usando a API

  1. O dispositivo chama a API UpdateThingShadow com um documento de estado Documento de estado de solicitação como o corpo da mensagem.

  2. Se a solicitação for válida, AWS IoT atualiza a sombra e retorna um código de resposta HTTP bem-sucedida com um documento Documento de estado da resposta /accepted paralelo como corpo da mensagem de resposta.

    AWS IoT também publicará uma mensagem MQTT no $aws/things/thingName/shadow/name/shadowName/update/delta tópico com um documento Documento de estado da resposta /delta paralelo para todos os dispositivos ou clientes que a assinarem.

  3. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e Documento de resposta de erro como corpo da mensagem de resposta.

Bloqueio otimista

Você pode usar a versão do documento de estado para garantir que está atualizando a versão mais recente de um documento de shadow de dispositivo. Ao fornecer uma versão com uma solicitação de atualização, o serviço rejeitará a solicitação com um código de resposta de conflito HTTP 409 se a versão atual do documento de estado não corresponder à versão fornecida. O código de resposta de conflito também pode ocorrer em qualquer API que modifique ThingShadow, incluindo DeleteThingShadow.

Por exemplo: .

Documento inicial:

{
  "state": {
    "desired": {
      "colors": [
        "RED",
        "GREEN",
        "BLUE"
      ]
    }
  },
  "version": 10
}

Atualização: (versão não corresponde, a solicitação será rejeitada)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 9
}

Resultado:

{
  "code": 409,
  "message": "Version conflict",
  "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}

Atualização: (a versão corresponde; a solicitação será aceita)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 10
}

Estado final:

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 11
}

Recuperar um documento de shadow

Você pode recuperar um documento de sombra usando a API GetThingShadow ou assinando e publicando no tópico /get. Isso recupera um documento de sombra completo, incluindo qualquer delta entre os estados reported e desired. O procedimento para esta tarefa é o mesmo para um dispositivo ou para um cliente que faz a solicitação.

Como recuperar um documento de sombra usando o protocolo MQTT

  1. O dispositivo ou o cliente deve assinar estes tópicos MQTT antes de atualizar a sombra:

    • $aws/things/thingName/shadow/name/shadowName/get/accepted

    • $aws/things/thingName/shadow/name/shadowName/get/rejected

  2. O dispositivo ou o cliente publica uma mensagem no tópico $aws/things/thingName/shadow/name/shadowName/get com um corpo de mensagem vazio.

  3. Se a solicitação for bem-sucedida, AWS IoT publica uma mensagem no $aws/things/thingName/shadow/name/shadowName/get/accepted tópico com um Documento de estado da resposta /accepted no corpo da mensagem.

  4. Se a solicitação não for válida, AWS IoT publica uma mensagem no $aws/things/thingName/shadow/name/shadowName/get/rejected tópico com um Documento de resposta de erro no corpo da mensagem.

Como recuperar um documento de sombra usando uma API REST

  1. O dispositivo ou o cliente chama a API GetThingShadow com um corpo de mensagem vazio.

  2. Se a solicitação for válida, AWS IoT retornará um código HTTP de resposta bem-sucedida com um documento Documento de estado da resposta /accepted paralelo como corpo da mensagem de resposta.

  3. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e Documento de resposta de erro como corpo da mensagem de resposta.

Excluir dados de sombra

Existem duas maneiras de excluir dados de sombra: você pode excluir propriedades específicas no documento de sombra e excluir a sombra completamente.

  • Para excluir propriedades específicas de uma sombra, atualize a sombra. No entanto, defina o valor das propriedades que você deseja excluir como null. Os campos com um valor de null são removidos do documento de sombra.

  • Para excluir a sombra inteira, use a API DeleteThingShadow ou publique no tópico /delete.

nota

A exclusão de uma sombra não redefine seu número de versão para zero de uma só vez. Ele será redefinido para zero após 48 horas.

Excluir uma propriedade de um documento de sombra

Como excluir uma propriedade de uma sombra usando o protocolo MQTT

  1. O dispositivo ou o cliente deve ter um documento de sombra atual para que possa identificar as propriedades a serem alteradas. Consulte Recuperar um documento de shadow para obter informações sobre como obter o documento de sombra atual.

  2. O dispositivo ou o cliente assina estes tópicos MQTT:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

  3. O dispositivo ou o cliente publica um tópico de solicitação $aws/things/thingName/shadow/name/shadowName/update com um documento de estado que atribui valores null às propriedades da sombra a ser excluída. Somente as propriedades a serem alteradas precisam ser incluídas no documento. Este é um exemplo de um documento que exclui a propriedade engine.

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  4. Se a solicitação de atualização for válida, AWS IoT excluirá as propriedades especificadas na sombra e publicará uma mensagem com o $aws/things/thingName/shadow/name/shadowName/update/accepted tópico com um documento Documento de estado da resposta /accepted paralelo no corpo da mensagem.

  5. Se a solicitação de atualização não for válida, AWS IoT publica uma mensagem com o $aws/things/thingName/shadow/name/shadowName/update/rejected tópico com um documento Documento de resposta de erro paralelo que descreve o erro.

Como excluir uma propriedade de uma sombra usando a API REST

  1. O dispositivo ou o cliente chama a API UpdateThingShadow com um Documento de estado de solicitação que atribui valores null às propriedades da sombra a ser excluída. Inclua apenas as propriedades que você deseja excluir no documento. Este é um exemplo de um documento que exclui a propriedade engine.

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  2. Se a solicitação for válida, AWS IoT retornará um código HTTP de resposta bem-sucedida e um documento Documento de estado da resposta /accepted paralelo como corpo da mensagem de resposta.

  3. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e Documento de resposta de erro como corpo da mensagem de resposta.

Excluir uma shadow

Veja a seguir algumas considerações ao excluir a sombra de um dispositivo.

  • Definir o estado da sombra do dispositivo como null não exclui a sombra. A versão da sombra será incrementada na próxima atualização.

  • A exclusão de uma sobra de dispositivo não exclui o objeto. A exclusão de um objeto não exclui a sombra do dispositivo correspondente.

  • A exclusão de uma sombra não redefine seu número de versão para zero de uma só vez. Ele será redefinido para zero após 48 horas.

Como excluir uma sombra usando o protocolo MQTT

  1. O dispositivo ou o cliente assina estes tópicos MQTT:

    • $aws/things/thingName/shadow/name/shadowName/delete/accepted

    • $aws/things/thingName/shadow/name/shadowName/delete/rejected

  2. O dispositivo ou o cliente publica um $aws/things/thingName/shadow/name/shadowName/delete com um buffer de mensagens vazio.

  3. Se a solicitação de exclusão for válida, AWS IoT excluirá a sombra e publicará uma mensagem com o $aws/things/thingName/shadow/name/shadowName/delete/accepted tópico e um Documento de estado da resposta /accepted documento-sombra abreviado no corpo da mensagem. Este é um exemplo de mensagem de exclusão aceita:

    {
  "version": 4,
  "timestamp": 1591057529
}

  4. Se a solicitação de atualização não for válida, AWS IoT publica uma mensagem com o $aws/things/thingName/shadow/name/shadowName/delete/rejected tópico com um documento Documento de resposta de erro paralelo que descreve o erro.

Como excluir uma sombra usando a API REST

  1. O dispositivo ou o cliente chama a API DeleteThingShadow com um buffer de mensagens vazio.

  2. Se a solicitação for válida, AWS IoT retornará um código de resposta de sucesso HTTP Documento de estado da resposta /accepted e um Documento de estado da resposta /accepted documento-sombra abreviado no corpo da mensagem. Este é um exemplo de mensagem de exclusão aceita:

    {
  "version": 4,
  "timestamp": 1591057529
}

  3. Se a solicitação não for válida, AWS IoT retornará um código de resposta de erro HTTP e Documento de resposta de erro como corpo da mensagem de resposta.