監視模組對應項

適用於： IoT Edge 1.5

重要

IoT Edge 1.5 LTS 是支援的版本。自 2024 年 11 月 12 日起，IoT Edge 1.4 LTS 已結束生命週期。如果您是舊版，請參閱更新 IoT Edge。

Azure IoT Hub 中的模組雙胞胎可讓您監視 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 中樞會各自更新其模組的報告屬性。

同樣地，您在 deployment.json 檔案中為自定義模組指定的所需屬性會複製到其模組孿生項，但您的解決方案則提供該模組的報告屬性值。

本文說明如何在 Azure 入口網站、Azure CLI 和 Visual Studio Code 中檢閱模組對應項。如需監視裝置如何接收部署的相關資訊，請參閱監視 IoT Edge 部署。如需模組對應項的概觀，請參閱瞭解和使用IoT中樞中的模組對應項。

提示

如果 IoT Edge 裝置與其 IoT 中樞中斷連線，運行時間模組的報告屬性可能會過時。 Ping 模組 $edgeAgent 以檢查連線是否遺失。

監視執行階段模組對應項

若要針對部署連線問題進行疑難排解，請檢閱 IoT Edge 代理程式和 IoT Edge 中樞執行階段模組對應項，然後向下深入探索其他模組。

監視 IoT Edge 代理程式模組對應項

此 JSON 顯示 $edgeAgent Visual Studio Code 中已將大部分區段折疊的模組副本。

{
  "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.desired和 properties.reported 區段都有類似的結構，並包含架構、版本和運行時間資訊的元數據。它們也有一個 modules 區段供自訂模組（例如 SimulatedTemperatureSensor）使用，以及一個 systemModules 區段供 $edgeAgent 和 $edgeHub 運行時間模組使用。

比較報告的屬性值與期望值，以找出不一致之處和斷線問題，這樣可以協助您對問題進行疑難排解。當您比較值時，請檢查您要調查的屬性在 $lastUpdated 區段中的 metadata 報告值。

在疑難排解過程中，請檢查以下特性：

exitcode - 除了零以外的任何值，表示模組因失敗而停止。如果模組刻意設定為已停止狀態，則會使用錯誤碼 137 或 143。
lastStartTimeUtc - 顯示容器上次啟動時的 DateTime 。如果未啟動容器，此值為 0001-01-01T00：00：00Z。
lastExitTimeUtc - 顯示容器上次完成時的 DateTime 。如果容器正在執行中且從未停止，則此值是 0001-01-01T00:00:00Z。

runtimeStatus - 具有下列其中一個值：

值	說明
未知	建立部署之前的預設狀態。
輪詢	模組已排程啟動，但未執行。這個值對於正在重新啟動的模組很有用。當失敗的模組在冷卻期間等待重新啟動時，模組會處於退避狀態。
執行中	模組正在執行。
狀況不良	健康檢測未通過或逾時。
已停止	模組已順利退出（退出碼為零）。
失敗	模組退出時返回錯誤退出代碼（非零）。模組可以根據重啟原則，從此狀態返回到退避階段。此狀態表示模組發生無法復原的錯誤。當Microsoft監視代理程式（MMA）無法重新啟動模組，需要新的部署時，就會發生失敗。

如需詳細資訊，請參閱 EdgeAgent報告屬性。

監視 IoT Edge 中樞模組對應項

下列 JSON 顯示位於 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：

中繼資料 - 包含連線資料。
屬性 - 包含 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 工具」延伸模組目前是維護模式。
在 Explorer 中，展開 Azure IoT Hub，然後展開包含您想要監視模組的裝置。
選取模組，然後選取 [編輯模組對應項]。模組配對項的臨時檔會下載到您的電腦，並在 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 命令鎖定執行時間模組，您可能需要轉義模組識別元中的 $ 字元。例如：

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 2025-06-09