IoT Tak Çalıştır dijital ikizleri yönetme

IoT Tak Çalıştır, dijital ikizleri yönetmek için Dijital ikiz alma ve Dijital ikiz işlemlerini güncelleştirme işlemlerini destekler. REST API'lerini veya hizmet SDK'larından birini kullanabilirsiniz.

Dijital ikiz güncelleştirme

IoT Tak Çalıştır cihaz, Digital Twins Tanım Dili (DTDL) V2 tarafından açıklanan bir model uygular. Çözüm geliştiricileri, bileşenin durumunu ve dijital ikizin özelliklerini güncelleştirmek için Dijital İkizi Güncelleştir API'sini kullanabilir.

Bu makalede örnek olarak kullanılan IoT Tak Çalıştır cihazı, Thermostat bileşenleriyle Sıcaklık Denetleyicisi modelini uygular.

Aşağıdaki kod parçacığı, JSON nesnesi olarak biçimlendirilmiş dijital ikiz alma isteğine verilen yanıtı gösterir. Dijital ikiz biçimi hakkında daha fazla bilgi edinmek için bkz. Dijital ikizleri IoT Tak Çalıştır anlama:

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

Dijital ikizler , JSON Düzeltme Eki kullanarak bileşenin veya özelliğin tamamını güncelleştirmenize olanak tanır.

Örneğin, özelliğini aşağıdaki gibi güncelleştirebilirsiniz targetTemperature :

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

Önceki güncelleştirme, aşağıdaki kod parçacığında gösterildiği gibi ilgili bileşen düzeyinde $metadata bir özelliğin istenen değerini ayarlar. IoT Hub özelliğin istenen sürümünü güncelleştirir:

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

Bileşen ekleme, değiştirme veya kaldırma

Bileşen düzeyi işlemleri, değer içinde boş bir nesne $metadata işaretçisi gerektirir.

Bileşen ekleme veya değiştirme işlemi, sağlanan tüm özelliklerin istenen değerlerini ayarlar. Ayrıca, güncelleştirmeyle birlikte sağlanmayan yazılabilir özellikler için istenen değerleri temizler.

Bir bileşenin kaldırılması, mevcut tüm yazılabilir özelliklerin istenen değerlerini temizler. Bir cihaz sonunda bu kaldırma işlemini eşitler ve tek tek özellikleri raporlamayı durdurur. Bileşen daha sonra dijital ikizden kaldırılır.

Aşağıdaki JSON Düzeltme Eki örneği, bir bileşeni ekleme, değiştirme veya kaldırma işlemini gösterir:

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

Özellik ekleme, değiştirme veya kaldırma

Ekleme veya değiştirme işlemi bir özelliğin istenen değerini ayarlar. Cihaz durumu eşitleyebilir ve bir kod, sürüm ve açıklamayla birlikte değerin güncelleştirmesini ack bildirebilir.

Bir özelliğin kaldırılması, ayarlanmışsa özelliğin istenen değerini temizler. Cihaz daha sonra bu özelliği raporlamayı durdurabilir ve bileşenden kaldırılır. Bu özellik bileşendeki son özellikse, bileşen de kaldırılır.

Aşağıdaki JSON Patch örneği, bir bileşenin içinde özellik ekleme, değiştirme veya kaldırma işlemini gösterir:

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

Dijital ikiz özelliğinin istenen değerini ayarlama kuralları

Ad

Bir bileşenin veya özelliğin adı geçerli DTDL V2 adı olmalıdır.

İzin verilen karakterler a-z, A-Z, 0-9 (ilk karakter olarak değil) ve alt çizgidir (ilk veya son karakter olarak değil).

Ad 1-64 karakter uzunluğunda olabilir.

Özellik değeri

Değer geçerli bir DTDL V2 Özelliği olmalıdır.

Tüm temel türler desteklenir. Karmaşık türlerde sabit listeleri, haritalar ve nesneler desteklenir. Daha fazla bilgi edinmek için bkz. DTDL V2 Şemaları.

Özellikler diziyi veya dizi içeren karmaşık şemaları desteklemez.

Karmaşık bir nesne için en fazla beş düzey derinliği desteklenir.

Karmaşık nesne içindeki tüm alan adları geçerli DTDL V2 adları olmalıdır.

Tüm harita anahtarları geçerli DTDL V2 adları olmalıdır.

Dijital ikiz API'sini güncelleştirme hatalarını giderme

Dijital ikiz API'sinde aşağıdaki genel hata iletisi görüntülenir:

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.

Bu hatayı görürseniz, güncelleştirme düzeltme ekinin dijital ikiz özelliğinin istenen değerini ayarlama kurallarına uydığından emin olun.

Bir bileşeni güncelleştirdiğinizde, boş nesne $metadata işaretçisinin ayarlandığından emin olun.

Güncelleştirmeler, bir cihazın bildirilen değerleri IoT tak çalıştır kurallarına uymuyorsa başarısız olabilir.

Sonraki adımlar

Dijital ikizler hakkında bilgi edindiğinize göre, burada daha fazla kaynak bulabilirsiniz: