管理 IoT 隨插即用數位對應項

發行項
05/11/2024

IoT 隨插即用支援取得數位對應項和更新數位對應項作業來管理數位對應項。您可以使用 REST API 或服務 SDK 之一。

更新數位對應項

IoT 隨插即用裝置會實作數位對應項定義語言 (DTDL) 所述的模型。解決方案開發人員可以使用更新 Digital Twin API 來更新元件的狀態和數位對應項的屬性。

本文中作為範例的 IoT 隨插即用裝置實作了控溫器元件的溫度控制器模型。

下列程式碼片段顯示取得數位對應項要求的回應，其格式為 JSON 物件。若要深入了解數位對應項格式，請參閱了解 IoT 隨插即用數位對應項：

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

數位對應項讓您可使用 JSON 修補檔來更新整個元件或屬性。

例如，您可以更新 targetTemperature 屬性，如下所示：

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

前一個更新在對應的元件層級 $metadata 中設定了所需的屬性值，如下列程式碼片段所示。 IoT 中樞更新所需的屬性版本：

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

新增、取代或移除元件

元件層級作業需要在值內有一個空白物件 $metadata 標記。

新增或取代元件作業會設定所有提供之屬性所需的值，也會清除任何未隨更新提供的可寫入屬性所需的值。

移除元件會清除目前所有可寫入屬性所需的值。裝置最終會同步處理此移除作業，並停止回報個別屬性。然後，元件會從數位對應項中移除。

下列 JSON 修補檔範例示範如何新增、取代或移除元件：

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

新增、取代或移除屬性

加入或取代作業會設定屬性所需的值。裝置可以同步處理狀態並回報值的更新及 ack 程式碼、版本和描述。

如果已設定屬性，移除該屬性便會清除所需的屬性值。然後，裝置便可以停止回報該屬性，屬性也會從元件中移除。如果這個屬性是元件的最後一個屬性，則該該元件也會遭到移除。

下列 JSON 修補檔範例示範如何在元件內新增、取代或移除屬性：

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

設定數位對應項屬性所需值的規則

名稱

元件或屬性的名稱必須是有效的 DTDL 名稱。

允許的字元是 a-z、A-Z、0-9 (不可為第一個字元)，以及底線 (不可為第一個或最後一個字元)。

名稱長度可以介於 1-64 個字元。

屬性值

此值必須是有效的 DTDL 屬性。

支援所有的基本類型。在複雜類型內，支援列舉、對應和物件。若要深入了解，請參閱 DTDL 結構描述。

屬性不支援陣列或任何具有陣列的複雜結構描述。

複雜物件支援五個層級的最大深度。

複雜物件中的所有欄位名稱都應為有效的 DTDL 名稱。

所有對應索引鍵都應為有效的 DTDL 名稱。

針對更新數位對應項 API 錯誤進行疑難排解

數位對應項 API 會擲回下列一般錯誤訊息：

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.

如果您看到此錯誤，請確保更新修補檔有遵循設定數位對應項屬性所需值的規則。

當您更新元件時，請確定已設定空白物件 $metadata 標記。

如果裝置的回報值未遵循 IoT 即插即用慣例，更新可能會失敗。

下一步

現在您了解數位對應項了，以下有一些額外的資源可供參考：

共用方式為