你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

监视模块孪生

2025-06-11

适用于：IoT Edge 1.5

重要

IoT Edge 1.5 LTS 是受支持的版本。 IoT Edge 1.4 LTS 的生命周期结束日期为 2024 年 11 月 12 日。如果你使用的是较低的版本，请参阅更新 IoT Edge。

Azure IoT 中心中的模块孪生可用于监视 IoT Edge 部署的连接性和运行状况。模块孪生在 IoT 中心存储有关正在运行的模块性能的信息。 IoT Edge 代理和 IoT Edge 中心运行时模块各自维护其自己的模块孪生：$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 中查看模块孪生。有关监视设备接收部署的方式的信息，请参阅监视 IoT Edge 部署。有关模块孪生的概述，请参阅了解和使用 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运行时模块。

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

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

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

runtimeStatus - 具有以下值之一：

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

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

监视 IoT Edge 中心模块孪生

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

{
  "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 设备的设备 ID。
从“模块”选项卡中选择模块名称，然后从上部菜单栏中选择“模块标识孪生” 。

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

在 Visual Studio Code 中监视模块孪生

查看并编辑模块孪生：

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

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

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

在 Azure CLI 中监视模块孪生

使用 az iot hub invoke-module-method 命令 ping IoT Edge 代理，以检测 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 通信。

通过