適用於：
IoT Edge 1.6
重要事項
IoT Edge 1.6 LTS 是支援的版本。 IoT Edge 1.5 LTS 支援將於 2026 年 11 月 10 日結束;IoT Edge 1.4 LTS 於 2024 年 11 月 12 日終止生命週期。 如果你使用的是較早版本，請參考 Update IoT Edge。
IoT Edge 代理與 IoT Edge 集線器是組成 IoT Edge 執行環境的兩個模組。 欲了解更多關於每個執行時模組的職責，請參閱 理解 Azure IoT Edge 執行時及其架構。
本文提供執行階段模組對應項的所需屬性和報告屬性。 欲了解更多如何在IoT Edge裝置上部署模組的資訊，請參見 learn 如何在 IoT Edge 中部署模組並建立路由。
模組對應項包含：
預期屬性。 解決方案後端會設定所需的屬性，而模組會讀取它們。 模組也會接收所需屬性中變更的通知。 利用期望屬性與回報屬性來同步模組配置或條件。
回報的屬性。 模組會設定報告的屬性，而解決方案後端會讀取和查詢它們。 利用報告的屬性與期望屬性來同步模組配置或條件。
EdgeAgent 預期屬性
IoT Edge代理的模組雙胞胎稱為$edgeAgent。 它協調運行在裝置上的 IoT Edge 代理與 IoT 中樞 之間的通訊。 當您在單一裝置或大規模部署中套用部署清單時，請設定所需的屬性。
| 屬性 | 描述 | 必要 |
|---|---|---|
imagePullPolicy |
指定何時提取映像： OnCreate 或 Never。 如果映射已經在裝置上，請使用 Never 。 | 是的 |
restartPolicy |
什麼時候該重新啟動模組。 可能的值包括：永不：若模組未運行則勿重啟；失敗後：模組以非零退出代碼退出時重啟；不健康時：若模組不健康（見註解）則重啟模組；始終：不論何時只要未運行便重啟模組。
註：on-failure該策略會重啟那些退出代碼非零的模組。
on-unhealthy該政策被結構接受，但執行時目前並未從 Docker 健康檢查中推導出不健康狀態，因此沒有實際效果。 詳情請參見IoT Edge限制與限制。 |
是的 |
runtime.type |
必須是 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。 建議使用 1.1 版本，隨 IoT Edge 1.0.10 版本引入。 | 是的 |
status |
模組的所需狀態：Running 或 Stopped。 | 必要 |
systemModules.edgeAgent.type |
必須是 docker。 | 是的 |
systemModules.edgeAgent.startupOrder |
指定以啟動順序表示模組位置的整數。 0 是第一個， 而最大整數 （4294967295） 是最後一個。 如果你沒有提供值，預設是 最大整數。 | 否 |
systemModules.edgeAgent.settings.image |
指定 IoT Edge 代理映像的 URI。 IoT Edge 代理程式無法自我更新。 | 是的 |
systemModules.edgeAgent.settings.createOptions |
指定一個串聯的 JSON 格式，並有建立 IoT Edge 代理容器的選項。 深入瞭解 Docker 建立選項。 | 否 |
systemModules.edgeAgent.configuration.id |
部署此模組的部署識別碼。 | IoT 中樞 在透過部署作業套用配置文件時會設定此屬性。 並非部署資訊清單的一部分。 |
systemModules.edgeHub.type |
必須是 docker。 | 是的 |
systemModules.edgeHub.status |
必須是執行中。 | 是的 |
systemModules.edgeHub.restartPolicy |
必須 永遠如此。 | 是的 |
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 |
建立時 | 永不 | 否 |
modules.{moduleId}.env |
要傳遞至模組的環境變數清單。 採用格式："<name>": {"value": "<value>"}。 |
否 |
modules.{moduleId}.settings.image |
模組映像的 URI。 | 是的 |
modules.{moduleId}.settings.createOptions |
包含適用於建立模組容器之選項的字串化 JSON。 Docker 建立選項 | 否 |
modules.{moduleId}.configuration.id |
部署此模組的部署識別碼。 | IoT 中樞 在透過部署作業套用配置文件時會設定此屬性。 並非部署資訊清單的一部分。 |
version |
目前具有版本、認可和建置的的反覆運算。 | 否 |
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代理的報告狀態：{ 運行中 | 異常 }。 |
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 hub 狀態：{ 運行中 | 已停止 | 故障 | 退避 | 不健康 }。 |
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 版本推出，建議使用。 | 是的 |
routes.{routeName} |
一個代表 IoT Edge 集線路由的字串。 如需詳細資訊，請參閱宣告路由。 |
routes 元素可以存在但為空白。 |
storeAndForwardConfiguration.timeToLiveSecs |
IoT Edge 中樞在與路由端點 (IoT 中樞或本機模組) 中斷連線時保留訊息的裝置時間 (以秒為單位)。 在任何電源關閉或重新啟動後，此時間仍會持續一段時間。 如需詳細資訊，請參閱離線功能。 | 是的 |
EdgeHub 環境變數
你可以在部署資訊清單中，於 $edgeHub 模組上設定環境變數，來調整某些 IoT Edge hub 行為。 以下變數控制 IoT Edge 樞紐如何更新其裝置範圍快取，並用以在本地驗證下游裝置與模組。
| 環境變數 | 描述 |
|---|---|
DeviceScopeCacheRefreshRateSecs |
IoT Edge 中樞每隔多少秒會透過從 IoT 中樞列舉其範圍內的裝置和模組，來重新整理其快取。 預設值是 3600 （一小時）。 在擁有多台 IoT Edge 裝置的樞紐中，所有裝置的範圍刷新操作合併後，能顯著提升該樞紐的身份操作使用率。 增加這個數值會成比例地減少負載。 如需詳細資訊，請參閱大型機群上的 IoT 中樞身分識別作業配額已超出。 |
DeviceScopeCacheRefreshDelaySecs |
IoT Edge 中樞在依需求再次重新整理單一身分識別之前所等待的最短時間（以秒為單位）。 預設值為 120。 此設定限制了用戶端連線時同一身份快速更新的頻率。 |
EdgeHub 回報的屬性
| 屬性 | 描述 |
|---|---|
lastDesiredVersion |
此整數指的是 IoT Edge 集線器處理的所需屬性的最近版本。 |
lastDesiredStatus.code |
狀態碼指的是 IoT Edge 集線器所看到的最後期望屬性。 允許的值： 200 成功、 400 設定無效、 500 失敗。 |
lastDesiredStatus.description |
狀態的文字說明。 |
clients |
所有連線到 edgeHub 的用戶端，包含狀態和上次連線時間。 範例："clients": { "device2/SimulatedTemperatureSensor": { "status": "Connected", "lastConnectedTimeUtc": "2022-11-17T21:49:16.4781564Z" } }。 關於此性質中出現哪些連接的詳細資訊，請參見 哪些連接出現於 clients。 |
clients.{device or moduleId}.status |
此裝置或模組的連線狀態。 可能的數值： 連接 或 斷開。 只有模組身分識別可以處於中斷連線的狀態。 連接 IoT Edge 集線器的下游裝置僅在連接時顯示。 |
clients.{device or moduleId}.lastConnectTime |
上次裝置或模組連線時。 |
clients.{device or moduleId}.lastDisconnectTime |
上次裝置或模組中斷連線時。 |
schemaVersion |
報告屬性的結構描述版本。 |
version |
映像的版本。 例如： "version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" } 。 |
clients 中會出現哪些連線
clients 報告屬性會列出本機 edgeHub 所服務的每個個別邏輯連線，但不包括其自己的 $edgeHub 身分識別。 具體來說：
-
同一邊緣裝置上的模組 會顯示為
<deviceId>/<moduleName>。 這包括$edgeAgent，因為本地 edgeAgent 是透過本地 edgeHub 連接的。 -
下游IoT Edge子裝置顯示為
<childDeviceId>/$edgeHub和<childDeviceId>/$edgeAgent。 沒有裸露的<childDeviceId>項目。 子裝置的$edgeHub連線，就是 閘道階層中已連線的用戶端數量 所指的「裝置自身的連線」。 -
下游葉片裝置（非IoT Edge裝置）顯示為
<deviceId>，且無模組後綴。 - 本地 edgeHub 自身的身份
<deviceId>/$edgeHub（）被刻意省略，以避免自我參照。
當模組中斷連線時，其項目仍會保留在 clients 中，狀態為 Disconnected。 當下游裝置中斷連線時，其項目會從 clients 中移除。 可見項目的數量等於針對 MaxConnectedClients 編列的預算數量。 沒有隱藏的額外連結。
後續步驟
關於如何利用這些屬性來建立部署清單的資訊，請參見 了解IoT Edge模組如何被使用、配置與重複使用。