你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

了解 IoT 即插即用数字孪生

项目
02/07/2024

IoT 即插即用设备实现数字孪生体定义语言 (DTDL) 架构描述的模型。模型描述特定设备可能具有的组件、属性、命令和遥测消息集。

注意

DTDL 并非 IoT 即插即用所独有。其他 IoT 服务（例如 Azure 数字孪生）使用它来表示大楼、能源网络等整个环境。

Azure IoT 服务 SDK 包括可让服务与设备的数字孪生体进行交互的 API。例如，服务可以从数字孪生体读取设备属性，或使用数字孪生体在设备上调用命令。若要了解详细信息，请参阅 IoT 中心数字孪生体示例。

本文中的示例 IoT 即插即用设备实现了具有恒温器组件的温度控制器模型。

设备孪生和数字孪生体

除了数字孪生体之外，Azure IoT 中心还会为每个连接的设备维护一个设备孪生。设备孪生类似于数字孪生体，因为它是设备属性的表示形式。在 IoT 即插即用设备首次预配时，IoT 中心会对数字孪生体和设备孪生进行初始化。 Azure IoT 服务 SDK 包括用于与设备孪生进行交互的 API。

设备孪生是存储设备状态信息（包括元数据、配置和条件）的 JSON 文档。若要了解详细信息，请参阅 IoT 中心服务客户端示例。设备和解决方案开发者都可以使用同一组设备孪生 API 和 SDK，以便使用 IoT 即插即用约定来实现设备和解决方案。在设备孪生中，可写属性的状态拆分到“所需的属性”和“报告的属性”部分中。所有只读属性都显示在报告的属性部分中。

数字孪生 API 在高级 DTDL 构造（如组件、属性和命令）上运行，使解决方案构建者能够更轻松地创建 IoT 即插即用解决方案。数字孪生体提供了一个统一视图，其中包含属性的当前状态和所需状态。给定属性的同步状态存储在相应的默认组件 $metadata 部分。

设备孪生 JSON 示例

以下代码片段显示了一个格式化为 JSON 对象的 IoT 即插即用设备孪生：

{
  "deviceId": "sample-device",
  "modelId": "dtmi:com:example:TemperatureController;1",
  "version": 15,
  "properties": {
    "desired": {
      "thermostat1": {
        "__t": "c",
        "targetTemperature": 21.8
      },
      "$metadata": {...},
      "$version": 4
    },
    "reported": {
      "serialNumber": "alwinexlepaho8329",
      "thermostat1": {
        "maxTempSinceLastReboot": 25.3,
        "__t": "c",
        "targetTemperature": {
          "value": 21.8,
          "ac": 200,
          "ad": "Successfully executed patch",
        }
      },
      "$metadata": {...},
      "$version": 11
    }
  }
}

数字孪生体示例

以下代码片段显示了格式化为 JSON 对象的数字孪生体：

{
  "$dtId": "sample-device",
  "serialNumber": "alwinexlepaho8329",
  "thermostat1": {
    "maxTempSinceLastReboot": 25.3,
    "targetTemperature": 21.8,
    "$metadata": {
      "targetTemperature": {
        "desiredValue": 21.8,
        "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 对象中的字段：

字段名称	说明
`$dtId`	用户提供的字符串，表示设备数字孪生体的 ID。
`{propertyName}`	以 JSON 表示的属性的值。
`$metadata.$model`	[可选] 将此数字孪生体特征化的模型接口的 ID。
`$metadata.{propertyName}.desiredValue`	[仅适用于可写属性] 指定的属性所需的值。
`$metadata.{propertyName}.desiredVersion`	[仅适用于可写属性] IoT 中心维护的所需值的版本。
`$metadata.{propertyName}.ackVersion`	[必需，仅适用于可写属性] 实现数字孪生体的设备确认的版本，它必须大于或等于所需的版本。
`$metadata.{propertyName}.ackCode`	[必需，仅适用于可写属性] 实现数字孪生体的设备应用返回的 `ack` 代码。
`$metadata.{propertyName}.ackDescription`	[可选，仅适用于可写属性] 实现数字孪生体的设备应用返回的 `ack` 说明。
`$metadata.{propertyName}.lastUpdateTime`	IoT 中心维护设备上次更新属性的时间戳。时间戳采用 UTC，以 ISO8601 格式 YYYY-MM-DDTHH:MM:SS.mmmZ 进行编码。
`{componentName}`	一个包含组件的属性值和元数据的 JSON 对象。
`{componentName}.{propertyName}`	以 JSON 表示的组件属性的值。
`{componentName}.$metadata`	组件的元数据信息。

属性

属性是表示实体状态的数据字段（就像许多面向对象的编程语言中的属性）。

只读属性

DTDL 架构：

{
    "@type": "Property",
    "name": "serialNumber",
    "displayName": "Serial Number",
    "description": "Serial number of the device.",
    "schema": "string"
}

在此示例中，alwinexlepaho8329 是设备报告的 serialNumber 只读属性的当前值。

以下代码片段显示了 serialNumber 属性的并行 JSON 表示形式：

设备孪生

"properties": {
"reported": {
"serialNumber": "alwinexlepaho8329"
}
}

数字孪生体

"serialNumber": "alwinexlepaho8329"

可写属性

下面的示例显示了默认组件中的可写属性。

DTDL：

{
  "@type": "Property",
  "name": "fanSpeed",
  "displayName": "Fan Speed",
  "writable": true,
  "schema": "double"
}

设备孪生

{
"properties": {
"desired": {
"fanSpeed": 2.0,
},
"reported": {
"fanSpeed": {
"value": 3.0,
"ac": 200,
"av": 1,
"ad": "Successfully executed patch version 1"
}
}
},
}

数字孪生体

{
"fanSpeed": 3.0,
"$metadata": {
"fanSpeed": {
"desiredValue": 2.0,
"desiredVersion": 2,
"ackVersion": 1,
"ackCode": 200,
"ackDescription": "Successfully executed patch version 1",
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

在此示例中，3.0 是设备报告的 fanSpeed 属性的当前值。 2.0 是解决方案设置的所需值。根级别属性的所需值和同步状态是在数字孪生体的根级别 $metadata 内设置的。当设备联机后，它可以应用此更新，并报告更新后的值。

组件

可以通过组件将一个模型接口构建为其他接口的程序集。例如，可以在温度控制器模型中将恒温器接口合并为组件 thermostat1 和 thermostat2。

在设备孪生中，组件通过 { "__t": "c"} 标记进行标识。在数字孪生体中，$metadata 用来标记组件。

在此示例中，thermostat1 是一个具有两个属性的组件：

maxTempSinceLastReboot 是一个只读属性。
targetTemperature 是已被设备成功同步的可写属性。这些属性的所需值和同步状态在组件的 $metadata 中。

以下代码片段显示了 thermostat1 组件的并行 JSON 表示形式：

设备孪生

"properties": {
"desired": {
"thermostat1": {
"__t": "c",
"targetTemperature": 21.8
},
"$metadata": {
},
"$version": 4
},
"reported": {
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"__t": "c",
"targetTemperature": {
"value": 21.8,
"ac": 200,
"ad": "Successfully executed patch",
"av": 4
}
},
"$metadata": {
},
"$version": 11
}
}

数字孪生体

"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 21.8,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.8,
"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"
}
}
}

数字孪生体 API

数字孪生体 API 包括“获取数字孪生体”、“更新数字孪生体”、“调用组件命令”和“调用命令”等用于管理数字孪生体的操作。可以直接或通过其中一个服务 SDK 使用 REST API。

数字孪生体更改事件

启用数字孪生更改事件后，只要组件或属性的当前值或所需值发生更改，就会触发事件。数字孪生体更改事件是以 JSON 补丁格式生成的。如果启用了孪生体更改事件，则会以设备孪生格式生成相应的事件。

若要了解如何为设备和数字孪生体事件启用路由，请参阅使用 IoT 中心消息路由将设备到云消息发送到不同的终结点。若要了解消息格式，请参阅创建和读取 IoT 中心消息。

例如，当解决方案设置 targetTemperature 时，将触发以下数字孪生体更改事件：

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:04 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d463fa034
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature",
    "value": {
      "desiredValue": 21.8,
      "desiredVersion": 4
    }
  }
]

当设备报告上述所需更改已得到应用时，会触发以下数字孪生体更改事件：

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:05 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d464a2c80
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackCode",
    "value": 200
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackDescription",
    "value": "Successfully executed patch"
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackVersion",
    "value": 4
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/lastUpdateTime",
    "value": "2020-07-17T06:11:04.9309159Z"
  },
  {
    "op": "add",
    "path": "/thermostat1/targetTemperature",
    "value": 21.8
  }
]

注意

同时在设备和数字孪生体更改通知中进行启用时，孪生体更改通知消息数会翻倍。

后续步骤

现在，你已了解数字孪生体，以下是一些其他资源：

通过

了解 IoT 即插即用数字孪生

设备孪生和数字孪生体

设备孪生 JSON 示例

数字孪生体示例

属性

只读属性

可写属性

组件

数字孪生体 API

数字孪生体更改事件

后续步骤

反馈

其他资源