監視模組對應項

發行項
04/11/2024

適用於： IoT Edge 1.5 IoT Edge 1.4

重要

支援 IoT Edge 1.5 LTS 和 IoT Edge 1.4 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 中樞會更新其模組的報告屬性。

同樣地，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 中的模組對應項，其中大部分的 JSON 區段都會折疊。

{
  "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 代理程式的連線狀態一律處於中斷聯機狀態： "connectionState": "Disconnected"。連線狀態與裝置到雲端（D2C）訊息有關的原因，而 IoT Edge 代理程式不會傳送 D2C 訊息。
屬性 - 包含 desired 和 reported 子區段。
Properties.desired - （顯示折疊） deployment.json 檔案中運算符所設定的預期屬性值。
Properties.reported - IoT Edge 代理程式所報告的最新屬性值。

properties.desired和 properties.reported 區段都有類似的結構，並包含架構、版本和運行時間資訊的其他元數據。此外，modules也包含任何自定義模組的區段（例如 SimulatedTemperatureSensor），以及 systemModules 和運行時間模組的 $edgeHub 區段$edgeAgent。

藉由比較回報的屬性值與所需的值，您可以判斷不一致，並找出可協助您針對問題進行疑難解答的中斷連線。在進行這些比較時，請檢查 $lastUpdated 區段中所報告的值 metadata ，以取得您要調查的屬性。

下列屬性對於檢查疑難解答很重要：

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

runtimeStatus - 可以是下列其中一個值：

值	Description
未知	在建立部署之前的默認狀態。
退避	模組已排定啟動，但目前未執行。這個值對於在重新啟動時進行狀態變更的模組很有用。當失敗的模組在冷卻期間等待重新啟動時，模組會處於輪詢狀態。
執行中	表示模組目前正在執行中。
不良	表示健康情況探查檢查失敗或逾時。
已停止	表示模組已順利結束（含零結束代碼）。
失敗	表示模組結束時發生失敗結束代碼（非零）。模組可以根據生效的重新啟動原則，從此狀態轉換迴輪詢。此狀態可能表示模組發生無法復原的錯誤。當 Microsoft Monitoring Agent （MMA）無法再恢復模組時，就會發生失敗，而需要新的部署。

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

監視 IoT Edge 中樞模組對應項

下列 JSON 顯示 $edgeHub Visual Studio Code 中的模組對應項，其中大部分的 JSON 區段都會折疊。

{
  "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 模組的程式代碼：

使用 CreateFromEnvironmentAysnc 方法建立 ModuleClient 的實例。
使用 GetTwinAsync 方法取得模組對應項屬性的集合。
使用 SetDesiredPropertyUpdateCallbackAsync 方法建立接聽程式（傳遞回呼），以攔截所需屬性的變更。
在回呼方法中，使用 UpdateReportedPropertiesAsync 方法更新模組對應項中的報告屬性，並傳遞您要設定之屬性值的 TwinCollection 。

存取模組對應項

您可以在 Azure IoT 中樞、Visual Studio Code 和 Azure CLI 中檢閱模組對應項的 JSON。

在Azure IoT 中樞中監視

若要檢視模組對應項的 JSON：

登入 Azure 入口網站並流覽至您的IoT中樞。
選取 [裝置管理] 功能表下的 [裝置]。
使用您想要監視的模組，選取IoT Edge裝置的裝置識別碼。
從 [模組 ] 索引標籤中選取模組名稱，然後從上方功能表欄選取 [模組識別對應項 ]。

如果您看到「此模組的模組身分識別不存在」訊息，此錯誤表示後端解決方案已不再提供原本建立身分識別的訊息。

在 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 中監視模組對應項

若要查看 IoT Edge 是否正在執行，請使用 az iot hub invoke-module-method 來 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 命令為目標的執行時間模組，您可能需要逸出 $ 模組識別元中的字元。例如：

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

共用方式為

監視模組對應項

監視運行時間模組對應項

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

監視 IoT Edge 中樞模組對應項

監視自定義模組對應項

存取模組對應項

在Azure IoT 中樞中監視

在 Visual Studio Code 中監視模組對應項

在 Azure CLI 中監視模組對應項

下一步

其他資源

共用方式為

監視模組對應項

監視運行時間模組對應項

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

監視 IoT Edge 中樞模組對應項

監視自定義模組對應項

存取模組對應項

在Azure IoT 中樞 中監視

在 Visual Studio Code 中監視模組對應項

在 Azure CLI 中監視模組對應項

下一步

其他資源

在Azure IoT 中樞中監視