Gestire Plug and Play IoT gemelli digitali
Plug and Play IoT supporta Ottenere gemelli digitali e aggiornare le operazioni del gemello digitale per gestire gemelli digitali. È possibile usare le API REST o uno degli SDK del servizio.
Aggiornare un gemello digitale
Un dispositivo Plug and Play IoT implementa un modello descritto da DTDL (Digital Twins Definition Language). Gli sviluppatori di soluzioni possono usare l'API Update Digital Twin per aggiornare lo stato del componente e le proprietà del gemello digitale.
Il dispositivo Plug and Play IoT usato come esempio in questo articolo implementa il modello Temperature Controller con i componenti Termostato.
Il frammento di codice seguente mostra la risposta a una richiesta Get digital twin formattata come oggetto JSON. Per altre informazioni sul formato del gemello digitale, vedere Informazioni Plug and Play IoT gemelli digitali:
{
"$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"
}
}
}
I gemelli digitali consentono di aggiornare un intero componente o proprietà usando una patch JSON.
Ad esempio, è possibile aggiornare la targetTemperature proprietà nel modo seguente:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
L'aggiornamento precedente imposta il valore desiderato di una proprietà nel livello $metadata di componente corrispondente, come illustrato nel frammento di codice seguente. hub IoT aggiorna la versione desiderata della proprietà:
"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"
}
}
}
Aggiungere, sostituire o rimuovere un componente
Le operazioni a livello di componente richiedono un marcatore di oggetto $metadata vuoto all'interno del valore.
Un'operazione di aggiunta o sostituzione del componente imposta i valori desiderati di tutte le proprietà specificate. Cancella anche i valori desiderati per qualsiasi proprietà scrivibile non fornita con l'aggiornamento.
La rimozione di un componente cancella i valori desiderati di tutte le proprietà scrivibili presenti. Un dispositivo alla fine sincronizza questa rimozione e interrompe la segnalazione delle singole proprietà. Il componente viene quindi rimosso dal gemello digitale.
L'esempio di patch JSON seguente illustra come aggiungere, sostituire o rimuovere un 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"
}
]
Aggiungere, sostituire o rimuovere una proprietà
Un'operazione di aggiunta o sostituzione imposta il valore desiderato di una proprietà. Il dispositivo può sincronizzare lo stato e segnalare un aggiornamento del valore insieme a un codice, una versione e una ack descrizione.
Se è impostata, la rimozione di una proprietà cancella il valore desiderato della proprietà. Il dispositivo può quindi interrompere la segnalazione di questa proprietà e viene rimosso dal componente. Se questa proprietà è l'ultima nel componente, anche il componente viene rimosso.
L'esempio di patch JSON seguente illustra come aggiungere, sostituire o rimuovere una proprietà all'interno di un componente:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
Regole per impostare il valore desiderato di una proprietà del gemello digitale
Nome
Il nome di un componente o di una proprietà deve essere un nome DTDL valido.
I caratteri consentiti sono a-z, A-Z, 0-9 (non come primo carattere) e carattere di sottolineatura (non come primo o ultimo carattere).
Un nome può essere lungo 1-64 caratteri.
Valore della proprietà
Il valore deve essere una proprietà DTDL valida.
Sono supportati tutti i tipi primitivi. All'interno di tipi complessi sono supportate enumerazioni, mappe e oggetti. Per altre informazioni, vedere Schemi DTDL.
Le proprietà non supportano matrici o schemi complessi con una matrice.
Per un oggetto complesso è supportata una profondità massima di cinque livelli.
Tutti i nomi di campo all'interno di un oggetto complesso devono essere nomi DTDL validi.
Tutte le chiavi della mappa devono essere nomi DTDL validi.
Risolvere gli errori di aggiornamento dell'API di Gemelli digitali
L'API del gemello digitale genera il seguente messaggio di errore generico:
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 viene visualizzato questo errore, assicurarsi che la patch di aggiornamento segua le regole per impostare il valore desiderato di una proprietà del gemello digitale.
Quando si aggiorna un componente, assicurarsi che l'oggetto vuoto $metadata marcatore sia impostato.
Aggiornamenti può non riuscire se i valori segnalati di un dispositivo non sono conformi a Convenzioni plug and play IoT.
Passaggi successivi
Dopo aver appreso le informazioni sui gemelli digitali, ecco alcune altre risorse: