了解和使用 Azure IoT 中樞的裝置對應項

發行項
12/20/2024

裝置對應項是存放裝置狀態資訊的 JSON 文件，包括中繼資料、組態和條件。 Azure IoT 中樞會維持連線到 IoT 中樞的每部裝置其裝置對應項。

注意

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

本文章說明：

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

使用裝置對應項以：

將裝置特定中繼資料儲存在雲端中。例如，販賣機的位置。
報告目前的狀態資訊，例如來自裝置應用程式的可用功能和條件。例如，無論裝置是透過行動數據或 WiFi 連線到您的 IoT 中樞。
同步處理裝置應用程式與後端應用程式之間長時間執行的工作流程狀態。例如，當後端應用程式指定要安裝的新韌體版本時，裝置應用程式會報告更新程式的各個階段。
查詢您的裝置中繼資料、設定或狀態。

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

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

若要了解裝置對應項如何與 Azure IoT 隨插即用裝置所使用的裝置型號相關，請參閱了解 IoT 隨插即用數位對應項。

裝置對應項

裝置對應項會儲存下列裝置相關資訊：

裝置應用程式和後端應用程式可用來同步處理裝置條件和設定。
解決方案後端用來查詢和鎖定長時間執行的作業。

裝置對應項的生命週期會連結至對應的裝置身分識別。裝置對應項會在 IoT 中樞內建立或刪除裝置身分識別時，以隱含方式建立和刪除。

裝置對應項是 JSON 文件，其中包含：

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

顯示哪些應用程式與哪些裝置對應項屬性互動的圖表。

下列範例顯示裝置對應項 JSON 文件：

{
    "deviceId": "devA",
    "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 中樞查詢語言來查詢裝置對應項。
使用作業在大型裝置對應項集合上執行作業。

裝置作業

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

擷取裝置對應項。此作業會針對目前連線的裝置傳回裝置對應項文件 (包括所需屬性、報告屬性和系統屬性)。 (裝置應用程式看不到標籤。)
部分更新的報告屬性。這項作業會啟用目前已連線裝置之報告屬性的部分更新。
觀察所需屬性。目前連線的裝置可以選擇在所需屬性更新時收到通知。

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

Azure IoT 裝置 SDK 可讓您透過許多語言和平台輕鬆使用上述作業。如需 IoT 中樞之所需屬性同步處理基元的詳細資訊，請參閱裝置重新連線流程。

標籤和屬性格式

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

索引鍵：JSON 物件中所有索引鍵都採 UTF-8 編碼，須區分大小寫，長度上限為 1 KB。允許的字元會排除 UNICODE 控制字元 (區段 C0 和 C1)，以及 .、$ 和 SP。

注意

用於訊息路由的 IoT 中樞查詢不支援空白字元或下列任何字元做為索引鍵名稱的一部分：()<>@,;:\"/?={}。
值：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 中樞會拒絕 (並出現錯誤) 將會讓 tags、properties/desired 或 properties/reported 文件的大小增加到超過限制的所有作業。

裝置對應項中繼資料

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": {
                        "$lastUpdated": "2016-03-31T16:35:48.789Z"
                    },
                    "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 類似，您可以使用 version 屬性來強制執行更新的一致性。例如，所報告屬性的裝置應用程式或所需屬性的後端應用程式。

當觀察代理程式 (例如觀察所需屬性的裝置應用程式) 必須協調擷取作業結果與更新通知之間的爭用時，版本也很有用。裝置重新連線流程一節會提供詳細資訊。

裝置重新連線流程

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

裝置應用程式會連線至 IoT 中樞。
裝置應用程式會訂閱所需的屬性更新通知。
裝置應用程式會擷取所需屬性的完整文件。

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

下一步

若要試用本文所述的一些概念，請參閱下列 IoT 中樞文章：

共用方式為