Analisar a configuração do dispositivo usando os dispositivos gêmeos no Hub IoT do Azure
A capacidade de configurar dispositivos no seu serviço de back-end é um componente fundamental da maioria das soluções de gerenciamento de dispositivo.
Para sincronizar informações de estado entre um dispositivo e um Hub IoT, você usa dispositivos gêmeos. Um dispositivo gêmeo é um documento JSON associado a um dispositivo específico e armazenado pelo Hub IoT na nuvem, onde você pode consultá-lo. Um dispositivo gêmeo contém as seguintes informações:
- Uma propriedade desejada é definida por um aplicativo de back-end e lida por um dispositivo.
- Uma propriedade relatada é definida por um dispositivo e lida por um aplicativo de back-end.
- Uma marcação é definida por um aplicativo de back-end e nunca é enviada para o dispositivo. Use as marcações para organizar os dispositivos. Por exemplo, uma marcação pode conter um local ou uma categoria do dispositivo. Você pode atribuir mais de uma marcação por dispositivo.
Propriedade de dispositivo gêmeo
Considere a seguinte seção properties de um documento de dispositivo gêmeo:
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"$metadata" : {...},
"$version": 4
}
}
Neste exemplo, as propriedades desejadas e relatadas do dispositivo gêmeo telemetryConfig são usadas pelo back-end da solução e pelo aplicativo do dispositivo para sincronizar a configuração de telemetria para esse dispositivo. Uma atualização da configuração do dispositivo pode ser implementada da seguinte maneira:
- O back-end da solução define a propriedade
desiredcom o valor de configuração desejado. - O aplicativo do dispositivo é notificado sobre a alteração imediatamente, se estiver conectado, ou na primeira reconexão. Em seguida, o aplicativo do dispositivo reporta a configuração atualizada (ou uma condição de erro usando a propriedade
status). - O back-end da solução pode acompanhar os resultados da operação de configuração em vários dispositivos consultando os dispositivos gêmeos.
Operações de back-end
O back-end da solução funciona no dispositivo gêmeo usando as seguintes operações atômicas, expostas por meio de HTTPS:
Recuperar dispositivo gêmeo por ID. Essa operação retorna o documento do dispositivo gêmeo, incluindo marcas e propriedades do sistema desejadas e reportadas.
Atualizar parcialmente o dispositivo gêmeo. Essa operação permite que o back-end da solução atualize parcialmente as marcações ou propriedades desejadas em um dispositivo gêmeo. A atualização parcial é expressa como um documento JSON que adiciona ou atualiza qualquer propriedade. As propriedades definidas como
nullforam removidas. O exemplo a seguir cria uma nova propriedade desejada com o valor{"newProperty": "newValue"}, substitui o valor existente deexistingPropertypor"otherNewValue"e removeotherOldProperty. Nenhuma outra alteração é feitas nas propriedades desejadas ou marcas existentes:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Substituir propriedades desejadas. Esta operação permite que o back-end da solução substitua completamente todas as suas propriedades desejadas existentes e substitui um novo documento JSON por
properties/desired.Substituir marcas. Esta operação permite que o back-end da solução substitua completamente todas as marcas existentes e substitui um novo documento JSON por
tags.Receba notificações gêmeas. Esta operação permite que o back-end de solução seja notificado quando o gêmeo é modificado. Para fazer isso, sua solução de IoT precisa para criar uma rota e definir a Fonte de Dados como twinChangeEvents. Por padrão, essa rota não existe, e portanto nenhuma notificação gêmea é enviada. Se a taxa de alteração for alta demais ou então por outros motivos como falhas internas, o Hub IoT poderá enviar apenas uma notificação contendo todas as alterações. Portanto, se o aplicativo precisar de auditoria e registro em log confiável de todos os estados intermediários, será necessário usar mensagens de dispositivo para nuvem. A mensagem de notificação gêmea inclui propriedades e corpo.
Propriedades. As propriedades de uma mensagem de notificação de um gêmeo são mostradas na tabela a seguir. As propriedades do sistema de mensagens são prefixadas com o símbolo $.
Nome
Valor
$content-type
aplicativo/json
$iothub-enqueuedtime
Data e hora em que a notificação foi enviada.
$iothub-message-source
twinChangeEvents
$content-encoding
utf-8
deviceId
ID do dispositivo.
hubName
Nome do Hub IoT que gerou o evento.
operationTimestamp
Carimbo de data/hora ISO8601 da operação.
iothub-message-schema
O esquema de mensagem associado à categoria de evento, por exemplo, deviceLifecycleNotification.
moduleid
A ID do módulo. Essa propriedade é saída somente para eventos de ciclo de vida do módulo e de alteração do gêmeo.
opType
"replaceTwin" ou "updateTwin"
Corpo. Esta seção de uma mensagem de notificação de um gêmeo inclui todas as alterações do gêmeo em um formato JSON. Ele usa o mesmo formato de um patch, com a diferença de que pode conter todas as seções de gêmeo: marcações, properties.reported, properties.desired, e que contém os elementos
$metadata.
Além dessas operações, o back-end da solução pode:
- Consulte os dispositivos gêmeos usando a linguagem de consulta do Hub IoT semelhante a SQL.
- Execute operações em conjuntos grandes de dispositivos gêmeos usando trabalhos.
Operações de dispositivo
O aplicativo do dispositivo opera no dispositivo gêmeo usando as seguintes operações atômicas:
- Recuperar dispositivo gêmeo. Essa operação retorna o documento do dispositivo gêmeo (incluindo propriedades do sistema desejadas e reportadas) para o dispositivo conectado no momento.
Observação
As marcas não ficam visíveis para os aplicativos do dispositivo.
- Atualizar parcialmente as propriedades reportadas. Essa operação permite a atualização parcial das propriedades reportadas do dispositivo conectado no momento. Esta operação usa o mesmo formato de atualização JSON que a solução de back-end usa para uma atualização parcial de propriedades desejadas.
- Observar as propriedades desejadas. O dispositivo conectado no momento pode optar por ser notificado sobre atualizações para as propriedades desejadas quando elas ocorrem. O dispositivo recebe a mesma forma de atualização (substituição total ou parcial) executada pelo back-end da solução.
Todas as operações anteriores exigem a permissão DeviceConnect.
Os SDKs de dispositivo do Hub IoT do Azure facilitam o uso das operações anteriores em muitas linguagens e plataformas.
Metadados do dispositivo gêmeo
O Hub IoT mantém o carimbo de data e hora da última atualização de cada objeto JSON nas propriedades desejadas e reportadas do dispositivo gêmeo. Os carimbos de data e hora estão em UTC e são codificados no formato ISO8601YYYY-MM-DDTHH:MM:SS.mmmZ.
Por exemplo:
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2019-08-30T16:24:48.789Z"
},
"$lastUpdated": "2019-08-30T16:24:48.789Z"
},
"$lastUpdated": "2019-08-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": {
"$lastUpdated": "2019-08-31T16:35:48.789Z"
},
"$lastUpdated": "2019-08-31T16:35:48.789Z"
},
"$lastUpdated": "2019-08-31T16:35:48.789Z"
},
"$version": 123
}
}
Essas informações são armazenadas em cada nível (não apenas nas folhas da estrutura JSON) a fim de preservar as atualizações que removem chaves de objeto.
Simultaneidade otimista
Marcas, propriedades desejadas e reportadas oferecem suporte à simultaneidade otimista. Marcas tem uma Etag, de acordo com RFC7232, que representa a representação JSON da marca. Você pode usar ETags em operações de atualização condicionais do back-end da solução para garantir a consistência.
As propriedades desejadas e relatadas do dispositivo gêmeo não têm ETags, mas têm um valor $version que tem a garantia de ser incremental. De forma semelhante a uma ETag, a versão pode ser usada pela parte de atualização para impor a consistência das atualizações. Por exemplo, um aplicativo de dispositivo para uma propriedade relatada ou o back-end de solução para uma propriedade desejada.
Versões também são úteis quando um agente observador (por exemplo, o aplicativo do dispositivo que observa as propriedades desejadas) deve reconciliar corridas entre o resultado de uma operação de recuperação e uma notificação de atualização.
Fluxo de reconexão do dispositivo
O Hub IoT não preserva notificações de atualização de propriedades desejadas para dispositivos desconectados. Acontece que um dispositivo que está se conectando deve recuperar o documento completo de propriedades desejadas, além de se inscrever para receber notificações de atualização. Considerando a possibilidade de corridas entre notificações de atualização e recuperação completa, o seguinte fluxo deve ser garantido:
- O aplicativo de dispositivo conecta-se a um Hub IoT.
- O aplicativo de dispositivo se inscreve para as notificações de atualização de propriedades desejadas .
- O aplicativo de dispositivo recupera o documento completo para as propriedades desejadas.
O aplicativo de dispositivo pode ignorar todas as notificações com $version menor ou igual à versão do documento recuperado completo. Essa abordagem é possível porque o Hub IoT garante que as versões sempre aumentam.
Observação
Essa lógica já está implementada nos SDKs de dispositivo do Hub IoT do Azure. Essa descrição será útil somente se o aplicativo de dispositivo não puder usar qualquer um dos SDKs do dispositivo IoT do Azure, e deve programar a interface MQTT diretamente.