IoT Edge代理和IoT Edge中心模块孪生的属性

适用于： IoT Edge 1.5

重要说明

IoT Edge 1.5 LTS 是受支持的版本。 IoT Edge 1.4 LTS 于 2024 年 11 月 12 日终止。 如果使用的是早期版本，请参阅 Update IoT Edge。

IoT Edge代理和IoT Edge中心是构成IoT Edge运行时的两个模块。 有关每个运行时模块的责任的详细信息，请参阅了解Azure IoT Edge运行时及其体系结构。

本文提供运行时模块孪生的所需属性和报告属性。 有关如何在 IoT Edge 设备上部署模块的详细信息，请参阅 learn 如何在 IoT Edge 中部署模块和建立路由。

模块孪生包括：

• 所需的属性。 解决方案后端设置所需的属性，模块读取它们。 该模块还会接收到关于所需属性变更的通知。 使用所需属性以及报告的属性来同步模块配置或条件。

• 报告的属性。 模块设置报告的属性，解决方案后端读取和查询它们。 使用报告的属性以及所需的属性来同步模块配置或条件。

EdgeAgent 所需属性

IoT Edge代理的模块孪生称为 $edgeAgent。 它协调在设备上运行的IoT Edge代理与IoT 中心之间的通信。 在将部署清单应用于特定设备时，无论是单台设备还是大规模部署，请设置所需属性。

properties	说明	必选
imagePullPolicy	指定何时拉取映像： OnCreate 或 Never。 如果映像已在设备上，请使用“从不”。	是
restartPolicy	何时重启模块。 可能的值为：never：不重启未运行的模块，on-failure：重启退出并显示非零退出代码的模块，on-unhealthy：重启不正常的模块（参见注释），always：始终重启未运行的模块。 注意： 该 on-failure 策略重启使用非零退出代码退出的模块。 on-unhealthy该策略由架构接受，但运行时当前不会从 Docker 运行状况检查中派生不正常状态，因此它没有实际效果。 有关详细信息，请参阅 IoT Edge 限制和限制。	是
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.io。	否
schemaVersion	指定 1.0 或 1.1。 推荐使用与 IoT Edge 版本 1.0.10 一起引入的版本 1.1。	是
status	模块的所需状态：Running 或 Stopped。	必选
systemModules.edgeAgent.type	必须是 docker。	是
systemModules.edgeAgent.startupOrder	指定模块在启动顺序中的位置的整数。 0 是第一个， 最大整数 （4294967295）是最后一个。 如果未提供值，则默认值为 最大整数。	否
systemModules.edgeAgent.settings.image	指定IoT Edge代理映像的 URI。 IoT Edge代理无法自行更新。	是
systemModules.edgeAgent.settings.createOptions	指定包含用于创建IoT Edge代理容器的选项的字符串化 JSON。 详细了解 Docker 创建选项。	否
systemModules.edgeAgent.configuration.id	部署此模块的部署 ID。	在通过应用程序部署使用清单时，IoT 中心 会设置此属性。 不是部署清单的一部分。
systemModules.edgeHub.type	必须是 docker。	是
systemModules.edgeHub.status	必须 正在运行。	是
systemModules.edgeHub.restartPolicy	必须 始终。	是
systemModules.edgeHub.startupOrder	一个整数值，指示某个模块在启动顺序中所处的位置。 第一个是 0，最后一个是最大整数 (4294967295)。 如果未提供值，则默认值为 最大整数。	否
systemModules.edgeHub.settings.image	IoT Edge 中心的映像 URI。	是
systemModules.edgeHub.settings.createOptions	包含用于创建IoT Edge中心容器的选项的字符串化 JSON。 Docker 创建选项	否
systemModules.edgeHub.configuration.id	部署此模块的部署 ID。	在通过应用程序部署使用清单时，IoT 中心 会设置此属性。 不是部署清单的一部分。
modules.{moduleId}.version	用户定义的字符串，表示此模块的版本。	是
modules.{moduleId}.type	必须是 docker。	是
modules.{moduleId}.status	运行 | 停止	是
modules.{moduleId}.restartPolicy	never | on-failure | on-unhealthy | always	是
modules.{moduleId}.startupOrder	一个整数值，指示某个模块在启动顺序中所处的位置。 第一个是 0，最后一个是最大整数 (4294967295)。 如果未提供值，则默认值为 最大整数。	否
modules.{moduleId}.imagePullPolicy	on-create | 从不	否
modules.{moduleId}.env	要传递给模块的环境变量的列表。 采用格式 "<name>": {"value": "<value>"}。	否
modules.{moduleId}.settings.image	模块映像的 URI。	是
modules.{moduleId}.settings.createOptions	字符串化的 JSON 包含模块容器的创建选项。 Docker 创建选项	否
modules.{moduleId}.configuration.id	部署此模块的部署 ID。	在通过应用程序部署使用清单时，IoT 中心 会设置此属性。 不是部署清单的一部分。
version	包含版本、提交和内部版本的当前迭代。	否

EdgeAgent 报告属性

IoT Edge代理上报的属性包括三个主要方面的信息：

• 上一次出现的所需属性的应用程序状态，
• IoT Edge代理报告当前在设备上运行的模块的状态，以及
• 当前在设备上运行的所需属性的副本。

当前所需属性的副本可帮助你确定设备是应用了最新部署还是仍在运行以前的部署清单。

注意

可以使用 IoT 中心 查询语言查询IoT Edge代理报告的属性，以大规模调查部署状态。 有关如何使用 IoT Edge 代理属性来获取状态的信息，请参阅了解单设备 IoT Edge 部署或大规模 IoT Edge 部署。

下表不包括从所需属性复制的信息。

properties	说明
lastDesiredStatus.code	IoT Edge代理看到的最后所需属性的状态代码。 允许的值：200 成功、400 配置无效、412 架构版本无效、417 所需属性为空、500 失败。
lastDesiredStatus.description	状态的文本说明。
lastDesiredVersion	此整数是指IoT Edge代理处理的所需属性的最后一个版本。
runtime.platform.OS	报告设备上运行的 OS。
runtime.platform.architecture	报告设备上的 CPU 体系结构。
schemaVersion	报告属性的架构版本。
systemModules.edgeAgent.runtimeStatus	IoT Edge代理的报告状态：{ 运行中 | 不健康 }。
systemModules.edgeAgent.statusDescription	IoT Edge代理报告状态的文本描述。
systemModules.edgeAgent.exitCode	IoT Edge代理容器在退出时报告的退出代码。
systemModules.edgeAgent.lastStartTimeUtc	上次启动IoT Edge代理的时间。
systemModules.edgeAgent.lastExitTimeUtc	IoT Edge代理上次退出的时间。
systemModules.edgeHub.runtimeStatus	IoT Edge 中心的状态：{ running | stopped | failed | backoff | unhealthy }。
systemModules.edgeHub.statusDescription	IoT Edge集线器状态（不正常时）的文本描述。
systemModules.edgeHub.exitCode	由 IoT Edge 中心容器报告的退出代码（如果容器存在）。
systemModules.edgeHub.lastStartTimeUtc	上次启动IoT Edge中心的时间。
systemModules.edgeHub.lastExitTimeUtc	IoT Edge枢纽上次退出的时间。
systemModules.edgeHub.lastRestartTimeUtc	上次重启IoT Edge中心的时间。
systemModules.edgeHub.restartCount	作为重启策略的一部分，此模块重新启动的次数。
modules.{moduleId}.runtimeStatus	模块的状态：【正在运行 | 已停止 | 失败 | 退避 | 不健康】。
modules.{moduleId}.statusDescription	不正常的模块状态的文本说明。
modules.{moduleId}.exitCode	由模块容器报告的退出代码（如果容器存在）。
modules.{moduleId}.lastStartTimeUtc	上次启动模块的时间。
modules.{moduleId}.lastExitTimeUtc	上次退出模块的时间。
modules.{moduleId}.lastRestartTimeUtc	上次重启模块的时间。
modules.{moduleId}.restartCount	作为重启策略的一部分，此模块重新启动的次数。
version	映像的版本。 例如： "version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }。

EdgeHub 所需属性

IoT Edge中心的模块孪生称为 $edgeHub。 它协调在设备上运行的IoT Edge中心与IoT 中心之间的通信。 在将部署清单应用于特定设备时，无论是单台设备还是大规模部署，请设置所需属性。

properties	说明	部署清单中的必备项
schemaVersion	1.0 或 1.1。 版本 1.1 随 IoT Edge 版本 1.0.10 引入，推荐使用。	是
routes.{routeName}	表示IoT Edge中心路由的字符串。 有关详细信息，请参阅声明路由。	routes 元素可以存在但为空。
storeAndForwardConfiguration.timeToLiveSecs	在断开连接路由终结点（无论是 IoT 中心还是本地模块）的情况下，IoT Edge 中心保留消息的设备时间（以秒为单位）。 即使关机或重启，此时间也会保留。 有关详细信息，请参阅脱机功能。	是

EdgeHub 报告属性

properties	说明
lastDesiredVersion	此整数是指IoT Edge中心处理的所需属性的最后一个版本。
lastDesiredStatus.code	该状态代码指的是 IoT Edge 中心上次看到的所需属性。 允许的值： 200 成功、 400 配置无效、 500 失败。
lastDesiredStatus.description	状态的文本说明。
clients	所有连接到 edgeHub 的客户端，以及状态和上次连接时间。 示例："clients": { "device2/SimulatedTemperatureSensor": { "status": "Connected", "lastConnectedTimeUtc": "2022-11-17T21:49:16.4781564Z" } }。 有关此属性中显示的连接的详细信息，请参阅 哪些连接显示在该属性中 clients。
clients.{device or moduleId}.status	此设备或模块的连接状态。 可能的值： 已连接 或 断开连接。 仅模块标识可以处于断开连接状态。 连接到IoT Edge中心的下游设备仅在连接时显示。
clients.{device or moduleId}.lastConnectTime	上次连接设备或模块的时间。
clients.{device or moduleId}.lastDisconnectTime	上次断开连接设备或模块的时间。
schemaVersion	报告属性的架构版本。
version	映像的版本。 例如： "version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }。

哪些连接会显示在 clients 中

clients 报告的属性会列出本地 edgeHub 所服务的每个独立逻辑连接，但其自身的 $edgeHub 标识除外。 具体如下：

• 同一边缘设备上的模块 显示为 <deviceId>/<moduleName>。 这包括 $edgeAgent，因为本地 edgeAgent 通过本地 edgeHub 进行连接。
• 下游 IoT Edge 子设备显示为 <childDeviceId>/$edgeHub 和 <childDeviceId>/$edgeAgent。 没有空的 <childDeviceId> 条目。 子项的 $edgeHub 连接是“网关层次结构中连接的客户端数”中引用的“设备自身连接”。
• 下游叶设备（非 IoT Edge 设备）显示为 <deviceId>，不带模块后缀。
• 有意省略本地 edgeHub 自己的标识（<deviceId>/$edgeHub），以避免自我引用。

当模块断开连接时，其条目仍保留在 clients 中，状态为 Disconnected。 当下游设备断开连接时，系统会从 clients 中删除其条目。 可见条目数等于针对 MaxConnectedClients 预设的预算数量。 没有隐藏的其他连接。

后续步骤

有关如何使用这些属性来生成部署清单的信息，请参阅了解如何使用、配置和重复使用 IoT Edge 模块。