監視模組對應項
適用於： 
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 顯示 Visual Studio Code 中的 $edgeAgent 模組對應項，其中大部分的 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)，以及 $edgeAgent 和 $edgeHub 執行階段模組的和 systemModules 區段。
藉由比較報告屬性值與需要的值，您可以判斷出差異並識別中斷連線問題，以協助您進行疑難排解。 在執行這些比較時，請針對您正在調查的屬性，檢查 metadata 區段中的 $lastUpdated 報告值。
若要進行疑難排解，請務必檢查下列屬性：
exitcode - 除了零以外的任何值，表示模組因失敗而停止。 但如果模組是刻意設定為停止狀態，則會使用錯誤碼 137 或 143。
lastStartTimeUtc - 顯示容器前次啟動的 DateTime。 如果容器未啟動，則此值是 0001-01-01T00:00:00Z。
lastExitTimeUtc - 顯示容器前次完成的 DateTime。 如果容器正在執行中且從未停止，則此值是 0001-01-01T00:00:00Z。
runtimeStatus - 可以是下列其中一個值：
值 Description 未知 建立部署之前的預設狀態。 輪詢 模組已排定啟動，但目前未執行。 對於在重新啟動時發生狀態變更的模組而言，這個值很實用。 當失敗的模組在冷關機期間等待重新啟動時，模組將處於輪詢狀態。 執行中 表示模組目前正在執行中。 狀況不良 表示健康情況探查檢查失敗或逾時。 已停止 表示模組已順利結束 (結束代碼為零)。 失敗 表示模組已結束且產生失敗結束代碼 (非零)。 模組可依據生效的重新啟動原則，從此狀態轉換回輪詢。 此狀態可表示模組發生無法復原的錯誤。 當 Microsoft Monitoring Agent (MMA) 無法再重新復原模組而需要新的部署時，就會發生失敗。
如需詳細資訊，請參閱 EdgeAgent 報告屬性。
監視 IoT Edge 中樞模組對應項
下列 JSON 顯示 Visual Studio Code 中的 $edgeHub 模組對應項，其中大部分的 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 裝置的 [裝置識別碼]。
從 [模組] 索引標籤選取模組名稱，然後從上方功能表列選取 [模組 ID 對應項]。
如果您看到「此模組的模組 ID 不存在」訊息，此錯誤表示原本建立該 ID 的後端解決方案已無法使用。
在 Visual Studio Code 中監視模組對應項
若要檢閱和編輯模組對應項：
如果尚未安裝，請安裝 Azure IoT Edge 和 Azure IoT 中樞延伸模組。 「適用於 Visual Studio Code 的 Azure IoT Edge 工具」延伸模組目前是維護模式。
在 [Explorer] 中，展開 [Azure IoT 中樞]，然後展開您要監視的模組所屬的裝置。
以滑鼠右鍵按一下模組，然後選取 [編輯模組對應項]。 模組對應項的暫存檔會下載到您的電腦，並顯示在 Visual Studio Code 中。
如果您進行變更，請在編輯器中的程式碼上方選取 [更新模組對應項]，將變更儲存至 IoT 中樞。
在 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>