监视模块孪生

适用于：IoT Edge 1.5

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 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 - 具有以下值之一：

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

1. 使用 CreateFromEnvironmentAsync 方法创建 ModuleClient 的实例。

2. 使用 GetTwinAsync 方法获取模块孪生的属性。

3. 使用 SetDesiredPropertyUpdateCallbackAsync 方法，创建一个具有回调功能的侦听器来捕获对所需属性的更改。

4. 在回调方法中，使用 UpdateReportedPropertiesAsync 方法更新模块孪生中报告的属性，并传递要设置的属性值的 TwinCollection。

访问模块孪生

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

在 Azure IoT 中心中进行监视

查看模块孪生的 JSON：

1. 登录 Azure 门户，导航到 IoT 中心。

2. 在“设备管理”菜单下选择“设备”。

3. 选择包含要监视的模块的 IoT Edge 设备的设备 ID。

4. 从“模块”选项卡中选择模块名称，然后从上部菜单栏中选择“模块标识孪生” 。

   

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

在 Visual Studio Code 中监视模块孪生

查看并编辑模块孪生：

1. 安装 Azure IoT Edge 和 Azure IoT 中心 扩展（如果尚未安装）。 适用于 Visual Studio Code 的 Azure IoT Edge 工具扩展处于维护模式。

2. 在 资源管理器中，展开 Azure IoT 中心，然后展开包含要监控模块的设备。

3. 选择模块，然后选择“编辑模块孪生”。 模块孪生的临时文件会下载到计算机并在 Visual Studio Code 中打开。

   

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

在 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。

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 通信。