IoT Edge 代理和 IoT Edge 中心模块孪生的属性Properties of the IoT Edge agent and IoT Edge hub module twins

IoT Edge 代理和 IoT Edge 中心是构成 IoT Edge 运行时的两个模块。The IoT Edge agent and IoT Edge hub are two modules that make up the IoT Edge runtime. 有关每个运行时模块的职责的详细信息,请参阅了解 Azure IoT Edge 运行时及其体系结构For more information about the responsibilities of each runtime module, see Understand the Azure IoT Edge runtime and its architecture.

本文提供运行时模块孪生的所需属性和报告属性。This article provides the desired properties and reported properties of the runtime module twins. 有关如何在 IoT Edge 设备上部署模块的详细信息,请参阅了解如何在 IoT Edge 中部署模块和建立路由For more information on how to deploy modules on IoT Edge devices, see Learn how to deploy modules and establish routes in IoT Edge.

模块孪生包括:A module twin includes:

  • 所需的属性Desired properties. 解决方案后端可设置所需的属性,而模块可以读取这些属性。The solution backend can set desired properties, and the module can read them. 此外,模块还可以收到有关所需的属性发生更改的通知。The module can also receive notifications of changes in the desired properties. 将所需的属性与报告的属性结合使用,可以同步模块配置或条件。Desired properties are used along with reported properties to synchronize module configuration or conditions.

  • 报告的属性Reported properties. 模块可以设置报告的属性,而解决方案后端可以读取和查询这些属性。The module can set reported properties, and the solution backend can read and query them. 报告的属性与所需的属性结合使用,可同步模块配置或状况。Reported properties are used along with desired properties to synchronize module configuration or conditions.

EdgeAgent 所需属性EdgeAgent desired properties

IoT Edge 代理的模块孪生被称为 $edgeAgent,用于协调在设备上运行的与在 IoT 中心运行的 IoT Edge 代理之间的通信。The module twin for the IoT Edge agent is called $edgeAgent and coordinates the communications between the IoT Edge agent running on a device and IoT Hub. 在特定设备上将部署清单作为单一设备或规模部署的一部分应用时,将会设置所需的属性。The desired properties are set when applying a deployment manifest on a specific device as part of a single-device or at-scale deployment.

属性Property 说明Description 必须Required
schemaVersionschemaVersion 必须为“1.0”Has to be "1.0" Yes
runtime.typeruntime.type 必须为“docker”Has to be "docker" Yes
runtime.settings.minDockerVersionruntime.settings.minDockerVersion 设置为此部署清单所需的最小 Docker 版本Set to the minimum Docker version required by this deployment manifest Yes
runtime.settings.loggingOptionsruntime.settings.loggingOptions 字符串化的 JSON 包含 IoT Edge 代理容器的日志记录选项。A stringified JSON containing the logging options for the IoT Edge agent container. Docker 日志记录选项Docker logging options No
runtime.settings.registryCredentialsruntime.settings.registryCredentials
.{registryId}.username.{registryId}.username
容器注册表的用户名。The username of the container registry. 对于 Azure 容器注册表,用户名通常是注册表名称。For Azure Container Registry, the username is usually the registry name.

注册表凭据对于任何专用模块映像都是必需的。Registry credentials are necessary for any private module images.
No
runtime.settings.registryCredentialsruntime.settings.registryCredentials
.{registryId}.password.{registryId}.password
容器注册表的密码。The password for the container registry. No
runtime.settings.registryCredentialsruntime.settings.registryCredentials
.{registryId}.address.{registryId}.address
容器注册表的地址。The address of the container registry. 对于 Azure 容器注册表,地址通常为“{registry name}.azurecr.cn” 。For Azure Container Registry, the address is usually {registry name}.azurecr.cn. No
systemModules.edgeAgent.typesystemModules.edgeAgent.type 必须为“docker”Has to be "docker" Yes
systemModules.edgeAgent.settings.imagesystemModules.edgeAgent.settings.image IoT Edge 代理的映像 URI。The URI of the image of the IoT Edge agent. 目前,IoT Edge 代理不能自行更新。Currently, the IoT Edge agent isn't able to update itself. Yes
systemModules.edgeAgent.settingssystemModules.edgeAgent.settings
.createOptions.createOptions
字符串化的 JSON 包含 IoT Edge 代理容器的创建选项。A stringified JSON containing the options for the creation of the IoT Edge agent container. Docker 创建选项Docker create options No
systemModules.edgeAgent.configuration.idsystemModules.edgeAgent.configuration.id 部署此模块的部署 ID。The ID of the deployment that deployed this module. 此属性是在使用部署来应用清单时由 IoT 中心设置。IoT Hub sets this property when the manifest is applied using a deployment. 不是部署清单的一部分。Not part of a deployment manifest.
systemModules.edgeHub.typesystemModules.edgeHub.type 必须为“docker”Has to be "docker" Yes
systemModules.edgeHub.statussystemModules.edgeHub.status 必须为“running”Has to be "running" Yes
systemModules.edgeHub.restartPolicysystemModules.edgeHub.restartPolicy 必须为“always”Has to be "always" Yes
systemModules.edgeHub.settings.imagesystemModules.edgeHub.settings.image IoT Edge 中心的映像 URI。The URI of the image of the IoT Edge hub. Yes
systemModules.edgeHub.settingssystemModules.edgeHub.settings
.createOptions.createOptions
字符串化的 JSON 包含 IoT Edge 中心容器的创建选项。A stringified JSON containing the options for the creation of the IoT Edge hub container. Docker 创建选项Docker create options No
systemModules.edgeHub.configuration.idsystemModules.edgeHub.configuration.id 部署此模块的部署 ID。The ID of the deployment that deployed this module. 此属性是在使用部署来应用清单时由 IoT 中心设置。IoT Hub sets this property when the manifest is applied using a deployment. 不是部署清单的一部分。Not part of a deployment manifest.
modules.{moduleId}.versionmodules.{moduleId}.version 用户定义的字符串,表示此模块的版本。A user-defined string representing the version of this module. Yes
modules.{moduleId}.typemodules.{moduleId}.type 必须为“docker”Has to be "docker" Yes
modules.{moduleId}.statusmodules.{moduleId}.status {"running" | "stopped"}{"running" | "stopped"} Yes
modules.{moduleId}.restartPolicymodules.{moduleId}.restartPolicy {"never" | "on-failure" | "on-unhealthy" | "always"}{"never" | "on-failure" | "on-unhealthy" | "always"} Yes
modules.{moduleId}.imagePullPolicymodules.{moduleId}.imagePullPolicy {"on-create" | "never"}{"on-create" | "never"} No
modules.{moduleId}.envmodules.{moduleId}.env 要传递给模块的环境变量的列表。A list of environment variables to pass to the module. 采用格式 "<name>": {"value": "<value>"}Takes the format "<name>": {"value": "<value>"} No
modules.{moduleId}.settings.imagemodules.{moduleId}.settings.image 模块映像的 URI。The URI to the module image. Yes
modules.{moduleId}.settings.createOptionsmodules.{moduleId}.settings.createOptions 字符串化的 JSON 包含模块容器的创建选项。A stringified JSON containing the options for the creation of the module container. Docker 创建选项Docker create options No
modules.{moduleId}.configuration.idmodules.{moduleId}.configuration.id 部署此模块的部署 ID。The ID of the deployment that deployed this module. 此属性是在使用部署来应用清单时由 IoT 中心设置。IoT Hub sets this property when the manifest is applied using a deployment. 不是部署清单的一部分。Not part of a deployment manifest.

EdgeAgent 报告属性EdgeAgent reported properties

IoT Edge 代理报告属性包括三个主要信息:The IoT Edge agent reported properties include three main pieces of information:

  1. 上一次出现的所需属性的应用程序状态;The status of the application of the last-seen desired properties;
  2. IoT Edge 代理报告的目前在设备上运行的模块的状态;以及The status of the modules currently running on the device, as reported by the IoT Edge agent; and
  3. 当前在设备上运行的所需属性的副本。A copy of the desired properties currently running on the device.

当前所需属性的副本有助于判断设备是应用了最新部署,还是仍在运行以前的部署清单。The copy of the current desired properties is useful to tell whether the device has applied the latest deployment or is still running a previous deployment manifest.

备注

IoT Edge 代理报告的属性非常有用,因为可以使用 IoT 中心查询语言对其进行查询,进而调查大规模部署的状态。The reported properties of the IoT Edge agent are useful as they can be queried with the IoT Hub query language to investigate the status of deployments at scale. 若要详细了解如何使用 IoT Edge 代理属性来获取状态,请参阅了解单设备 IoT Edge 部署或大规模 IoT Edge 部署For more information on how to use the IoT Edge agent properties for status, see Understand IoT Edge deployments for single devices or at scale.

下表不包括从所需属性中复制的信息。The following table does not include the information that is copied from the desired properties.

属性Property 说明Description
lastDesiredVersionlastDesiredVersion 此整数指的是由 IoT Edge 代理处理的所需属性的最后一个版本。This integer refers to the last version of the desired properties processed by the IoT Edge agent.
lastDesiredStatus.codelastDesiredStatus.code 此状态代码指的是 IoT Edge 代理上次看到的所需属性。This status code refers to the last desired properties seen by the IoT Edge agent. 允许的值:200 成功、400 配置无效、412 架构版本无效、417 所需属性为空、500 失败Allowed values: 200 Success, 400 Invalid configuration, 412 Invalid schema version, 417 the desired properties are empty, 500 Failed
lastDesiredStatus.descriptionlastDesiredStatus.description 状态的文本说明Text description of the status
deviceHealthdeviceHealth 如果所有模块的运行时状态为 runningstopped,则为 healthy,否则为 unhealthyhealthy if the runtime status of all modules is either running or stopped, unhealthy otherwise
configurationHealth.{deploymentId}.healthconfigurationHealth.{deploymentId}.health 如果部署 {deploymentId} 设置的所有模块的运行时状态为 runningstopped,则为 healthy,否则为 unhealthyhealthy if the runtime status of all modules set by the deployment {deploymentId} is either running or stopped, unhealthy otherwise
runtime.platform.OSruntime.platform.OS 报告在设备上运行的 OSReporting the OS running on the device
runtime.platform.architectureruntime.platform.architecture 报告设备上的 CPU 体系结构Reporting the architecture of the CPU on the device
systemModules.edgeAgent.runtimeStatussystemModules.edgeAgent.runtimeStatus IoT Edge 代理的报告状态:{"running" | "unhealthy"}The reported status of IoT Edge agent: {"running" | "unhealthy"}
systemModules.edgeAgent.statusDescriptionsystemModules.edgeAgent.statusDescription IoT Edge 代理报告状态的文本说明。Text description of the reported status of the IoT Edge agent.
systemModules.edgeHub.runtimeStatussystemModules.edgeHub.runtimeStatus IoT Edge 中心的状态:{ "running" | "stopped" | "failed" | "backoff" | "unhealthy" }Status of IoT Edge hub: { "running" | "stopped" | "failed" | "backoff" | "unhealthy" }
systemModules.edgeHub.statusDescriptionsystemModules.edgeHub.statusDescription 运行不正常情况下 IoT Edge 中心状态的文本说明。Text description of the status of IoT Edge hub if unhealthy.
systemModules.edgeHub.exitCodesystemModules.edgeHub.exitCode 由 IoT Edge 中心容器报告的退出代码(如果容器存在)The exit code reported by the IoT Edge hub container if the container exits
systemModules.edgeHub.startTimeUtcsystemModules.edgeHub.startTimeUtc 上一次启动 IoT Edge 中心的时间Time when IoT Edge hub was last started
systemModules.edgeHub.lastExitTimeUtcsystemModules.edgeHub.lastExitTimeUtc IoT Edge 中心上一次退出的时间Time when IoT Edge hub last exited
systemModules.edgeHub.lastRestartTimeUtcsystemModules.edgeHub.lastRestartTimeUtc 上一次重启 IoT Edge 中心的时间Time when IoT Edge hub was last restarted
systemModules.edgeHub.restartCountsystemModules.edgeHub.restartCount 作为重启策略的一部分,此模块重新启动的次数。Number of times this module was restarted as part of the restart policy.
modules.{moduleId}.runtimeStatusmodules.{moduleId}.runtimeStatus 模块的状态:{ "running" | "stopped" | "failed" | "backoff" | "unhealthy" }Status of the module: { "running" | "stopped" | "failed" | "backoff" | "unhealthy" }
modules.{moduleId}.statusDescriptionmodules.{moduleId}.statusDescription 运行不正常情况下模块状态的文本说明。Text description of the status of the module if unhealthy.
modules.{moduleId}.exitCodemodules.{moduleId}.exitCode 由模块容器报告的退出代码(如果容器存在)The exit code reported by the module container if the container exits
modules.{moduleId}.startTimeUtcmodules.{moduleId}.startTimeUtc 模块的上次启动时间Time when the module was last started
modules.{moduleId}.lastExitTimeUtcmodules.{moduleId}.lastExitTimeUtc 模块的上次退出时间Time when the module last exited
modules.{moduleId}.lastRestartTimeUtcmodules.{moduleId}.lastRestartTimeUtc 模块的上次重启时间Time when the module was last restarted
modules.{moduleId}.restartCountmodules.{moduleId}.restartCount 作为重启策略的一部分,此模块重新启动的次数。Number of times this module was restarted as part of the restart policy.

EdgeHub 所需属性EdgeHub desired properties

IoT Edge 中心的模块孪生被称为 $edgeHub,用于协调在设备上运行的与在 IoT 中心运行的 IoT Edge 中心之间的通信。The module twin for the IoT Edge hub is called $edgeHub and coordinates the communications between the IoT Edge hub running on a device and IoT Hub. 在特定设备上将部署清单作为单一设备或规模部署的一部分应用时,将会设置所需的属性。The desired properties are set when applying a deployment manifest on a specific device as part of a single-device or at-scale deployment.

属性Property 说明Description 部署清单中的必备项Required in the deployment manifest
schemaVersionschemaVersion 必须为“1.0”Has to be "1.0" Yes
routes.{routeName}routes.{routeName} 表示 IoT Edge 中心路由的字符串。A string representing an IoT Edge hub route. 有关详细信息,请参阅声明路由For more information, see Declare routes. routes 元素可以存在但为空。The routes element can be present but empty.
storeAndForwardConfiguration.timeToLiveSecsstoreAndForwardConfiguration.timeToLiveSecs 在断开连接路由终结点(无论是 IoT 中心还是本地模块)的情况下,IoT Edge 中心保留消息的时长(以秒为单位)。The time in seconds that IoT Edge hub keeps messages if disconnected from routing endpoints, whether IoT Hub or a local module. 该值可以是任何正整数。The value can be any positive integer. Yes

EdgeHub 报告属性EdgeHub reported properties

属性Property 说明Description
lastDesiredVersionlastDesiredVersion 此整数指的是由 IoT Edge 中心处理的所需属性的最后一个版本。This integer refers to the last version of the desired properties processed by the IoT Edge hub.
lastDesiredStatus.codelastDesiredStatus.code 该状态代码指的是 IoT Edge 中心上次看到的所需属性。The status code referring to last desired properties seen by the IoT Edge hub. 允许的值:200 成功、400 配置无效、500 失败Allowed values: 200 Success, 400 Invalid configuration, 500 Failed
lastDesiredStatus.descriptionlastDesiredStatus.description 状态的文本说明。Text description of the status.
clients.{device or moduleId}.statusclients.{device or moduleId}.status 此设备或模块的连接状态。The connectivity status of this device or module. 可能值:{"connected" | "disconnected"}。Possible values {"connected" | "disconnected"}. 仅模块标识可以处于断开连接状态。Only module identities can be in disconnected state. 仅在连接时才会显示连接到 IoT Edge 中心的下游设备。Downstream devices connecting to IoT Edge hub appear only when connected.
clients.{device or moduleId}.lastConnectTimeclients.{device or moduleId}.lastConnectTime 上次连接设备或模块的时间。Last time the device or module connected.
clients.{device or moduleId}.lastDisconnectTimeclients.{device or moduleId}.lastDisconnectTime 上次断开连接设备或模块的时间。Last time the device or module disconnected.

后续步骤Next steps

若要了解如何使用这些属性构建部署清单,请参阅了解如何使用、配置和重用 IoT Edge 模块To learn how to use these properties to build out deployment manifests, see Understand how IoT Edge modules can be used, configured, and reused.