IoT Plug and Play digitális ikerpéldányok kezelése
Az IoT Plug and Play támogatja a Digitális ikerpéldányok lekérése és a Digitális ikerpéldány frissítése műveleteket a digitális ikerpéldányok kezeléséhez. Használhatja a REST API-kat vagy az egyik szolgáltatás SDK-t.
Digitális ikerpéldány frissítése
Az IoT Plug and Play-eszközök a Digital Twins Definition Language (DTDL) által leírt modellt implementálják. A megoldásfejlesztők az Update Digital Twin API használatával frissíthetik az összetevő állapotát és a digitális ikerpéldány tulajdonságait.
A cikkben példaként használt IoT Plug and Play eszköz termosztát-összetevőkkel implementálja a Hőmérséklet-vezérlő modellt.
Az alábbi kódrészlet egy JSON-objektumként formázott Digitális ikerpéldány kérésére adott választ jeleníti meg. A digitális ikerpéldányok formátumáról további információt az IoT Plug and Play digitális ikerpéldányok ismertetése című témakörben talál:
{
"$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"
}
}
}
A digitális ikerpéldányokkal egy teljes összetevőt vagy tulajdonságot frissíthet egy JSON-javítás használatával.
A tulajdonságot például az targetTemperature alábbiak szerint frissítheti:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
Az előző frissítés egy tulajdonság kívánt értékét a megfelelő összetevőszinten $metadata állítja be az alábbi kódrészletben látható módon. Az IoT Hub frissíti a tulajdonság kívánt verzióját:
"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"
}
}
}
Összetevő hozzáadása, cseréje vagy eltávolítása
Az összetevőszintű műveletekhez üres objektumjelölőre $metadata van szükség az értéken belül.
Az összetevő hozzáadása vagy cseréje művelet az összes megadott tulajdonság kívánt értékeit állítja be. Emellett törli a kívánt értékeket minden olyan írható tulajdonság esetében, amely nem szerepel a frissítésben.
Az összetevők eltávolítása törli az összes írható tulajdonság kívánt értékeit. Egy eszköz végül szinkronizálja ezt az eltávolítást, és leállítja az egyes tulajdonságok jelentését. Ezt követően az összetevő el lesz távolítva a digitális ikerpéldányból.
Az alábbi JSON-javításminta bemutatja, hogyan adhat hozzá, cserélhet vagy távolíthat el összetevőket:
[
{
"op": "add",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"anotherWritableProperty": 42,
"$metadata": {}
}
},
{
"op": "replace",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"$metadata": {}
}
},
{
"op": "remove",
"path": "/thermostat2"
}
]
Tulajdonság hozzáadása, cseréje vagy eltávolítása
Egy hozzáadási vagy csereművelet beállítja egy tulajdonság kívánt értékét. Az eszköz szinkronizálhatja az állapotot, és jelentést készíthet az érték frissítéséről egy ack kóddal, verzióval és leírással együtt.
A tulajdonság eltávolítása törli a tulajdonság kívánt értékét, ha be van állítva. Az eszköz ezután leállítja a tulajdonság jelentését, és eltávolítja az összetevőből. Ha ez a tulajdonság az utolsó az összetevőben, akkor az összetevő is törlődik.
Az alábbi JSON Patch-minta bemutatja, hogyan adhat hozzá, cserélhet vagy távolíthat el tulajdonságot egy összetevőn belül:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
A digitális ikertulajdonság kívánt értékének beállítására vonatkozó szabályok
Név
Egy összetevő vagy tulajdonság nevének érvényes DTDL-névnek kell lennie.
Az engedélyezett karakterek a-z, A-Z, 0-9 (nem az első karakter), és aláhúzásjelek (nem az első vagy az utolsó karakter).
A név 1–64 karakter hosszú lehet.
Tulajdonságérték
Az értéknek érvényes DTDL-tulajdonságnak kell lennie.
Minden primitív típus támogatott. Az összetett típusokon belül az enumerálások, a térképek és az objektumok támogatottak. További információ: DTDL-sémák.
A tulajdonságok nem támogatják a tömböt vagy a tömböt tartalmazó összetett sémákat.
Összetett objektumok esetében öt szint maximális mélysége támogatott.
Az összetett objektumon belüli összes mezőnévnek érvényes DTDL-névnek kell lennie.
Minden térképkulcsnak érvényes DTDL-névnek kell lennie.
A digitális iker API frissítési hibáinak elhárítása
A digitális iker API a következő általános hibaüzenetet küldi:
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.
Ha ezt a hibát látja, győződjön meg arról, hogy a frissítési javítás a digitális ikertulajdonság kívánt értékének beállítására vonatkozó szabályokat követi.
Az összetevő frissítésekor győződjön meg arról, hogy az üres objektum $metadata jelölő be van állítva.
Frissítések meghiúsulhat, ha egy eszköz jelentett értékei nem felelnek meg a IoT plug and play konvenciók.
Következő lépések
Most, hogy megismerkedett a digitális ikerpéldányokkal, íme néhány további forrás: