OSConfig 用户需要了解的“普通所需/报告”与“DTDL 增强”工具链

通过不同的工具读取 OSConfig 文档和试用方案时,了解 Azure IoT 生态系统中描述孪生内容的两个视角会很有帮助。

透视 1:普通所需/报告

所需属性和报告属性构成了核心IoT 中心对象模型。 大多数工具和服务都使用此纯所需/报告的透视。 例如:

  • IoT 中心查询服务
  • IoT 中心配置服务
  • az iot hub module-twin命令
  • Azure 门户中的 IoT 中心孪生视图
  • IoT 资源管理器中的纯孪生视图

普通的所需/报告透视可以描述为 JSON 文档,其中:

  1. 实际状态 ((如当前配置或状态) )由分区下 properties.reported 设备上的代码报告
  2. 所需状态 (,例如管理员) 的配置设置(如果有)由云中的管理工具在分区下 properties.desired 添加
  3. 如果从云端指定了任何所需状态,设备上的负责任的代码将通过该部分中的其他属性 properties.reported 确认相同。

以下示例是IoT 中心设备 OSConfig 模块孪生的简化摘录:

  1. 设备上的 OSConfig 代理始终将当前主机名报告为 properties.reported.HostName.name
  2. 此外,管理员希望确保特定值,因此在云端填充了这些值 properties.desired.HostName.desiredName
  3. 为了响应 properties.desired.HostName.desiredName 管理员的填充,设备上的 OSConfig 代理确认收到与管理员相同的 properties.reported.HostName.desiredName接收。

显示所需属性和报告属性的批注屏幕截图

透视 2:数字孪生定义语言 (DTDL) 增强建模

DTDL (以及 Azure IoT 即插即用 [PnP]) 等相关模式,使应用和服务能够预测、验证和更好地将孪生内容上下文化到纯 JSON 之外。 使用此 DTDL 增强透视的工具和服务包括:

  • IoT 资源管理器中的“即插即用”视图
  • Azure 数字孪生服务

上述孪生内容的 DTDL 增强视图可以描述为:

  • 此设备/模块具有名为 HostName组件,用于实现 OSConfig HostName 接口

  • HostName 组件/接口中,有一个名为名称只读属性,其值应为字符串

  • 此外,在 HostName 组件中,还有一个名为 desiredName的可写属性,其值应为字符串

    ー 在应用于 OSConfig 等设备代理的 DTDL 上下文中,“只读”表示属性由设备报告,而不是由云中的管理员直接) 设置 (
    在应用于 OSConfig 等设备代理的 DTDL 上下文中,“可写”表示该属性可由云中的管理员设置,当设备收到此属性时,将有确认。

IoT 资源管理器的以下屏幕截图是一个使用 DTDL 的工具示例。 在此示例中,IoT 资源管理器让管理员知道 desiredName 可在下 HostName设置该资源管理器。 管理员可能不知道这是一个选项,尤其是考虑到 properties.desired 基础孪生部分默认为空。

可写属性的 IoT Explorer DTDL 增强视图的屏幕截图

OSConfig 文档介绍哪些视角?

在 OSConfig 参考文档中,我们默认描述普通的所需/报告透视。 如果 DTDL 增强工具的其他上下文适用,该信息将包含在括号中。

例如,在 CommandRunner: commandArguments (由管理员设置) 可能的值 action 描述为“1 (重启) 、2 (关闭) 、3 (RunCommand) 或 4 (refreshCommandStatus) ”。 在普通的所需/报告体验中,如 az iot hub module-twin show 会看到数值。 在 IOT 资源管理器的IoT 即插即用视图等 DTDL 增强体验中,会看到标签 (“重新启动”等)

如何实现 (或正在使用的工具(例如 IoT 资源管理器) 查找最新的 OSConfig DTDL 模型 (DTMI) ?

在 IoT 资源管理器的“主页>IoT 即插即用设置”下,选择添加可配置存储库,路径如下: raw.githubusercontent.com/Azure/azure-osconfig/main 有关示例,请参阅以下屏幕截图。

上述代理的屏幕截图。

如果要直接检查模型,而不是在 IoT 资源管理器中加载模型,URI 为: https://github.com/Azure/azure-osconfig/tree/main/dtmi/osconfig

注意

为什么模型不位于 https://devicemodels.azure.com

较旧版本的 OSConfig 模型已发布, https://devicemodels.azure.com但截至本文 () 不可能在那里发布较新版本。 应改用上述 GitHub 地址。

后续步骤

有关 OSConfig 方案和功能的概述,请参阅:

有关特定实际示例,请参阅: