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

在 IoT 解决方案中使用 IoT 即插即用模型

项目
08/30/2024

本文介绍如何在 IoT 解决方案中标识 IoT 即插即用设备的模型 ID，然后检索其模型定义。

IoT 解决方案分为两大类：

根据用途生成的解决方案适用于一系列要与解决方案连接的 IoT 即插即用设备的已知模型。在开发解决方案时会使用这些模型。
模型驱动的解决方案适用于任何 IoT 即插即用设备的模型。生成模型驱动的解决方案会更复杂，但优点在于解决方案适用于任何在未来会添加的设备。模型驱动的 IoT 解决方案会检索某个模型并使用它来决定设备实现的遥测、属性和命令。

若要使用 IoT 即插即用模型，IoT 解决方案需要：

标识由 IoT 即插即用设备、模块或连接到解决方案的 IoT Edge 模块实现的模型的模型 ID。
使用模型 ID 从模型存储库或自定义存储中检索已连接的设备的模型定义。

标识模型 ID

当 IoT 即插即用设备连接到 IoT 中心时，会向 IoT 中心注册它所实现的模型的模型 ID。

在设备连接流中，IoT 中心会将设备模型 ID 告知解决方案。

解决方案可以使用以下三种方法之一获取 IoT 即插即用设备的模型 ID：

获取设备孪生 API

解决方案可以使用获取设备孪生 API 来检索 IoT 即插即用设备的模型 ID。

提示

对于模块和 IoT Edge 模块，使用 ModuleClient.getTwin。

在以下设备孪生响应代码段中，modelId 包含 IoT 即插即用设备的模型 ID：

{
    "deviceId": "sample-device",
    "etag": "AAAAAAAAAAc=",
    "deviceEtag": "NTk0ODUyODgx",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00Z",
    "connectionState": "Disconnected",
    "lastActivityTime": "2020-07-17T06:12:26.8402249Z",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "modelId": "dtmi:com:example:TemperatureController;1",
    "version": 15,
    "properties": {...}
    }
}

获取数字孪生 API

解决方案可以使用获取数字孪生 API 来检索 IoT 即插即用设备实现的模型的模型 ID。

在以下数字孪生响应代码段中，$metadata.$model 包含 IoT 即插即用设备的模型 ID：

{
    "$dtId": "sample-device",
    "$metadata": {
        "$model": "dtmi:com:example:TemperatureController;1",
        "serialNumber": {
            "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
        }
    }
}

数字孪生更改事件通知

设备连接会生成数字孪生更改事件通知。解决方案需要订阅此事件通知。若要了解如何为数字孪生事件启用路由，请参阅使用 IoT 中心消息路由将设备到云消息发送到不同的终结点。

解决方案可以使用以下代码片段中所示的事件来了解正在连接的 IoT 即插即用设备并获取其模型 ID：

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/22/2020 8:02:27 PM
iothub-message-source:digitalTwinChangeEvents
correlation-id:100f322dc2c5
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:com:example:TemperatureController;1"
  }
]

检索模型定义

解决方案使用先前标识的模型 ID 来检索相应的模型定义。

解决方案可以使用以下选项之一获取模型定义：

模型存储库

解决方案可以从设备模型存储库 (DMR) 检索 DTDL 模型。 DMR 是由 Microsoft 托管的公共存储库，其中包含特选 DTDL 模型的集合。每个人都可以从公共终结点 https://devicemodels.azure.com 在其应用程序中使用和集成 DMR 中存储的公共设备模型。

标识新设备连接的模型 ID 后，请执行以下步骤：

使用模型存储库中的模型 ID 检索模型定义。有关详细信息，请参阅解析模型。
使用连接的设备的模型定义，可以枚举设备的功能。
使用设备的枚举功能，可以使用户能够与设备交互。

解析模型

DMR 约定包括用于简化托管模型的使用的其他生成工件。对于自定义或专用存储库，这些功能是可选的。

Index。所有可用的 DTMI 都通过由一系列 json 文件组成的索引公开，例如：https://devicemodels.azure.com/index.page.2.json
扩展。具有所有依赖项的文件可用于每个接口，例如 https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json。
Metadata。此文件公开存储库的关键属性，并使用最新发布的模型快照定期刷新。它包括存储库实现的功能，例如模型索引或扩展的模型文件是否可用。可以在 https://devicemodels.azure.com/metadata.json 访问 DMR 元数据

要以编程方式访问 DMR 中的公共 DTDL 模型，可以使用 NuGet 包 Azure.IoT.ModelsRepository 中提供的 ModelsRepositoryClient。默认情况下，此客户端配置为查询 devicemodels.azure.com 可用的公共 DMR，也可配置为任何自定义存储库。

客户端接受 DTMI 作为输入，并返回包含所有必需接口的字典：

using Azure.IoT.ModelsRepository;

var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

预期输出显示在依赖项链中找到的三个接口的 DTMI：

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

可以将 ModelsRepositoryClient 配置为查询自定义 DMR（可通过 https 获取）并使用 ModelDependencyResolution 标记来指定依赖项解析：

“禁用”。仅返回指定的接口，没有任何依赖项。
已启用。返回依赖项链中的所有接口

提示

自定义存储库可能不会公开 .expanded.json 文件。此文件不可用时，客户端将回退，以在本地处理每一个依赖项。

以下示例代码演示如何使用自定义存储库基 URL 初始化 ModelsRepositoryClient，在这种情况下是指使用 GitHub API 中的 raw URL，而不是 expanded 窗体（因为它在 raw 终结点中不可用）。 AzureEventSourceListener 将执行初始化，以检查客户端执行的 HTTP 请求：

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

var client = new ModelsRepositoryClient(
    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));

ModelResult model = await client.GetModelAsync(
    "dtmi:com:example:TemperatureController;1", 
    dependencyResolution: ModelDependencyResolution.Enabled);

model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

有关更多示例，请参阅 Azure SDK GitHub 存储库：Azure.Iot.ModelsRepository/samples。

自定义存储

解决方案可以将这些模型定义存储在本地文件系统、公共文件存储中，或使用自定义实现。