適用於：
IoT Edge 1.5
重要事項
IoT Edge 1.5 LTS 是受支援的版本。 自 2024 年 11 月 12 日起，IoT Edge 1.4 LTS 已結束生命週期。 如果您採用舊版，請參閱更新 IoT Edge。
IoT Edge 代理程式和 IoT Edge 中樞是構成 IoT Edge 執行階段的兩個模組。 如需每個運行時間模組責任的詳細資訊，請參閱 瞭解 Azure IoT Edge 運行時間及其架構。
本文提供執行階段模組對應項的所需屬性和報告屬性。 如需如何在IoT Edge裝置上部署模組的詳細資訊，請參閱 瞭解如何在IoT Edge中部署模組和建立路由。
模組對應項包含：
預期屬性。 解決方案後端會設定所需的屬性，而模組會讀取它們。 模組也會接收所需屬性中變更的通知。 預期屬性會搭配回報的屬性使用，以便同步處理模組的設定或條件。
回報的屬性。 模組會設定報告的屬性，而解決方案後端會讀取和查詢它們。 報告的屬性會搭配所需屬性使用，以同步模組設定或條件。
EdgeAgent 預期屬性
IoT Edge 代理程式的模組孿生稱為 $edgeAgent。 它會協調在裝置上執行的IoT Edge代理程式與IoT中樞之間的通訊。 在特定裝置上套用部署資訊清單以成為單一裝置或大規模部署的一部分時，即會設定預期屬性。
| 屬性 | 描述 | 必要 |
|---|---|---|
| imagePullPolicy | 指定何時提取映像： OnCreate 或 Never。 如果映射已經在裝置上，請使用 Never 。 | 是的 |
| restartPolicy | 應該重新啟動模組時。 可能的值為：Never：若未執行，請勿重新啟動模組、Always：若未執行，一律重新啟動模組、On-Unhealthy：如果狀況不良則重新啟動模組。 狀況不良是 Docker 根據健康健全狀況檢查的內容，例如「狀況不良 - 容器無法正常運作」、On-Failed：如果失敗，請重新啟動。 | 是的 |
| 執行時類型 | 必須是 docker。 | 是的 |
| runtime.settings.minDockerVersion | 指定此部署指令清單所需的最低 Docker 版本。 | 是的 |
| runtime.settings.loggingOptions | 指定適用於 IoT Edge 代理程式容器之記錄選項的字串化 JSON。 深入瞭解 Docker 記錄選項。 | 否 |
| runtime.settings.registryCredentials.{registryId}.username | 指定容器登錄的用戶名稱。 針對 Azure Container Registry，使用者名稱通常是登錄名稱。 私人模組映像需要登錄認證。 | 否 |
| runtime.settings.registryCredentials.{registryId}.password | 容器登錄的密碼。 | 否 |
| runtime.settings.registryCredentials.{registryId}.address | 容器登錄的位址。 針對 Azure Container Registry，位址通常是 {registry name}.azurecr.io。 | 否 |
| schemaVersion | 指定 1.0 或 1.1。 建議使用在IoT Edge 1.0.10版中引入的1.1版。 | 是的 |
| 狀態 | 模組的所需狀態：Running 或 Stopped。 | 必要 |
| systemModules.edgeAgent.type | 必須為 docker。 | 是的 |
| systemModules.edgeAgent.startupOrder | 指定以啟動順序表示模組位置的整數。 0 是第一個， 而最大整數 （4294967295） 是最後一個。 如果未提供任何值，則預設值為 最大整數。 | 否 |
| systemModules.edgeAgent.settings.image | 指定 IoT Edge 代理程式映像的 URI。 IoT Edge 代理程式無法自行更新。 | 是的 |
| systemModules.edgeAgent.settings.createOptions | 指定包含建立 IoT Edge 代理程式容器選項的字串化 JSON。 深入瞭解 Docker 建立選項。 | 否 |
| systemModules.edgeAgent.configuration.id | 部署此模組的部署識別碼。 | IoT 中樞會在使用部署套用資訊清單時設定此屬性。 並非部署資訊清單的一部分。 |
| systemModules.edgeHub.type（系統模組.edgeHub.類型） | 必須為 docker。 | 是的 |
| systemModules.edgeHub.status | 必須為 running。 | 是的 |
| systemModules.edgeHub.restartPolicy | 必須為 always。 | 是的 |
| systemModules.edgeHub.startupOrder | 整數值，會在啟動順序中找出模組。 0 是第一個，最大整數 (4294967295) 是最後一個。 如果未提供值，預設值為最大整數。 | 否 |
| systemModules.edgeHub.settings.image | IoT Edge 中樞映像的 URI。 | 是的 |
| systemModules.edgeHub.settings.createOptions | 包含適用於建立 IoT Edge 中樞容器之選項的字串化 JSON。 Docker 建立選項 | 否 |
| systemModules.edgeHub.configuration.id | 部署此模組的部署識別碼。 | IoT 中樞會在使用部署套用資訊清單時設定此屬性。 並非部署資訊清單的一部分。 |
| modules.{moduleId}.version | 代表此模組版本的使用者定義字串。 | 是的 |
| modules.{moduleId}.type | 必須為 docker。 | 是的 |
| modules.{moduleId}.status | {運行中 | 已停止} | 是的 |
| modules.{moduleId}.restartPolicy | {從不 | 永遠} | 是的 |
| modules.{moduleId}.startupOrder | 在啟動順序中用於模組位置的整數值。 0 是第一個，最大整數 (4294967295) 是最後一個。 如果未提供值，預設值為最大整數。 | 否 |
| modules.{moduleId}.imagePullPolicy | {on-create | never} | 否 |
| modules.{moduleId}.env | 要傳遞至模組的環境變數清單。 採用格式："<name>": {"value": "<value>"}。 |
否 |
| modules.{moduleId}.settings.image | 模組映像的 URI。 | 是的 |
| 模組.{moduleId}.設定.建立選項 | 包含適用於建立模組容器之選項的字串化 JSON。 Docker 建立選項 | 否 |
| modules.{moduleId}.configuration.id | 部署此模組的部署識別碼。 | IoT 中樞會在使用部署套用資訊清單時設定此屬性。 並非部署資訊清單的一部分。 |
| 版本 | 目前具有版本、認可和建置的的反覆運算。 | 否 |
EdgeAgent 回報的屬性
IoT Edge 代理程式報告屬性包含三個主要資訊：
- 最後看到之預期屬性的應用程式狀態，
- 目前在裝置上執行的模組狀態，如 IoT Edge 代理程式所報告，以及
- 目前在裝置上執行之所需屬性的複本。
目前所需屬性的複本有助於判斷裝置是否已套用最新的部署，或仍在執行先前的部署指令清單。
附註
您可以使用 IoT中樞查詢語言來查詢IoT Edge代理程式報告屬性，以大規模調查部署狀態。 在瞭解單一裝置或大規模 IoT Edge 部署中，學習如何針對狀態使用 IoT Edge 代理程序屬性。
下表不包含從所需屬性複製的資訊。
| 屬性 | 描述 |
|---|---|
| lastDesiredStatus.code | IoT Edge 代理程式所見之最後所需屬性的狀態代碼。 允許的值：200 Success、400 Invalid configuration、412 Invalid schema version、417 Desired properties are empty、500 Failed。 |
| lastDesiredStatus.description | 狀態的文字說明。 |
| lastDesiredVersion | 此整數是指 IoT Edge 代理程式所處理之預期屬性的最新版本。 |
| runtime.platform.OS | 報告在裝置上執行的OS。 |
| runtime.platform.architecture | 報告裝置上的 CPU 架構。 |
| schemaVersion | 報告屬性的結構描述版本。 |
| systemModules.edgeAgent.runtimeStatus | IoT Edge 代理程式報告的狀態：{running | unhealthy}。 |
| systemModules.edgeAgent.statusDescription | IoT Edge 代理程式回報狀態的文字描述。 |
| systemModules.edgeAgent.exitCode | 容器結束時 IoT Edge 代理程式容器報告的結束代碼。 |
| systemModules.edgeAgent.lastStartTimeUtc | IoT Edge 代理程式上次啟動的時間。 |
| systemModules.edgeAgent.lastExitTimeUtc | IoT Edge 代理程式上次結束的時間。 |
| systemModules.edgeHub.runtimeStatus | IoT Edge 中樞狀態：{ running | stopped | failed | backoff | unhealthy }。 |
| systemModules.edgeHub.statusDescription | 在狀況不良的情況下，IoT Edge 中樞狀態的文字描述。 |
| systemModules.edgeHub.exitCode | 容器結束時 IoT Edge 中樞容器報告的結束代碼。 |
| systemModules.edgeHub.lastStartTimeUtc | IoT Edge 中樞上次啟動的時間。 |
| systemModules.edgeHub.lastExitTimeUtc | IoT Edge 中樞上次結束的時間。 |
| systemModules.edgeHub.lastRestartTimeUtc | IoT Edge 中樞上次重新啟動的時間。 |
| systemModules.edgeHub.restartCount | 作為重新啟動原則的一部分，重新啟動此模組的次數。 |
| modules.{moduleId}.runtimeStatus | 模組的狀態：{ running | stopped | failed | backoff | unhealthy }。 |
| modules.{moduleId}.statusDescription | 在狀況不良的情況下，模組狀態的文字描述。 |
| modules.{moduleId}.exitCode | 容器結束時模組容器報告的結束代碼。 |
| modules.{moduleId}.lastStartTimeUtc | 模組上次啟動的時間。 |
| modules.{moduleId}.lastExitTimeUtc | 模組上次結束的時間。 |
| 模組 {moduleId} 最後重啟時間 (UTC) | 模組上次重新啟動的時間。 |
| modules.{moduleId}.restartCount | 作為重新啟動原則的一部分，重新啟動此模組的次數。 |
| 版本 | 映像的版本。 範例："version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }。 |
EdgeHub 預期屬性
IoT Edge 中樞的模組對應項稱為 $edgeHub，且可協調在裝置上執行的 IoT Edge 中樞和 IoT 中樞之間的通訊。 在特定裝置上套用部署資訊清單以成為單一裝置或大規模部署的一部分時，即會設定預期屬性。
| 屬性 | 描述 | 部署資訊清單中的必要項 |
|---|---|---|
| schemaVersion | 1.0 或 1.1。 1.1 版隨 IoT Edge 1.0.10 版推出，建議使用。 | 是的 |
| 路線。{routeName} | 代表 IoT Edge 中樞路由的字串。 如需詳細資訊，請參閱宣告路由。 |
routes 元素可以存在但為空白。 |
| storeAndForwardConfiguration.timeToLiveSecs | IoT Edge 中樞在與路由端點 (IoT 中樞或本機模組) 中斷連線時保留訊息的裝置時間 (以秒為單位)。 在任何電源關閉或重新啟動後，此時間仍會持續一段時間。 如需詳細資訊，請參閱離線功能。 | 是的 |
EdgeHub 回報的屬性
| 屬性 | 描述 |
|---|---|
| lastDesiredVersion | 此整數是指 IoT Edge 中樞所處理之預期屬性的最新版本。 |
| lastDesiredStatus.code | 此狀態代碼代表 IoT Edge 中樞上次看到的所需屬性。 允許的值：200 Success、400 Invalid configuration、500 Failed。 |
| lastDesiredStatus.description | 狀態的文字說明。 |
| 用戶端 | 所有連線到 edgeHub 的用戶端，包含狀態和上次連線時間。 範例："clients": { "device2/SimulatedTemperatureSensor": { "status": "Connected", "lastConnectedTimeUtc": "2022-11-17T21:49:16.4781564Z" } }。 |
| clients.{device or moduleId}.status | 此裝置或模組的連線狀態。 可能的值 {connected | disconnected}。 只有模組身分識別可以處於中斷連線的狀態。 連線到 IoT Edge 中樞的下游裝置只有在連線時才會出現。 |
| clients.{device or moduleId}.lastConnectTime | 上次裝置或模組連線時。 |
| 客戶.{裝置或模組Id}.最後斷線時間 | 上次裝置或模組中斷連線時。 |
| schemaVersion | 報告屬性的結構描述版本。 |
| 版本 | 映像的版本。 範例："version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }。 |
後續步驟
若要了解如何使用這些屬性建置部署資訊清單，請參閱了解如何使用、設定以及重複使用 IoT Edge 模組。