了解和使用 IoT 中樞的模組對應項
本文假設您已先讀過了解和使用 Azure IoT 中樞的裝置對應項。 在 IoT 中樞的每個裝置身分識別下，您可以建立最多 50 個模組身分識別。 每個模組身分識別都會隱含地產生模組對應項。 類似於裝置對應項，模組對應項是儲存模組狀態資訊的 JSON 文件，包括中繼資料、設定和條件。 Azure IoT 中樞會針對連線到 IoT 中樞的每個模組維護模組對應項。
在裝置端，IoT 中樞裝置 SDK 可讓您建立模組，其中每個模組都會開啟與 IoT 中樞的獨立連線。 這項功能可讓您針對裝置上的不同元件使用不同的命名空間。 例如，您有一台具有三個不同感應器的自動販賣機。 每個感應器都是由貴公司的不同部門所控制。 您可以為每個感應器建立模組。 如此一來，每個部門只能將作業或直接方法傳送至其所控制的感應器，以避免衝突和使用者錯誤。
模組身分識別和模組對應項提供與裝置身分識別和裝置對應項相同的功能，但資料細微性更為精細。 此更精細的細微性可讓支援裝置，例如作業系統型裝置或管理多個元件的韌體裝置，隔離每個元件的設定和條件。 模組身分識別和模組對應項可在使用具有模組化軟體元件的 IoT 裝置時，提供關注的管理區隔。 我們的目標是透過模組對應項的正式運作，在模組對應項層級上支援所有裝置對應項功能。
注意
本文中所述的功能僅適用於 IoT 中樞的標準層。 如需有關基本和標準/免費 Azure IoT 中樞階層的詳細資訊，請參閱為您的解決方案選擇適合的 Azure 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
}
}
}
根物件中包含的是模組身分識別屬性，以及 tags 和 reported 與 desired 屬性的容器物件。 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 中樞查詢語言來查詢模組對應項。
模組作業
模組應用程式會使用下列不可部分完成的作業來操作模組對應項︰
擷取模組對應項。 此作業會針對目前連線的模組傳回模組對應項文件 (包括所需及報告系統屬性)。
部分更新的報告屬性。 此作業可針對目前所連線模組的報告屬性進行局部更新。 此作業會使用方案後端針對所需屬性部分更新所使用的相同 JSON 更新格式。
觀察所需屬性。 目前連線的模組可以選擇在所需屬性進行更新時收到通知。 模組會收到由解決方案後端執行的相同更新形式 (部分或完整取代)。
如控制 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。
對應項大小的計算方式如下：
針對 JSON 文件中的每一個屬性，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 中樞」教學課程：