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

什么是设备模板？

项目
06/08/2023

Azure IoT Central 中的设备模板是一个蓝图，用于定义可连接到应用程序的某种设备的特征和行为。例如，设备模板定义设备发送的遥测数据，以便 IoT Central 使用正确单位和数据类型创建可视化效果。

解决方案构建者将设备模板添加到 IoT Central 应用程序。设备开发者编写实现设备模板中定义的行为的设备代码。若要详细了解设备与 IoT Central 交换的数据，请参阅遥测、属性和命令有效负载。

设备模板包含以下各部分：

设备模型。设备模板的此部分定义设备与应用程序交互的方式。每个设备模型都有唯一 ID。设备开发者实现模型中定义的行为。
- 根组件。每个设备模型都有根组件。根组件的接口描述了特定于设备模型的功能。
- 组件。除了描述设备功能的根组件之外，设备模型还可能包含其他组件。每个组件都有一个用于描述组件功能的接口。组件接口可以在其他设备模型中重复使用。例如，多个电话设备模型可能使用同一相机接口。
- 继承接口。设备模型包含一个或多个可扩展根组件功能的接口。
视图。设备模板的此部分使解决方案开发者可以定义可视化，以查看设备中的数据，以及用于管理和控制设备的窗体。视图不影响设备开发者为实现设备模型而编写的代码。

将设备分配到设备模板

若要使设备与 IoT Central 交互，必须将其分配到设备模板。此分配操作通过以下四种方式之一完成：

在“设备”页上“注册”设备时，可以标识设备应使用的模板。
批量导入设备列表时，可选择列表中所有设备都应使用的设备模板。
连接设备模板后，可以手动将未分配的设备分配到设备模板。
当设备首次连接到应用程序时，可通过发送模型 ID 自动将设备分配到设备模板。

自动分配

设备连接后，IoT Central 会自动将设备分配到设备模板。设备连接时应会发送一个模型 ID。 IoT Central 使用模型 ID 识别该特定设备模型的设备模板。发现过程如下所述：

如果设备模板已在 IoT Central 应用程序中发布，则设备将分配到设备模板。
如果设备模板未在 IoT Central 应用程序中发布，IoT Central 会在公共设备模型存储库中查找设备模型。如果 IoT Central 找到模型，它将使用该模型生成基本设备模板。
如果 IoT Central 在公共模型存储库中找不到模型，则设备将被标记为“未分配”。操作员可以：
- 为设备创建设备模板，然后将未分配的设备迁移到新的设备模板。
- 根据设备发送的数据自动生成设备模板。

以下屏幕截图演示了如何在 IoT Central 中查看设备模板的模型 ID。在设备模板中，选择一个组件，然后选择“编辑标识”：

可以在公共模型存储库中查看恒温器模型。模型 ID 定义如下所示：

"@id": "dtmi:com:example:Thermostat;1"

使用以下 DPS 有效负载将设备分配到设备模板：

{
  "modelId":"dtmi:com:example:TemperatureController;2"
}

若要详细了解 DPS 有效负载，请参阅教程：创建客户端应用程序并将其连接到 Azure IoT Central 应用程序中使用的示例代码。

设备模型

设备模型定义设备与 IoT Central 应用程序交互的方式。设备开发者必须确保设备实现设备模型中定义的行为，以便 IoT Central 能够监视和管理设备。设备模型由一个或多个“接口”组成，每个接口都可以定义“遥测”类型、“设备属性”和“命令”的集合。解决方案开发人员可以：

将定义完整设备模型或单个接口的 JSON 文件导入到设备模板中。
使用 IoT Central 中的 Web UI 创建或编辑设备模型。

注意

IoT Central 接受来自设备的任何有效 JSON 负载，但如果数据与设备模型中的定义匹配，则只能将数据用于可视化效果。可以导出与定义不匹配的数据，请参阅使用 Blob 存储将 IoT 数据导出到云目标。

若要详细了解如何编辑设备模型，请参阅编辑现有设备模板

解决方案开发人员还可以从包含完整设备模型或单独接口的设备模板中导出 JSON 文件。设备开发者可以使用此 JSON 文档来了解设备应该如何与 IoT Central 的应用程序进行通信。

定义设备模型的 JSON 文件使用数字孪生体定义语言 (DTDL) V2。 IoT Central 要求 JSON 文件包含带有以内联方式（而不是在单独的文件中）定义接口的设备模型。在 IoT Central 中创建的模型具有已定义的上下文 dtmi:iotcentral:context;2，以指示模型是在 IoT Central 中创建的：

"@context": [
  "dtmi:iotcentral:context;2",
  "dtmi:dtdl:context;2"
]

若要详细了解 DTDL 模型，请参阅 IoT 即插即用建模指南。

注意

IoT Central 定义了 DTDL v2 语言的一些扩展。若要了解详细信息，请参阅 IoT Central 扩展。

属性

默认情况下，属性是只读的。只读属性意味着设备将属性值更新报告给你的 IoT Central 应用程序。 IoT Central 应用程序无法设置只读属性的值。

还可以将接口上的属性标记为可写。设备可以从你的 IoT Central 应用程序中接收可写属性的更新，以及向应用程序报告属性值更新。

设备无需连接即可设置属性值。当设备下一次连接到应用程序时，将传输更新的值。此行为同时适用于只读属性和可写属性。

不要使用属性从设备发送遥测数据。例如，一种只读属性（例如 temperatureSetting=80）意味着设备温度已设置为 80，并且设备尝试达到或停留在此温度。

对于可写属性，设备应用程序会返回所需状态的状态代码、版本和说明，以指示是否已收到并应用属性值。

云属性

你还可以将云属性添加到模型的根组件。云属性使你可以指定要存储在 IoT Central 应用程序中的任何设备元数据。云属性值存储在 IoT Central 应用程序中，永远不会与设备同步。云属性不影响设备开发者为实现设备模型而编写的代码。

解决方案开发者可以将云属性与设备属性一起添加到设备视图和窗体中，使操作员能够管理连接到应用程序的设备。解决方案开发者还可以使用云属性作为规则定义的一部分，使操作员可以编辑阈值。

以下 DTDL 代码片段显示了一个示例云属性定义：

{
    "@id": "dtmi:azureiot:Thermostat:CustomerName",
    "@type": [
        "Property",
        "Cloud",
        "StringValue"
    ],
    "displayName": {
        "en": "Customer Name"
    },
    "name": "CustomerName",
    "schema": "string"
}

遥测

使用 IoT Central，可以在设备视图和图表中查看遥测数据，并通过规则在达到阈值时触发操作。 IoT Central 使用设备模型中的信息（如数据类型、单位和显示名称）来确定如何显示遥测值。还可以在应用程序和个人仪表板上显示遥测值。

你可以使用 IoT Central 数据导出功能将遥测数据流式传输到其他目标（例如存储或事件中心）。

命令

默认情况下，命令必须在 30 秒内执行，并且设备在命令到达时必须处于已连接状态。如果设备未按时响应或设备未连接，则该命令将失败。

命令可以包含请求参数并返回响应。

脱机命令

如果设备当前脱机，则可通过为设备模板中的命令启用“脱机时排队”选项，选择排队命令。

脱机命令是从解决方案到设备的单向通知。脱机命令可以有请求参数，但不返回响应。

注意

如果将模型导出为 DTDL，则脱机命令将标记为 durable。

脱机命令使用 IoT 中心云到设备的消息将命令和有效负载发送到设备。

设备接收的消息的有效负载是参数的原始值。名为 method-name 的自定义属性存储 IoT Central 命令的名称。下表显示了一些有效负载的示例：

IoT Central 请求架构	设备接收的有效负载示例
无请求参数	`@`
双精度	`1.23`
字符串	`sample string`
Object	`{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}`

设备模型中的以下代码片段显示命令的定义。该命令具有一个对象参数，其中包含日期/时间字段和枚举：

{
  "@type": "Command",
  "displayName": {
    "en": "Generate Diagnostics"
  },
  "name": "GenerateDiagnostics",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "Payload"
    },
    "name": "Payload",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "StartTime"
          },
          "name": "StartTime",
          "schema": "dateTime"
        },
        {
          "displayName": {
            "en": "Bank"
          },
          "name": "Bank",
          "schema": {
            "@type": "Enum",
            "displayName": {
              "en": "Enum"
            },
            "enumValues": [
              {
                "displayName": {
                  "en": "Bank 1"
                },
                "enumValue": 1,
                "name": "Bank1"
              },
              {
                "displayName": {
                  "en": "Bank2"
                },
                "enumValue": 2,
                "name": "Bank2"
              },
              {
                "displayName": {
                  "en": "Bank3"
                },
                "enumValue": 3,
                "name": "Bank3"
              }
            ],
            "valueSchema": "integer"
          }
        }
      ]
    }
  }
}

如果为上一个代码片段中的命令启用设备模板 UI 中的“脱机时排队”选项，则设备接收的消息包括以下属性：

属性名称	示例值
`custom_properties`	`{'method-name': 'GenerateDiagnostics'}`
`data`	`{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}`

视图

解决方案开发者创建视图，以支持操作员监视和管理连接的设备。视图是设备模板的一部分，因此视图与特定设备类型相关联。视图可以包括：

绘制遥测数据的图表。
显示只读设备属性的磁贴。
允许操作员编辑可写设备属性的磁贴。
允许操作员编辑云属性的磁贴。
允许操作员调用命令的磁贴，包括需要有效负载的命令。
显示标签、图像或 markdown 文本的磁贴。

后续步骤

现在，你已经了解设备模板，建议的后续步骤是阅读遥测、属性和命令有效负载，详细了解设备与 IoT Central 交换的数据。