Gerencie gêmeos digitais IoT Plug and Play
O IoT Plug and Play suporta operações Get digital twin e Update digital twin para gerenciar 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 pela Digital Twins Definition Language (DTDL). Os desenvolvedores de soluções podem usar a API Update Digital Twin para atualizar o estado do componente e as propriedades do gêmeo digital.
O dispositivo IoT Plug and Play usado como exemplo neste artigo implementa o modelo de controlador de temperatura com componentes de termostato .
O trecho a seguir mostra a resposta a uma solicitação de gêmeo digital Get formatada como um objeto JSON. Para saber mais sobre o formato de gêmeos digitais, consulte Compreender os gêmeos digitais 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 atualizar um componente ou propriedade inteira usando um patch JSON.
Por exemplo, você pode atualizar a targetTemperature propriedade da seguinte maneira:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
A atualização anterior define o valor desejado de uma propriedade no nível $metadata de componente correspondente, conforme mostrado no trecho 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
As operações no nível do componente exigem um marcador de objeto $metadata vazio 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 quaisquer 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 exemplo de patch JSON a seguir 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 adição ou substituição define o valor desejado de uma propriedade. O dispositivo pode sincronizar o estado e relatar uma atualização do valor, juntamente com um ack código, versão e descrição.
A remoção de uma propriedade limpa o valor desejado da propriedade, se ela estiver definida. O dispositivo pode então parar de relatar essa propriedade e ela é removida do componente. Se essa propriedade for a última do componente, o componente também será removido.
O exemplo de patch JSON a seguir 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 do imóvel
O valor deve ser uma propriedade DTDL válida.
Todos os tipos primitivos são suportados. Dentro de tipos complexos, enums, mapas e objetos são suportados. Para saber mais, consulte Esquemas DTDL.
As propriedades não suportam array ou qualquer esquema complexo com um array.
Uma profundidade máxima de cinco níveis é suportada 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 ser nomes DTDL válidos.
Solucionar erros de atualização da API de gêmeo digital
A API de 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ê vir 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 de $metadata de objeto vazio está definido.
As atualizações podem falhar se os valores relatados de um dispositivo não estiverem em conformidade com as convenções plug and play da IoT.
Próximos passos
Agora que você já aprendeu sobre gêmeos digitais, aqui estão mais alguns recursos: