Správa IoT Plug and Play digitálních dvojčat

IoT Plug and Play podporuje operace Získat digitální dvojče a Aktualizovat digitální dvojčata pro správu digitálních dvojčat. Můžete použít rozhraní REST API nebo některou ze sad SDK služby.

Aktualizace digitálního dvojčete

Zařízení IoT Plug and Play implementuje model popsaný v jazyce DTDL (Digital Twins Definition Language) verze 2. Vývojáři řešení můžou pomocí rozhraní Update Digital Twin API aktualizovat stav komponenty a vlastnosti digitálního dvojčete.

IoT Plug and Play zařízení použité jako příklad v tomto článku implementuje model regulátoru teploty se součástmi termostatu.

Následující fragment kódu ukazuje odpověď na žádost o získání digitálního dvojčete formátovaného jako objekt JSON. Další informace o formátu digitálních dvojčat najdete v tématu Principy IoT Plug and Play digitálních dvojčat:

{
    "$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"
        }
    }
}

Digitální dvojčata umožňují aktualizovat celou komponentu nebo vlastnost pomocí opravy JSON.

Vlastnost můžete například následujícím způsobem aktualizovat targetTemperature :

[
    {
        "op": "add",
        "path": "/thermostat1/targetTemperature",
        "value": 21.4
    }
]

Předchozí aktualizace nastaví požadovanou hodnotu vlastnosti v odpovídající úrovni $metadata komponenty, jak je znázorněno v následujícím fragmentu kódu. IoT Hub aktualizuje požadovanou verzi vlastnosti:

"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"
        }
    }
}

Přidání, nahrazení nebo odebrání komponenty

Operace na úrovni komponent vyžadují v rámci hodnoty prázdnou značku objektu $metadata .

Operace přidání nebo nahrazení komponenty nastaví požadované hodnoty všech zadaných vlastností. Vymaže také požadované hodnoty pro všechny zapisovatelné vlastnosti, které nejsou součástí aktualizace.

Odebrání komponenty vymaže požadované hodnoty všech zapisovatelných vlastností, které jsou k dispozici. Zařízení nakonec toto odebrání synchronizuje a přestane hlásit jednotlivé vlastnosti. Komponenta se pak odebere z digitálního dvojčete.

Následující ukázka opravy JSON ukazuje, jak přidat, nahradit nebo odebrat komponentu:

[
    {
        "op": "add",
        "path": "/thermostat1",
        "value": {
            "targetTemperature": 21.4,
            "anotherWritableProperty": 42,
            "$metadata": {}
        }
    },
    {
        "op": "replace",
        "path": "/thermostat1",
        "value": {
            "targetTemperature": 21.4,
            "$metadata": {}
        }
    },
    {
        "op": "remove",
        "path": "/thermostat2"
    }
]

Přidání, nahrazení nebo odebrání vlastnosti

Operace přidání nebo nahrazení nastaví požadovanou hodnotu vlastnosti. Zařízení může synchronizovat stav a hlásit aktualizaci hodnoty spolu s kódem, verzí a popisem ack .

Odebrání vlastnosti vymaže požadovanou hodnotu vlastnosti, pokud je nastavená. Zařízení pak může tuto vlastnost zastavit a odebere se z komponenty. Pokud je tato vlastnost poslední v komponentě, odebere se také komponenta.

Následující ukázka opravy JSON ukazuje, jak přidat, nahradit nebo odebrat vlastnost v rámci komponenty:

[
    {
        "op": "add",
        "path": "/thermostat1/targetTemperature",
        "value": 21.4
    },
    {
        "op": "replace",
        "path": "/thermostat1/anotherWritableProperty",
        "value": 42
    },
    {
        "op": "remove",
        "path": "/thermostat2/targetTemperature",
    }
]

Pravidla pro nastavení požadované hodnoty vlastnosti digitálního dvojčete

Název

Název komponenty nebo vlastnosti musí být platný název DTDL V2.

Povolené znaky jsou a-z, A-Z, 0-9 (ne jako první znak) a podtržítka (ne jako první nebo poslední znak).

Název může mít délku 1 až 64 znaků.

Hodnota vlastnosti

Hodnota musí být platná vlastnost DTDL V2.

Podporují se všechny primitivní typy. V rámci složitých typů jsou podporovány výčty, mapy a objekty. Další informace najdete v tématu Schémata DTDL V2.

Vlastnosti nepodporují pole ani žádné složité schéma s polem.

U komplexního objektu je podporována maximální hloubka pěti úrovní.

Všechny názvy polí v rámci komplexního objektu by měly být platné názvy DTDL V2.

Všechny klíče mapování by měly mít platné názvy DTDL V2.

Řešení potíží s aktualizacemi rozhraní API pro digitální dvojčata

Rozhraní API digitálního dvojčete vyvolá následující obecnou chybovou zprávu:

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.

Pokud se zobrazí tato chyba, ujistěte se, že oprava aktualizace dodržuje pravidla pro nastavení požadované hodnoty vlastnosti digitálního dvojčete.

Při aktualizaci komponenty se ujistěte, že je nastavená značka prázdného objektu $metadata .

Aktualizace může selhat, pokud hlášené hodnoty zařízení nevyhovují konvencím technologie Plug and Play IoT.

Další kroky

Teď, když jste se dozvěděli o digitálních dvojčatech, tady jsou další zdroje informací: