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

發行項
02/06/2024

裝置對應 項是 JSON 檔，可儲存裝置狀態資訊，包括元數據、組態和條件。 Azure IoT 中樞會維持連線到 IoT 中樞的每部裝置其裝置對應項。

注意

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

本文章說明：

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

使用裝置對應項以：

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

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

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

若要瞭解裝置對應項如何與 Azure IoT 隨插即用裝置所使用的裝置模型產生關聯，請參閱瞭解 IoT 隨插即用數字對應項。

裝置對應項

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

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

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

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

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

Screenshot of device twin properties

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

根物件中是裝置身分識別屬性，以及和 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 可讓您輕鬆地從許多語言和平臺使用上述作業。如需所需屬性同步處理之 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/desiredproperties/reported各有 32 KB 大小限制。這些總計是唯讀元素的獨佔，例如 $version 和 $metadata/$lastUpdated。

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

針對 JSON 檔中的每一個屬性，IoT 中樞累計計算並新增屬性索引鍵和值的長度。
屬性索引鍵會被視為UTF8編碼的字串。
簡單屬性值會被視為 UTF8 編碼字串、數值（8 Bytes）或布爾值（4 Bytes）。
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 類似，更新者可以使用版本來強制執行更新的一致性。例如，已報告屬性的裝置應用程式或所需屬性的方案後端。

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

裝置重新連線流程

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

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

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

其他參考數據

IoT 中樞開發人員指南中的其他參考主題包括：

IoT 中樞端點一文說明每個IoT中樞針對運行時間和管理作業公開的各種端點。
節流和配額一文說明套用至 IoT 中樞服務的配額，以及當您使用服務時所預期的節流行為。
Azure IoT 裝置和服務 SDK 一文列出當您開發與 IoT 中樞互動的裝置和服務應用程式時，可以使用的各種語言 SDK。
裝置對應項、作業和訊息路由的 IoT 中樞查詢語言一文說明可用來從裝置對應項和作業 IoT 中樞擷取資訊 IoT 中樞查詢語言。
IoT 中樞 MQTT 支援一文提供有關 MQTT 通訊協定 IoT 中樞支援的詳細資訊。

下一步

現在您已瞭解裝置對應項，您可能對下列 IoT 中樞開發人員指南主題感興趣：

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

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