监视模块孪生

适用于： IoT Edge 1.5

重要

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

使用Azure IoT 中心中的模块孪生可以监视IoT Edge部署的连接性和运行状况。模块孪生在 IoT 中心存储有关正在运行的模块性能的信息。 IoT Edge agent 和 IoT Edge hub 运行时模块各自维护自己的模块孪生：$edgeAgent 和 $edgeHub。

$edgeAgent具有有关IoT Edge代理、IoT Edge中心运行时模块和自定义模块的运行状况和连接数据。 IoT Edge代理部署模块、监视模块，并将连接状态报告给Azure IoT中心。
$edgeHub包含设备上运行的IoT Edge中心与Azure IoT中心之间的通信数据。这包括处理来自下游设备的传入消息。 IoT Edge中心处理Azure IoT 中心与IoT Edge设备和模块之间的通信。

数据被组织为元数据、标记以及模块孪生的 JSON 结构中所需的和报告的属性集。在 deployment.json 文件中指定的所需属性会复制到模块孪生。 IoT Edge代理和IoT Edge中心每个更新其模块的报告属性。

同样，在 deploy.json 文件中为自定义模块指定的所需属性会复制到其模块孪生，但你的解决方案会提供其报告的属性值。

本文介绍如何在Azure门户、Azure CLI和Visual Studio Code中查看模块孪生。有关监控设备接收部署情况的信息，请参阅 Monitor IoT Edge 部署。有关模块孪生的概述，请参阅 Understand and use module twins in IoT 中心。

提示

如果IoT Edge设备与其 IoT 中心断开连接，则运行时模块的报告属性可能已过时。 Ping 模块 $edgeAgent 以检查连接是否丢失。

监视运行时模块孪生

若要排查部署连接问题，请查看 IoT Edge 代理模块和 IoT Edge 中心运行时模块双胞胎，然后深入查看其他模块。

监视 IoT Edge 代理模块孪生体

此JSON显示Visual Studio Code中$edgeAgent模块孪生，其中大多数部分已折叠。

{
  "deviceId": "Windows109",
  "moduleId": "$edgeAgent",
  "etag": "AAAAAAAAAAU=",
  "deviceEtag": "NzgwNjA1MDUz",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Disconnected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "version": 53,
  "properties": {
    "desired": { "···" },
    "reported": {
      "schemaVersion": "1.0",
      "version": { "···" },
      "lastDesiredStatus": { "···" },
      "runtime": { "···" },
      "systemModules": {
        "edgeAgent": { "···" },
        "edgeHub": { "···" }
      },
      "lastDesiredVersion": 5,
      "modules": {
        "SimulatedTemperatureSensor": { "···" }
      },
      "$metadata": { "···" },
      "$version": 48
    }
  }
}

此 JSON 包含以下部分：

元数据 - 具有连接性数据。 IoT Edge代理的连接状态始终"Disconnected"，因为它适用于设备到云（D2C）消息，IoT Edge代理不会发送 D2C 消息。
属性 - 具有 desired 和 reported 子部分。
Properties.desired -（折叠显示）在 deployment.json 文件中设置的预期属性值。
Properties.reported - IoT Edge代理报告的最新属性值。

这properties.desiredproperties.reported两个部分都具有类似的结构，并包括架构、版本和运行时信息的元数据。它们还有一个modules部分用于自定义模块，比如SimulatedTemperatureSensor，还有一个systemModules部分用于$edgeAgent和$edgeHub运行时模块。

将报告的属性值与所需值进行比较，以找出差异并标识断开连接，从而帮助排查问题。比较值时，请检查所调查属性的 $lastUpdated 部分中 metadata 报告的值。

故障排除时，请检查以下属性：

exitcode - 除零以外的任何值都表示模块因故障而停止。如果模块有意设置为已停止状态，则使用错误代码 137 或 143。
lastStartTimeUtc - 显示容器上次启动时的 DateTime 。如果未启动容器，则此值为 0001-01T00：00：00Z。
lastExitTimeUtc - 显示容器上次完成时的 DateTime 。如果容器正在运行且从未停止过，则此值为 0001-01-01T00:00:00Z。

runtimeStatus - 具有以下值之一：

价值	说明
未知	默认状态，直到部署创建完成。
退避	该模块计划启动，但未运行。此值对于正在重启的模块非常有用。当故障模块在冷却期间等待重启时，该模块处于退避状态。
正在运行	模块正在运行。
运行不正常	运行状况探测检查失败或超时。
已停止	模块已成功退出（零退出代码）。
“失败”	已退出该模块，并显示失败退出代码（非零）。根据重启策略，模块可以从当前状态返回到退避状态。此状态表示模块有不可恢复的错误。当IoT Edge代理无法重启模块（需要新部署）时，会发生失败。

有关详细信息，请参阅 EdgeAgent 报告的属性。

监视IoT Edge中心模块孪生

以下 JSON 显示 $edgeHub Visual Studio Code 模块孪生，其中大多数部分都折叠。

{
  "deviceId": "Windows109",
  "moduleId": "$edgeHub",
  "etag": "AAAAAAAAAAU=",
  "deviceEtag": "NzgwNjA1MDU2",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Connected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "version": 102,
    "properties": {
      "desired": { "···" },
      "reported": {
        "schemaVersion": "1.0",
        "version": { "···" },
      "lastDesiredVersion": 5,
      "lastDesiredStatus": { "···" },
      "clients": {
        "Windows109/SimulatedTemperatureSensor": {
          "status": "Disconnected",
          "lastConnectedTimeUtc": "2020-04-08T21:42:42.1743956Z",
          "lastDisconnectedTimeUtc": "2020-04-09T07:02:42.1398325Z"
        }
      },
      "$metadata": { "···" },
      "$version": 97
    }
  }
}

JSON 可以从顶部开始在以下部分中进行描述：

Metadata - 包含连接性数据。
Properties - 包含 desired 和 reported 子节。
Properties.desired -（显示为已折叠）运算符在 deployment.json 文件中设置的期望属性值。
Properties.reported - IoT Edge中心报告的最新属性值。

如果下游设备出现问题，请先检查此数据。

监视自定义模块孪生

IoT Edge代理模块孪生保留有关自定义模块连接的信息。自定义模块的模块孪生体主要用于存储解决方案相关的数据。在 deployment.json 文件中定义的所需属性显示在模块孪生中，模块可以根据需要更新报告的属性值。

将首选编程语言与 Azure IoT 中心设备 SDK配合使用，根据模块的应用程序代码更新模块孪生中的报告属性值。以下过程使用用于 .NET 的 Azure SDK 和来自SimulatedTemperatureSensor 模块的代码：

使用 CreateFromEnvironmentAsync 方法创建 ModuleClient 的实例。
使用 GetTwinAsync 方法获取模块孪生的属性。
使用 SetDesiredPropertyUpdateCallbackAsync 方法，创建一个具有回调功能的侦听器来捕获对所需属性的更改。
在回调方法中，使用 UpdateReportedPropertiesAsync 方法更新模块孪生中报告的属性，并传递要设置的属性值的 TwinCollection。

访问模块孪生

在 Azure IoT 中心、Visual Studio Code 或 Azure CLI 中查看模块孪生的 JSON。

在 Azure IoT 中心中监视

查看模块孪生的 JSON：

登录到 Azure 门户并导航到 IoT 中心。
在“设备管理”菜单下选择“设备”。
选择包含要监视模块的IoT Edge设备的 Device ID。
从“模块”选项卡中选择模块名称，然后从上部菜单栏中选择“模块标识孪生” 。

截图展示如何选择一个模块孪生以在 Azure 门户中查看。

如果看到消息“此模块不存在模块标识”，则此错误意味着最初创建的标识的后端解决方案不可用。

监视Visual Studio Code中的模块孪生

查看并编辑模块孪生：

安装 Azure IoT Edge 和 Azure IoT 中心扩展（如果尚未安装）。用于 Visual Studio Code 的 Azure IoT Edge 工具 处于维护模式。
在 Explorer 中，展开 Azure IoT 中心，然后使用要监视的模块展开设备。
选择模块，然后选择“编辑模块孪生”。该模块孪生的临时文件会下载到您的计算机，并在 Visual Studio Code 中打开。

进行更改后，在编辑器中的代码上方选择 “更新模块孪生 ”，将其保存到 IoT 中心。

截图显示如何在 Visual Studio Code 中更新模块孪生体。

监视Azure CLI中的模块孪生

使用 az iot hub invoke-module-method 命令检查IoT Edge是否正在运行，以 ping IoT Edge 代理。

az iot hub module-twin 结构提供以下命令：

az iot hub module-twin show - 显示模块孪生定义。
az iot hub module-twin update - 更新模块孪生定义。
az iot hub module-twin replace - 将模块孪生定义替换为目标 JSON。

提示

要使用 CLI 命令将运行时模块作为目标，可能需要对模块 ID 中的 $ 字符进行转义。例如：

az iot hub module-twin show -m '$edgeAgent' -n <hub name> -d <device name>

或：

az iot hub module-twin show -m \$edgeAgent -n <hub name> -d <device name>

后续步骤

了解如何使用内置直接方法与 EdgeAgent 通信。

Last updated on 2026-04-13

Compartilhar via