Gerenciar os gêmeos digitais do IoT Plug and Play
O IoT Plug and Play dá suporte às operações Obter gêmeo digital ou Atualizar gêmeo digital para gerenciar os gêmeos digitais. Você pode usar as APIs REST ou um dos SDKs de serviço.
Atualizar um gêmeo digital
Um dispositivo IoT Plug and Play implementa um modelo descrito por DTDL (Digital Twins Definition Language). Os desenvolvedores de soluções podem usar a API de atualização de gêmeo digital para atualizar o estado do componente e as propriedades do gêmeo digital.
O dispositivo IoT Plug and Play usado como um exemplo neste artigo implementa o modelo de Controlador de Temperatura com componentes de Termostato.
O snippet a seguir mostra a resposta a uma solicitação Obter gêmeo digital formatada como um objeto JSON. Para saber mais sobre o formato do gêmeo digital digitais, confira Noções básicas sobre gêmeos digitais do IoT Plug and Play:
{
"$dtId": "sample-device",
"serialNumber": "alwinexlepaho8329",
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 20.4,
"$metadata": {
"targetTemperature": {
"desiredValue": 20.4,
"desiredVersion": 4,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
},
"maxTempSinceLastReboot": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
},
"$metadata": {
"$model": "dtmi:com:example:TemperatureController;1",
"serialNumber": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}
Os gêmeos digitais permitem que você atualize um componente ou propriedade inteira usando um patch JSON.
Por exemplo, você pode atualizar a propriedade targetTemperature da seguinte maneira:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
A atualização anterior define o valor desejado de uma propriedade no $metadata do nível de componente correspondente, conforme mostrado no snippet a seguir. O Hub IoT atualiza a versão desejada da propriedade:
"thermostat1": {
"targetTemperature": 20.4,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.4,
"desiredVersion": 5,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
}
}
}
Adicionar, substituir ou remover um componente
Operações de nível de componente exigem um marcador de objeto vazio $metadata dentro do valor.
Uma operação de adicionar ou substituir componente define os valores desejados de todas as propriedades fornecidas. Ele também limpa os valores desejados para as propriedades graváveis não fornecidas com a atualização.
A remoção de um componente limpa os valores desejados de todas as propriedades graváveis presentes. Um dispositivo eventualmente sincroniza essa remoção e para de relatar as propriedades individuais. O componente é, então, removido do gêmeo digital.
O seguinte exemplo de patch JSON mostra como adicionar, substituir ou remover um componente:
[
{
"op": "add",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"anotherWritableProperty": 42,
"$metadata": {}
}
},
{
"op": "replace",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"$metadata": {}
}
},
{
"op": "remove",
"path": "/thermostat2"
}
]
Adicionar, substituir ou remover uma propriedade
Uma operação de adicionar ou substituir define o valor desejado de uma propriedade. O dispositivo pode sincronizar o estado e relatar uma atualização do valor junto com um código, versão e descrição ack.
A remoção de uma propriedade limpará o valor desejado da propriedade se ela estiver definida. Em seguida, o dispositivo pode parar de relatar essa propriedade e ela é removida do componente. Se essa propriedade for a última no componente, o componente também será removido.
O seguinte exemplo de patch JSON mostra como adicionar, substituir ou remover uma propriedade dentro de um componente:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
Regras para definir o valor desejado de uma propriedade de gêmeo digital
Nome
O nome de um componente ou propriedade deve ser um nome DTDL válido.
Os caracteres permitidos são a-z, A-Z, 0-9 (não como o primeiro caractere) e sublinhado (não como o primeiro ou último caractere).
Um nome pode ter de 1 a 64 caracteres.
Valor da propriedade
O valor deve ser uma propriedade DTDL válida.
Há suporte para todos os tipos primitivos. Há suporte para tipos complexos, enums, mapas e objetos. Para saber mais, consulte Esquemas DTDL.
Não há suporte nas propriedades a nenhuma matriz nem um esquema complexo com uma matriz.
Há suporte a uma profundidade máxima de cinco níveis para um objeto complexo.
Todos os nomes de campo dentro de objetos complexos devem ser nomes DTDL válidos.
Todas as chaves de mapa devem ter nomes DTDL válidos.
Solucionar erros da API de atualização do gêmeo digital
A API do gêmeo digital lança a seguinte mensagem de erro genérica:
ErrorCode:ArgumentInvalid;'{propertyName}' exists within the device twin and is not digital twin conformant property. Please refer to aka.ms/dtpatch to update this to be conformant.
Se você encontrar esse erro, verifique se o patch de atualização segue as regras para definir o valor desejado de uma propriedade de gêmeo digital.
Ao atualizar um componente, verifique se o marcador $metadata de objeto vazio está definido.
As atualizações poderão falhar se os valores relatados de um dispositivo não estiverem em conformidade com as convenções do IoT Plug and Play.
Próximas etapas
Agora que você sabe mais sobre os gêmeos digitais, confira mais alguns recursos: