了解和使用 IoT 中樞的模組對應項

發行項
12/20/2024

在 IoT 中樞的每個裝置身分識別下，您可以建立最多 50 個模組身分識別。每個模組身分識別都會隱含地產生模組對應項。類似於裝置對應項，模組對應項是儲存模組狀態資訊的 JSON 文件，包括中繼資料、設定和條件。 Azure IoT 中樞會針對連線到 IoT 中樞的每個模組維護模組對應項。

本文假設您先閱讀瞭解並使用裝置對應項，IoT 中樞。

在裝置端，IoT 中樞裝置軟體開發工具包（SDK）可讓您建立模組，其中每個模組都會開啟與 IoT 中樞的獨立連線。這項功能可讓您針對裝置上的不同元件使用不同的命名空間。例如，您有一台具有三個不同感應器的自動販賣機。公司的不同部門會控制每個感測器。您可以為每個感測器建立模組，讓部門只能將工作或直接方法傳送至其控制的感測器，以避免衝突和用戶錯誤。

模組身分識別和模組對應項提供與裝置身分識別和裝置對應項相同的功能，但資料細微性更為精細。此更精細的細微性可讓支援裝置，例如作業系統型裝置或管理多個元件的韌體裝置，隔離每個元件的設定和條件。模組身分識別和模組對應項可在使用具有模組化軟體元件的 IoT 裝置時，提供關注的管理區隔。我們的目標是透過模組對應項的正式運作，在模組對應項層級上支援所有裝置對應項功能。

注意

本文中所述的功能僅適用於 IoT 中樞的標準層。如需有關基本和標準/免費 Azure IoT 中樞階層的詳細資訊，請參閱為您的解決方案選擇適合的 IoT 中樞階層。

本文章說明：

模組對應項的結構：標籤、所需屬性和報告屬性。
裝置應用程式和解決方案後端可以在模組對應項上執行的作業。

請參閱裝置到雲端通訊指引，以取得有關使用報告屬性、裝置到雲端訊息或檔案上傳的指引。

請參閱雲端對裝置通訊指引，以取得有關使用所需屬性、直接方法或雲端到裝置訊息的指引。

模組對應項

模組對應項會儲存模組相關資訊，以供︰

裝置與 IoT 中樞上的模組用來同步處理模組的狀況和設定。
解決方案後端用來查詢和鎖定長時間執行的作業。

模組對應項的生命週期會連結至對應的模組身分識別。在 IoT 中樞建立或刪除模組身分識別時，系統會隱含地建立和刪除模組對應項。

模組對應項是 JSON 文件，其中含有︰

標籤。後端應用程式可從中讀取和寫入的 JSON 檔區段。裝置上的模組看不到標記。標籤是基於查詢用途所設定。
預期屬性。搭配報告屬性使用，以便同步處理模組的設定或條件。後端應用程式可以設定所需的屬性，而模組應用程式可以讀取它們。模組應用程式也可以接收所需屬性中的變更通知。
回報的屬性。搭配所需屬性使用，以便同步處理模組的設定或條件。模組應用程式可以設定報告的屬性，而後端應用程式可以讀取和查詢它們。
模組身分識別屬性。模組對應項 JSON 文件的根目錄包含來自對應模組身分識別的唯讀屬性，此身分識別儲存在身分識別登錄中。

裝置對應項的架構表示法

以下範例顯示模組對應項 JSON 文件︰

{
    "deviceId": "devA",
    "moduleId": "moduleA",
    "etag": "AAAAAAAAAAc=", 
    "status": "enabled",
    "statusReason": "provisioned",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "connected",
    "lastActivityTime": "2015-02-30T16:24:48.789Z",
    "cloudToDeviceMessageCount": 0, 
    "authenticationType": "sas",
    "x509Thumbprint": {     
        "primaryThumbprint": null, 
        "secondaryThumbprint": null 
    }, 
    "version": 2, 
    "tags": {
        "deploymentLocation": {
            "building": "43",
            "floor": "1"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "sendFrequency": "5m"
            },
            "$metadata" : {...},
            "$version": 1
        },
        "reported": {
            "telemetryConfig": {
                "sendFrequency": "5m",
                "status": "success"
            },
            "batteryLevel": 55,
            "$metadata" : {...},
            "$version": 4
        }
    }
}

在最上層，模組對應項物件包含和 reported desired 屬性的tags模組識別屬性和容器物件。 properties 容器包含一些唯讀元素 ($metadata 和 $version)，如模組對應項中繼資料和開放式同步存取章節中所述。

報告屬性範例

在上一個範例中，模組對應項包含報告 batteryLevel 屬性。此屬性可讓您根據最後一次報告的電池電量對模組進行查詢和操作。其他範例包含模組應用程式報告模組功能或連線能力選項。

注意

報告屬性可簡化您對於屬性最後已知值的案例。如果您想要以時間戳事件序列來處理模組遙測，例如時間序列，請使用裝置到雲端訊息。

所需屬性範例

在上一個範例中， telemetryConfig 後端應用程式和模塊應用程式會使用模組對應項所需和報告屬性來同步處理此課程模組的遙測組態。例如：

後端應用程式會使用所需的組態值來設定所需的屬性。以下是含有所需屬性集的文件部分：
```
...
"desired": {
    "telemetryConfig": {
        "sendFrequency": "5m"
    },
    ...
},
...
```
模組一旦連線，模組應用程式便會立即收到變更通知。若未連線，則模組應用程式會在連線後按照模組重新連線流程運作。模組應用程式接著會報告更新的設定 (或使用 status 屬性報告錯誤狀況)。以下是報告屬性的部分：
```
"reported": {
    "telemetryConfig": {
        "sendFrequency": "5m",
        "status": "success"
    }
    ...
}
```
後端應用程式可以藉由查詢模組對應項來追蹤許多模組的組態作業結果。

注意

上述程式碼片段舉例說明用來編碼模組設定和其狀態的方式，並針對方便閱讀而進行最佳化。 IoT 中樞不會對模組對應項中的模組對應項所需屬性和報告屬性強制實行特定結構描述。

重要

IoT 隨插即用會定義結構描述，該結構描述會使用數個額外的屬性來同步處理所需和報告屬性的變更。如果您的解決方案使用 IoT 隨插即用，您必須在更新對應項屬性時遵循隨插即用慣例。如需詳細資訊和範例，請參閱 IoT 隨插即用中的可寫入屬性。

後端作業

後端應用程式會使用下列不可部分完成的作業在模組對應項上運作，並透過 HTTPS 公開：

依識別碼擷取模組對應項。此作業會傳回模組對應項文件，包括標籤，以及所需及報告的系統屬性。
局部更新模組對應項。這項作業會部分更新模組對應項中的標記或所需屬性。部分更新會以新增或更新任何屬性的 JSON 文件表示。設定為 null 的屬性會移除。下列範例會使用值 {"newProperty": "newValue"} 建立新的所需屬性，以 "otherNewValue" 覆寫 existingProperty 的現有值，並移除 otherOldProperty。現有的所需屬性或標籤不會進行任何其他變更：
```
{
    "properties": {
        "desired": {
            "newProperty": {
                "nestedProperty": "newValue"
            },
            "existingProperty": "otherNewValue",
            "otherOldProperty": null
        }
    }
}
```
取代所需屬性。此工作會完全覆寫所有現有的所需屬性，並將新的 JSON 檔取代為 properties/desired。
取代標籤。這項工作會完全覆寫所有現有的標記，並將新的 JSON 檔取代為 tags。
接收對應項通知。這項作業會在修改對應項時通知。若要接收模組對應項變更通知，您的IoT解決方案必須建立路由，並將數據源設定為 等於 twinChangeEvents。根據預設，不存在此類路由，因此不會傳送任何對應項通知。如果變動率過高，或基於內部失敗等其他原因，IoT 中樞可能會只傳送一個包含所有變更的通知。因此，如果您的應用程式需要所有中繼狀態的可靠稽核和記錄，您應該使用裝置到雲端的訊息。若要深入了解對應項通知訊息中傳回的屬性與本文，請參閱非遙測事件結構描述。

上述所有作業皆支援開放式並行存取，而且需要 ServiceConnect 權限，如控制 IoT 中樞的存取權一文中所定義。

除了這些作業之外，後端應用程式還可以使用類似 SQL 的 IoT 中樞查詢語言來查詢模組對應項。

模組作業

模組應用程式會使用下列不可部分完成的作業來操作模組對應項︰

擷取模組對應項。此作業會針對目前連線的模組傳回模組對應項文件 (包括所需及報告系統屬性)。
部分更新的報告屬性。此作業可針對目前所連線模組的報告屬性進行局部更新。
觀察所需屬性。目前連線的模組可以選擇在所需屬性進行更新時收到通知。

如控制 IoT 中樞的存取權一文所述，以上所有作業都需要 DeviceConnect 權限。

Azure IoT 裝置 SDK 可讓您透過許多語言和平台輕鬆使用上述作業。

標籤和屬性格式

標籤、所需屬性和報告屬性是具有下列限制的 JSON 物件：

索引鍵：JSON 物件中所有索引鍵都採 UTF-8 編碼，須區分大小寫，長度上限為 1 KB。允許的字元會排除 UNICODE 控制字元 (區段 C0 和 C1)，以及 .、$ 和 SP。
值：JSON 物件中的所有值都可能屬於下列 JSON 類型︰布林值、數字、字串、物件。也支援陣列。
- 整數值最小可為 -4503599627370496，最大可為 4503599627370495。
- 字串值會以 UTF-8 編碼，而且長度上限為 4 KB。

深度：標籤、所需屬性和報告屬性中 JSON 物件的最大深度為 10。例如，下列物件有效：

{
     ...
     "tags": {
         "one": {
             "two": {
                 "three": {
                     "four": {
                         "five": {
                             "six": {
                                 "seven": {
                                     "eight": {
                                         "nine": {
                                             "ten": {
                                                 "property": "value"
                                             }
                                         }
                                     }
                                 }
                             }
                         }
                     }
                 }
             }
         }
     },
     ...
}

模組對應項大小

IoT 中樞會針對 tags 的值強制執行 8 KB 大小限制，並針對 properties/desired 和 properties/reported 的值強制執行 32 KB 大小限制。這些總計是唯讀元素專屬，例如 $version 和 $metadata/$lastUpdated。

對應項大小的計算方式如下：

IoT 中樞累計計算，並新增每個屬性的索引鍵和值長度。
屬性索引鍵會視為 UTF8 編碼字串。
簡單屬性值會視為 UTF8 編碼字串、數值 (8 個位元組)，或布林值 (4 個位元組)。
UTF8 編碼字串大小的計算方式是計算所有字元的數量，排除 UNICODE 控制字元 (區段 C0 和 C1)。
複雜屬性值 (巢狀物件) 是根據其包含的屬性索引鍵和屬性值的彙總大小來計算。

IoT 中樞會拒絕 (並出現錯誤) 將會讓這些文件的大小增加到超過限制的所有作業。

模組對應項中繼資料

IoT 中樞會為模組對應項所需屬性和報告屬性中的每個 JSON 物件保有上次更新的時間戳記。時間戳記採用 UTC 格式，並以 ISO8601 格式 YYYY-MM-DDTHH:MM:SS.mmmZ 進行編碼。例如：

{
    ...
    "properties": {
        "desired": {
            "telemetryConfig": {
                "sendFrequency": "5m"
            },
            "$metadata": {
                "telemetryConfig": {
                    "sendFrequency": {
                        "$lastUpdated": "2016-03-30T16:24:48.789Z"
                    },
                    "$lastUpdated": "2016-03-30T16:24:48.789Z"
                },
                "$lastUpdated": "2016-03-30T16:24:48.789Z"
            },
            "$version": 23
        },
        "reported": {
            "telemetryConfig": {
                "sendFrequency": "5m",
                "status": "success"
            },
            "batteryLevel": "55%",
            "$metadata": {
                "telemetryConfig": {
                    "sendFrequency": "5m",
                    "status": {
                        "$lastUpdated": "2016-03-31T16:35:48.789Z"
                    },
                    "$lastUpdated": "2016-03-31T16:35:48.789Z"
                },
                "batteryLevel": {
                    "$lastUpdated": "2016-04-01T16:35:48.789Z"
                },
                "$lastUpdated": "2016-04-01T16:24:48.789Z"
            },
            "$version": 123
        }
    }
    ...
}

這項資訊會保留在每個層級 (不只是 JSON 結構的分葉)，以保留移除物件索引鍵的更新。

開放式並行存取

標籤、所需屬性和報告屬性全都支援開放式同步存取。如果您需要保證對應項屬性更新的順序，請考慮在傳送下一個更新之前等待報告的屬性回撥，以便在應用程式層級實作同步處理。

模組對應項具有 ETag (etag 屬性)，根據 RFC7232，其代表對應項的 JSON 表示法。您可以從後端應用程式使用 etag 條件式更新作業中的屬性，以確保一致性。此選項可確保涉及 tags 容器之作業中的一致性。

模組對應項所需屬性和報告屬性也有保證增量的 $version 值。與ETag類似，您可以使用版本值來強制執行更新的一致性。例如，報告屬性的模組應用程式或所需屬性的後端應用程式。

當觀察端代理程式 (例如，觀察所需屬性的模組應用程式) 必須協調擷取作業結果與更新通知之間的競爭情況時，版本也相當有用。更多資訊詳見模組重新連線流程一節。

模組重新連線流程

IoT 中樞不會保留已中斷連線模組的所需屬性更新通知。因此，連線的模組必須擷取完整的所需屬性文件，並訂閱更新通知。鑑於更新通知與完整擷取之間爭用的可能性，必須確保下列流程：

模組應用程式連線到 IoT 中樞。
模組應用程式訂閱所需屬性更新通知。
模組應用程式擷取所需屬性的完整文件。

模組應用程式可以忽略 $version 小於或等於完整擷取文件版本的所有通知。這種方法是可能的，因為 IoT 中樞保證版本一律會遞增。

下一步

若要嘗試本文所述的一些概念，請參閱下列「IoT 中樞」教學課程：

透過 .NET 後端和 .NET 裝置開始使用 IoT 中樞模組身分識別和模組對應項

共用方式為