你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
管理 IoT 即插即用数字孪生
IoT 即插即用支持“获取数字孪生”和“更新数字孪生”操作以管理数字孪生。 可以使用 REST API，也可以使用服务 SDK 之一。
更新数字孪生
IoT 即插即用设备实现数字孪生定义语言（DTDL）描述的模型。 解决方案开发人员可以使用更新数字孪生 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",
}
]
数字孪生属性的预期值的设置规则
Name
组件或属性的名称必须是有效的 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 即插即用约定，更新可能会失败。
后续步骤
现在，你已了解数字孪生体，以下是一些其他资源：