管理 IoT 隨插即用 數字對應項
IoT 隨插即用支援取得數字對應項和更新數位對應項作業來管理數字對應項。 您可以使用 REST API 或其中一個 服務 SDK。
更新數位對應項
IoT 隨插即用 裝置會實作 Digital Twins 定義語言 （DTDL） 所描述的模型。 解決方案開發人員可以使用 Update Digital Twin API 來更新元件的狀態和數位對應項的屬性。
本文中用來做為範例的 IoT 隨插即用 裝置會實作具有控溫器元件的溫度控制器模型。
下列代碼段顯示將 Get digital twin 要求格式化為 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 隨插即用慣例。
下一步
既然您已瞭解數字對應項，以下是一些更多資源：