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

發行項
02/06/2024

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

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

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

注意

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

本文章說明：

模組對應項的結構：標籤、所需屬性和 報告屬性。
模組和後端可以在模組對應項上執行的作業。

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

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

模組對應項

模組對應項會儲存下列模組相關信息：

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

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

模組對應項是 JSON 檔，其中包含：

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

Architectural representation of device twin

下列範例顯示模組對應項 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
        }
    }
}

根物件中是模組身分識別屬性，以及和 reporteddesired 和屬性的tags容器物件。容器properties包含模組對應項元數據和開放式並行存取區段中所述的一些唯讀元素（$metadata和 $version）。

報告屬性範例

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

注意

報告屬性可簡化解決方案後端對屬性最後已知值感興趣的案例。如果解決方案後端需要以時間戳事件序列的形式處理模組遙測，例如時間序列，請使用裝置到雲端訊息。

Desired 屬性範例

在上一個範例中， 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 中樞可能會只傳送一個包含所有變更的通知。因此，如果您的應用程式需要所有中繼狀態的可靠稽核和記錄，您應該使用裝置到雲端的訊息。若要深入了解對應項通知訊息中傳回的屬性和本文，請參閱非遙測事件架構。

上述所有作業都支持開放式並行存取，而且需要 Service 連線 許可權，如控制存取 IoT 中樞一文中所定義。

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

模組作業

模組應用程式會使用下列不可部分完成的作業在模組對應項上運作：

擷取模組對應項。此作業會傳回目前連線模組的模組對應項檔（包括所需和回報的系統屬性）。
部分更新報告屬性。這項作業會啟用目前已連線模組之報告屬性的部分更新。此作業會使用方案後端針對所需屬性部分更新所使用的相同 JSON 更新格式。
觀察所需的屬性。目前連線的模組可以選擇在更新發生時收到所需屬性的通知。模組會接收解決方案後端所執行的相同更新形式（部分或完整取代）。

上述所有作業都需要 Device 連線 許可權，如控制存取 IoT 中樞一文中所定義。

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/desiredproperties/reported各有 32 KB 大小限制。這些總計是唯讀元素的獨佔，例如 $version 和 $metadata/$lastUpdated。

對應項目大小會計算如下：

針對 JSON 檔中的每個屬性，IoT 中樞累加計算屬性的索引鍵和值長度。
屬性索引鍵會被視為UTF8編碼的字串。
簡單屬性值會被視為 UTF8 編碼字串、數值（8 Bytes）或布爾值（4 Bytes）。
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 中樞模組身分識別和模組對應項

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