适用于：
IoT Edge 1.5
重要
IoT Edge 1.5 LTS 是受支持的版本。 IoT Edge 1.4 LTS 的生命周期结束日期为 2024 年 11 月 12 日。 如果你使用的是较低的版本，请参阅更新 IoT Edge。
IoT Edge 代理和 IoT Edge 中心是构成 IoT Edge 运行时的两个模块。 有关每个运行时模块的责任的详细信息，请参阅 了解 Azure IoT Edge 运行时及其体系结构。
本文提供运行时模块孪生的所需属性和报告属性。 有关如何在 IoT Edge 设备上部署模块的详细信息，请参阅 了解如何在 IoT Edge 中部署模块和建立路由。
模块孪生包括：
所需的属性。 解决方案后端设置所需的属性，模块读取它们。 该模块还会接收到关于所需属性变更的通知。 将所需的属性与报告的属性结合使用，可以同步模块配置或条件。
报告的属性。 模块设置报告的属性，解决方案后端读取和查询它们。 报告的属性与所需的属性结合使用，可同步模块配置或状况。
IoT Edge 代理的模块孪生称为 $edgeAgent。 它协调在设备和 IoT 中心上运行的 IoT Edge 代理之间的通信。 在特定设备上将部署清单作为单一设备或规模部署的一部分应用时，将会设置所需的属性。
| 属性 | 描述 | 必需 |
|---|---|---|
| imagePullPolicy（镜像拉取策略） | 指定何时拉取映像： OnCreate 或 Never。 如果映像已在设备上，请使用“从不”。 | 是 |
| 重启策略 | 何时应重启模块。 可能的值为：Never：不重启未运行的模块，Always：始终重启未运行的模块，On-Unhealthy：重启不正常的模块。 “不正常”是 Docker 基于运行状况检查报告的状态，例如“不正常 - 容器未正常工作”，On-Failed：如果失败则重启。 | 是 |
| runtime.type | 必须是 docker。 | 是 |
| runtime.settings.minDockerVersion | 指定此部署清单所需的最低 Docker 版本。 | 是 |
| runtime.settings.loggingOptions | 使用字符串化的 JSON 来指定 IoT Edge 代理容器的日志记录选项。 详细了解 Docker 日志记录选项。 | 否 |
| runtime.settings.registryCredentials.{registryId}.username | 指定容器注册表的用户名。 对于 Azure 容器注册表，用户名通常是注册表名称。 专用模块映像需要注册凭据。 | 否 |
| runtime.settings.registryCredentials.{registryId}.password | 容器注册表的密码。 | 否 |
| runtime.settings.registryCredentials。{registryId}.address | 容器注册表的地址。 对于 Azure 容器注册表，地址通常为“{registry name}.azurecr.cn” 。 | 否 |
| schemaVersion | 指定 1.0 或 1.1。 推荐使用 IoT Edge 版本 1.0.10 引入的 1.1 版本。 | 是 |
| 状态 | 模块的所需状态：Running 或 Stopped。 | 必需 |
| systemModules.edgeAgent.type | 必须为 docker。 | 是 |
| systemModules.edgeAgent.startupOrder | 指定模块在启动顺序中的位置的整数。 0 是第一个， 最大整数 （4294967295）是最后一个。 如果未提供任何值，则默认值为 最大整数。 | 否 |
| 系统模块.边缘代理.设置.镜像 | 指定 IoT Edge 代理映像的 URI。 IoT Edge 代理无法自行更新。 | 是 |
| 系统模块.edgeAgent.设置.创建选项 | 指定包含用于创建 IoT Edge 代理容器的选项的字符串化 JSON。 详细了解 Docker 创建选项。 | 否 |
| systemModules.edgeAgent.configuration.id | 部署此模块的部署 ID。 | 此属性是在使用部署来应用清单时由 IoT 中心设置。 不是部署清单的一部分。 |
| systemModules.edgeHub.type | 必须为 docker。 | 是 |
| systemModules.edgeHub.status | 必须为 running。 | 是 |
| systemModules.edgeHub.restartPolicy | 必须为 always。 | 是 |
| systemModules.edgeHub.startupOrder | 一个整数值，指示某个模块在启动顺序中所处的位置。 0 表示第一个，最大整数 (4294967295) 表示最后一个。 如果未提供值，则默认值为最大整数。 | 否 |
| systemModules.edgeHub.settings.image | IoT Edge 中心的映像 URI。 | 是 |
| systemModules.edgeHub.settings.createOptions | 字符串化的 JSON 包含 IoT Edge 中心容器的创建选项。 Docker 创建选项 | 否 |
| systemModules.edgeHub.configuration.id | 部署此模块的部署 ID。 | 此属性是在使用部署来应用清单时由 IoT 中心设置。 不是部署清单的一部分。 |
| 模块.{moduleId}.version | 用户定义的字符串，表示此模块的版本。 | 是 |
| 模块.{moduleId}.type | 必须为 docker。 | 是 |
| 模块。{moduleId}.status | {runningstopped} | 是 |
| 模块.{moduleId}.restartPolicy | {neveralways} | 是 |
| 模块。{moduleId}.startupOrder | 一个整数值，指示某个模块在启动顺序中所处的位置。 0 表示第一个，最大整数 (4294967295) 表示最后一个。 如果未提供值，则默认值为最大整数。 | 否 |
| 模块。{moduleId}.imagePullPolicy | {on-createnever} | 否 |
| 模块。{moduleId}.env | 要传递给模块的环境变量的列表。 采用格式 "<name>": {"value": "<value>"}。 |
否 |
| 模块。{moduleId}.settings.image | 模块映像的 URI。 | 是 |
| 模块.{moduleId}.settings.createOptions | 字符串化的 JSON 包含模块容器的创建选项。 Docker 创建选项 | 否 |
| 模块.{moduleId}.configuration.id | 部署此模块的部署 ID。 | 此属性是在使用部署来应用清单时由 IoT 中心设置。 不是部署清单的一部分。 |
| 版本 | 包含版本、提交和内部版本的当前迭代。 | 否 |
IoT Edge 代理报告的属性包括三个主要信息片段：
- 上一次出现的所需属性的应用程序状态，
- IoT Edge 代理报告当前在设备上运行的模块的状态，以及
- 当前在设备上运行的所需属性的副本。
当前所需属性的副本有助于确定设备是否已应用最新部署或仍在运行以前的部署清单。
注意
可以使用 IoT 中心查询语言查询 IoT Edge 代理报告的属性，以大规模调查部署状态。 在了解单设备 IoT Edge 部署或大规模 IoT Edge 部署中了解如何使用 IoT Edge 代理属性来获取状态。
下表不包括从所需属性复制的信息。
| 属性 | 描述 |
|---|---|
| 最后期望状态代码 | IoT Edge 代理查看的最后所需属性的状态代码。 允许的值：200 成功、400 配置无效、412 架构版本无效、417 所需属性为空、500 失败。 |
| lastDesiredStatus.description | 状态的文本说明。 |
| 最终期望版本 | 此整数指的是由 IoT Edge 代理处理的所需属性的最后一个版本。 |
| 运行时.平台.操作系统 | 报告设备上运行的 OS。 |
| runtime.platform.体系结构 | 报告设备上的 CPU 体系结构。 |
| schemaVersion | 报告属性的架构版本。 |
| systemModules.edgeAgent.runtimeStatus | IoT Edge 代理的报告状态：{runningunhealthy}。 |
| 系统模块.edgeAgent.状态描述 | IoT Edge 代理报告状态的文本说明。 |
| 系统模块.边缘代理.退出代码 | 由 IoT Edge 代理容器报告的退出代码（如果容器存在）。 |
| systemModules.edgeAgent.lastStartTimeUtc | 上一次启动 IoT Edge 代理的时间。 |
| systemModules.edgeAgent.最后退出时间UTC | 上一次退出 IoT Edge 代理的时间。 |
| systemModules.edgeHub.runtimeStatus | IoT Edge 中心的状态：{runningstopped | failedbackoff | unhealthy}。 |
| 系统模块.edgeHub.状态描述 | 不正常的 IoT Edge 中心状态的文本说明。 |
| systemModules.edgeHub.exitCode | 由 IoT Edge 中心容器报告的退出代码（如果容器存在）。 |
| systemModules.edgeHub.lastStartTimeUtc | 上次启动 IoT Edge 中心的时间。 |
| systemModules.edgeHub.lastExitTimeUtc | 上次退出 IoT Edge 中心的时间。 |
| systemModules.edgeHub.lastRestartTimeUtc | 上次重启 IoT Edge 中心的时间。 |
| 系统模块.edgeHub.重启次数 | 作为重启策略的一部分，此模块重新启动的次数。 |
| 模块.{moduleId}.runtimeStatus | 模块的状态：{runningstopped | failedbackoff | unhealthy}。 |
| 模块.{moduleId}.状态描述 | 不正常的模块状态的文本说明。 |
| 模块。{moduleId}.exitCode | 由模块容器报告的退出代码（如果容器存在）。 |
| 模块。{moduleId}.lastStartTimeUtc | 上次启动模块的时间。 |
| 模块。{moduleId}.lastExitTimeUtc | 上次退出模块的时间。 |
| 模块。{moduleId}.lastRestartTimeUtc | 上次重启模块的时间。 |
| 模块。{moduleId}.restartCount | 作为重启策略的一部分，此模块重新启动的次数。 |
| 版本 | 映像的版本。 示例："version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }。 |
IoT Edge 中心的模块孪生被称为 $edgeHub，用于协调在设备上运行的与在 IoT 中心运行的 IoT Edge 中心之间的通信。 在特定设备上将部署清单作为单一设备或规模部署的一部分应用时，将会设置所需的属性。
| 属性 | 描述 | 部署清单中的必备项 |
|---|---|---|
| schemaVersion | 1.0 或 1.1。 版本 1.1 随 IoT Edge 版本 1.0.10 引入，推荐使用。 | 是 |
| 路线。{routeName} | 表示 IoT Edge 中心路由的字符串。 有关详细信息，请参阅声明路由。 |
routes 元素可以存在但为空。 |
| storeAndForwardConfiguration.timeToLiveSecs | 在断开连接路由终结点（无论是 IoT 中心还是本地模块）的情况下，IoT Edge 中心保留消息的设备时间（以秒为单位）。 即使关机或重启，此时间也会保留。 有关详细信息，请参阅脱机功能。 | 是 |
| 属性 | 描述 |
|---|---|
| 最后期望版本 | 此整数指的是由 IoT Edge 中心处理的所需属性的最后一个版本。 |
| 最后期望状态.代码 | 该状态代码指的是 IoT Edge 中心上次看到的所需属性。 允许的值：200 成功、400 配置无效、500 失败 |
| 最近期望状态.描述 | 状态的文本说明。 |
| 客户端 | 所有连接到 edgeHub 的客户端，以及状态和上次连接时间。 示例："clients": { "device2/SimulatedTemperatureSensor": { "status": "Connected", "lastConnectedTimeUtc": "2022-11-17T21:49:16.4781564Z" } }。 |
| 客户。{设备或模块ID}.状态 | 此设备或模块的连接状态。 可能的值：{connecteddisconnected}。 仅模块标识可以处于断开连接状态。 仅在连接时才会显示连接到 IoT Edge 中心的下游设备。 |
| 客户端.{设备或模块ID}.最后连接时间 | 上次连接设备或模块的时间。 |
| 客户。{device or moduleId}.lastDisconnectTime | 上次断开连接设备或模块的时间。 |
| schemaVersion | 报告属性的架构版本。 |
| 版本 | 映像的版本。 示例："version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }。 |
若要了解如何使用这些属性构建部署清单，请参阅了解如何使用、配置和重用 IoT Edge 模块。