IoT Edge 代理程式和 IoT Edge 中樞模組對應項的屬性
適用於： 
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。
IoT Edge 代理程式和 IoT Edge 中樞是構成 IoT Edge 執行階段的兩個模組。 如需各執行階段模組相關責任的詳細資訊，請參閱了解 Azure IoT Edge 執行階段及其架構。
本文提供執行階段模組對應項的所需屬性和報告屬性。 如需如何在 IoT Edge 裝置上部署模組的詳細資訊，請參閱了解如何在 IoT Edge 中部署模組和建立路由。
模組對應項包括：
預期屬性。 解決方案後端可以設定所需屬性，模組可加以讀取。 模組也可以收到所需屬性變更的通知。 預期屬性會搭配回報的屬性使用，以便同步處理模組的設定或條件。
回報的屬性。 模組可以設定報告的屬性，解決方案後端可加以讀取並查詢。 報告的屬性會搭配所需屬性使用，以同步模組設定或條件。
EdgeAgent 預期屬性
IoT Edge 代理程式的模組對應項稱為 $edgeAgent，且可協調在裝置上執行的 IoT Edge 代理程式和 IoT 中樞之間的通訊。 在特定裝置上套用部署資訊清單以成為單一裝置或大規模部署的一部分時，即會設定預期屬性。
| 屬性 | 描述 | 必要 |
|---|---|---|
| imagePullPolicy | 在 OnCreate 或 Never 中提取映像時 (如果映像已在裝置上，則可使用 Never) | Yes |
| restartPolicy | 應該重新啟動模組時。 可能的值為：Never：若未執行，不要重新啟動模組、Always：若未執行，一律重新啟動模組、On-Unhealthy：如果狀況不良則重新啟動模組。 狀況不良是 Docker 根據健康情況檢查所報告的內容，例如「狀況不良 - 容器無法正常運作」、On-Failed：如果失敗，則重新啟動。 | Yes |
| runtime.type | 必須為 docker。 | Yes |
| runtime.settings.minDockerVersion | 設定為此部署資訊清單所需的最小 Docker 版本。 | Yes |
| runtime.settings.loggingOptions | 包含適用於 IoT Edge 代理程式容器之記錄選項的字串化 JSON。 Docker 記錄選項 | No |
| runtime.settings.registryCredentials.{registryId}.username | 容器登錄的使用者名稱。 針對 Azure Container Registry，使用者名稱通常是登錄名稱。 任何私人模組映像都需要登錄認證。 | No |
| runtime.settings.registryCredentials.{registryId}.password | 容器登錄的密碼。 | No |
| runtime.settings.registryCredentials.{registryId}.address | 容器登錄的位址。 Azure Container Registry 的位址通常是 {登錄名稱}.azurecr.io。 | No |
| schemaVersion | 可以是 1.0 或 1.1。 1.1 版隨 IoT Edge 1.0.10 版推出，建議使用。 | Yes |
| status | 模組的所需狀態：執行中或已停止。 | 必要 |
| systemModules.edgeAgent.type | 必須為 docker。 | Yes |
| systemModules.edgeAgent.startupOrder | 模組在啟動順序中所居位置的整數值。 「0」 是第一個，「最大整數」(4294967295) 是最後一個。 如果未提供值，則預設值為「最大整數」。 | No |
| systemModules.edgeAgent.settings.image | IoT Edge 代理程式映像的 URI。 目前，IoT Edge 代理程式無法自行更新。 | Yes |
| systemModules.edgeAgent.settings.createOptions | 包含適用於建立 IoT Edge 代理程式容器之選項的字串化 JSON。 Docker 建立選項 | No |
| systemModules.edgeAgent.configuration.id | 部署此模組的部署識別碼。 | IoT 中樞會在使用部署套用資訊清單時設定此屬性。 並非部署資訊清單的一部分。 |
| systemModules.edgeHub.type | 必須為 docker。 | Yes |
| systemModules.edgeHub.status | 必須為 running。 | Yes |
| systemModules.edgeHub.restartPolicy | 必須為 always。 | Yes |
| systemModules.edgeHub.startupOrder | 整數值，會在啟動順序中找出模組。 「0」 是第一個，「最大整數」(4294967295) 是最後一個。 如果未提供值，則預設值為「最大整數」。 | No |
| systemModules.edgeHub.settings.image | IoT Edge 中樞映像的 URI。 | Yes |
| systemModules.edgeHub.settings.createOptions | 包含適用於建立 IoT Edge 中樞容器之選項的字串化 JSON。 Docker 建立選項 | No |
| systemModules.edgeHub.configuration.id | 部署此模組的部署識別碼。 | IoT 中樞會在使用部署套用資訊清單時設定此屬性。 並非部署資訊清單的一部分。 |
| modules.{moduleId}.version | 代表此模組版本的使用者定義字串。 | Yes |
| modules.{moduleId}.type | 必須為 docker。 | Yes |
| modules.{moduleId}.status | {running | stopped} | Yes |
| modules.{moduleId}.restartPolicy | {never | always} | Yes |
| modules.{moduleId}.startupOrder | 模組在啟動順序中所居位置的整數值。 「0」 是第一個，「最大整數」(4294967295) 是最後一個。 如果未提供值，則預設值為「最大整數」。 | No |
| modules.{moduleId}.imagePullPolicy | {on-create | never} | No |
| modules.{moduleId}.env | 要傳遞至模組的環境變數清單。 採用格式 "<name>": {"value": "<value>"}。 |
No |
| modules.{moduleId}.settings.image | 模組映像的 URI。 | Yes |
| modules.{moduleId}.settings.createOptions | 包含適用於建立模組容器之選項的字串化 JSON。 Docker 建立選項 | No |
| modules.{moduleId}.configuration.id | 部署此模組的部署識別碼。 | IoT 中樞會在使用部署套用資訊清單時設定此屬性。 並非部署資訊清單的一部分。 |
| version | 目前具有版本、認可和組建的反覆項目。 | No |
EdgeAgent 回報的屬性
IoT Edge 代理程式回報的屬性包括資訊的三個主要部分：
- 最後看到之預期屬性的應用程式狀態；
- 目前在裝置上執行的模組狀態，如同 IoT Edge 代理程式所回報；以及
- 目前在裝置上執行之預期屬性的複本。
目前所需屬性的複本，在判斷裝置是否已套用最新部署，或是否仍在執行舊版部署資訊清單時，非常實用。
注意
可以使用 IoT 中樞查詢語言查詢，以調查大規模部署的狀態時，IoT Edge 代理程式的報告屬性相當有用。 如需如何將 IoT Edge 代理程式屬性用於狀態的詳細資訊，請參閱了解單一裝置或大規模的 IoT Edge 部署。
下表不包括從預期屬性複製的資訊。
| 屬性 | 說明 |
|---|---|
| lastDesiredStatus.code | 此狀態代碼代表 IoT Edge 代理程式上次看到的所需屬性。 允許的值：200 成功、400 無效的設定、412 無效的結構描述版本、417 預期屬性是空的、500 失敗。 |
| lastDesiredStatus.description | 狀態的文字說明。 |
| lastDesiredVersion | 此整數是指 IoT Edge 代理程式所處理之預期屬性的最新版本。 |
| runtime.platform.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 | 模組的上次結束時間。 |
| modules.{moduleId}.lastRestartTimeUtc | 模組上次重新啟動的時間。 |
| modules.{moduleId}.restartCount | 作為重新啟動原則的一部分，重新啟動此模組的次數。 |
| version | 映像的版本。 範例："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 版推出，建議使用。 | Yes |
| routes.{routeName} | 代表 IoT Edge 中樞路由的字串。 如需詳細資訊，請參閱宣告路由。 | routes 元素可以存在但為空白。 |
| storeAndForwardConfiguration.timeToLiveSecs | IoT Edge 中樞在與路由端點 (IoT 中樞或本機模組) 中斷連線時保留訊息的裝置時間 (以秒為單位)。 在任何電源關閉或重新啟動後，此時間仍會持續。 如需詳細資訊，請參閱離線功能。 | Yes |
EdgeHub 回報的屬性
| 屬性 | 說明 |
|---|---|
| lastDesiredVersion | 此整數是指 IoT Edge 中樞所處理之預期屬性的最新版本。 |
| lastDesiredStatus.code | 此狀態代碼代表 IoT Edge 中樞上次看到的所需屬性。 允許的值：200 成功、400 無效的設定、500 失敗 |
| 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 | 上次裝置或模組連線時。 |
| clients.{device or moduleId}.lastDisconnectTime | 上次裝置或模組中斷連線時。 |
| schemaVersion | 報告屬性的結構描述版本。 |
| version | 映像的版本。 範例："version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }。 |
下一步
若要了解如何使用這些屬性建置部署資訊清單，請參閱了解如何使用、設定以及重複使用 IoT Edge 模組。