Azure IoT 中樞非遙測事件結構描述

發行項
12/11/2024

本文提供 Azure IoT 中樞所發出非遙測事件的屬性和結構描述。非遙測事件與裝置到雲端和雲端到裝置訊息不同，IoT 中樞會發出這些事件，以回應與裝置相關聯的特定狀態變更。例如，生命週期變更 (像是正在建立或刪除的裝置或模組)，或連線狀態變更 (像是正在連線或中斷連線的裝置或模組)。

您可以使用訊息路由來路由傳送非遙測事件，或使用 Azure 事件方格來連線至非遙測事件。若要深入了解 IoT 中樞訊息路由，請參閱 IoT 中樞訊息路由以及使用事件方格來回應 IoT 中樞事件。

本文中的事件範例是使用 az iot hub monitor-events Azure CLI 命令所擷取。您可能會看到抵達訊息路由端點的事件中所含的屬性子集。

可用的事件類型

Azure IoT 中樞會發出下列類別中的非遙測事件：

事件類別目錄	描述
裝置連線狀態事件	當裝置連線到 IoT 中樞或中斷其連線時發出。
裝置生命週期事件	在 IoT 中樞上建立裝置或模組或從中刪除時發出。
裝置對應項變更事件	當裝置或模組對應項遭到變更或取代時發出。
數位分身變更事件	當裝置或模組的數位對應項遭到變更或取代時發出。

常見的事件屬性

非遙測事件會共用數個通用屬性。

系統屬性

IoT 中樞在每個事件上設定下列系統屬性。

屬性	類型	描述	路由查詢的關鍵字
content-encoding	string	utf-8	$contentEncoding
Content-Type	string	application/json	$contentType
correlation-id	string	可識別事件的唯一識別碼。	$correlationId
user-id	string	產生事件的 IoT 中樞名稱。	$userId
iothub-connection-device-id	string	裝置識別碼。	$connectionDeviceId
iothub-connection-module-id	string	模組識別碼。此屬性僅針對模組生命週期和對應項事件輸出。	$connectionModuleId
iothub-enqueuedtime	數值	傳送通知的日期和時間。在路由查詢中，使用 ISO8601 時間戳記；例如 `$enqueuedTime > "2022-06-06T22:56:06Z"`	$enqueuedTime
iothub-message-source	string	可識別訊息來源的事件類別。例如，deviceLifecycleEvents。	N/A

應用程式屬性

IoT 中樞在每個事件上設定下列應用程式屬性。

屬性	類型	描述
deviceId	string	裝置識別碼。
hubName	string	產生事件的 IoT 中樞名稱。
iothub-message-schema	string	與事件類別相關聯的訊息結構描述；例如 deviceLifecycleNotification。
moduleId	string	模組識別碼。此屬性僅針對模組生命週期和對應項變更事件輸出。
operationTimestamp	string	作業的 ISO8601 時間戳記。
opType	string	產生事件的作業識別碼。例如，createDeviceIdentity 或 deleteDeviceIdentity。

在路由查詢中，使用屬性名稱。例如： deviceId = "my-device" 。

連線狀態事件

每當裝置或模組與 IoT 中樞連線或中斷其連線時，就會發出連線狀態事件。

應用程式屬性：下表顯示如何為連線狀態事件設定應用程式屬性：

屬性	值
iothub-message-schema	deviceConnectionStateNotification
opType	deviceConnected 或 deviceDisconnected

模組和裝置都會使用 deviceConnected 和 deviceDisconnected 應用程式屬性來報告連線狀態事件。如果事件來自模組，則事件也會包含 moduleId 屬性。 moduleId如果沒有屬性，則事件來自裝置。

系統屬性：下表顯示如何為連線狀態事件設定系統屬性：

屬性	值
iothub-message-source	deviceConnectionStateEvents

本文：本文包含序號。序號是十六進位數字的字串表示法。您可以使用字串比較來識別較大的號碼。如果您想要將字串轉換為十六進位，號碼將是 256 位元的數字。序號會嚴格增加，因此最新的事件數目高於較舊的事件。如果您有頻繁的裝置連線和中斷連線，而且想要確保只使用最新的事件來觸發下游動作，這非常有用。

範例

下列 JSON 顯示裝置中斷連線時所發出的裝置連線狀態事件。

{
    "event": {
        "origin": "contoso-device-1",
        "module": "",
        "interface": "",
        "component": "",
        "properties": {
            "system": {
                "content_encoding": "utf-8",
                "content_type": "application/json",
                "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
                "user_id": "contoso-routing-hub"
            },
            "application": {
                "hubName": "contoso-routing-hub",
                "deviceId": "contoso-device-1",
                "opType": "deviceDisconnected",
                "iothub-message-schema": "deviceConnectionStateNotification",
                "operationTimestamp": "2022-06-01T18:43:04.5561024Z"
            }
        },
        "annotations": {
            "iothub-connection-device-id": "contoso-device-1",
            "iothub-enqueuedtime": 1654109018051,
            "iothub-message-source": "deviceConnectionStateEvents",
            "x-opt-sequence-number": 72,
            "x-opt-offset": "37344",
            "x-opt-enqueued-time": 1654109018176
        },
        "payload": {
            "sequenceNumber": "000000000000000001D8713FF7E0851400000002000000000000000000000007"
        }
    }
}

裝置生命週期事件

每當從身分識別登錄建立或刪除裝置或模組時，就會發出裝置生命週期事件。如需何時產生裝置生命週期事件的詳細資訊，請參閱裝置和模組生命週期通知。

應用程式屬性：下表顯示如何為裝置生命週期事件設定應用程式屬性：

屬性	值
iothub-message-schema	deviceLifecycleNotification
opType	下列其中一個值：createDeviceIdentity、deleteDeviceIdentity。

模組和裝置都會使用 createDeviceIdentity 和 deleteDeviceIdentity 應用程式屬性來報告連線狀態事件。如果事件來自模組，則事件也會包含 moduleId 屬性。 moduleId如果沒有屬性，則事件來自裝置。

系統屬性：下表顯示如何為裝置生命週期事件設定系統屬性：

屬性	值
iothub-message-source	deviceLifecycleEvents

本文：本文包含裝置對應項或模組對應項的表示法。它包含裝置識別碼和模組標識碼、對應項 etag、版本屬性，以及對應項的標記、屬性和相關聯的元數據。

範例

下列 JSON 顯示建立模組時發出的裝置生命週期事件。事件是使用 az iot hub monitor-events Azure CLI 命令來擷取。

{
    "event": {
        "origin": "contoso-device-2",
        "module": "module-1",
        "interface": "",
        "component": "",
        "properties": {
            "system": {
                "content_encoding": "utf-8",
                "content_type": "application/json",
                "correlation_id": "c5a4e6986c",
                "user_id": "contoso-routing-hub"
            },
            "application": {
                "hubName": "contoso-routing-hub",
                "deviceId": "contoso-device-2",
                "operationTimestamp": "2022-05-27T18:49:38.4904785Z",
                "moduleId": "module-1",
                "opType": "createDeviceIdentity",
                "iothub-message-schema": "deviceLifecycleNotification"
            }
        },
        "annotations": {
            "iothub-connection-device-id": "contoso-device-2",
            "iothub-connection-module-id": "module-1",
            "iothub-enqueuedtime": 1653677378534,
            "iothub-message-source": "deviceLifecycleEvents",
            "x-opt-sequence-number": 62,
            "x-opt-offset": "31768",
            "x-opt-enqueued-time": 1653677378643
        },
        "payload": {
            "deviceId": "contoso-device-2",
            "moduleId": "module-1",
            "etag": "AAAAAAAAAAE=",
            "version": 2,
            "properties": {
                "desired": {
                    "$metadata": {
                        "$lastUpdated": "0001-01-01T00:00:00Z"
                    },
                    "$version": 1
                },
                "reported": {
                    "$metadata": {
                        "$lastUpdated": "0001-01-01T00:00:00Z"
                    },
                    "$version": 1
                }
            }
        }
    }
}

裝置對應項變更事件

每當更新或取代裝置對應項或模組對應項時，就會發出裝置對應項變更事件。在某些情況下，可能會在單一事件中封裝數個變更。若要深入了解，請參閱裝置對應項後端作業或模組對應項後端作業。

應用程式屬性：下表顯示如何為裝置對應項變更事件設定應用程式屬性：

屬性	值
iothub-message-schema	twinChangeNotification
opType	下列其中一個值：replaceTwin 或 updateTwin。

系統屬性：下表顯示如何為裝置對應項變更事件設定系統屬性：

屬性	值
iothub-message-source	twinChangeEvents

本文：更新時，本文包含對應項的版本屬性，以及已更新的標籤和屬性及其相關聯的中繼資料。在取代上，本文包含裝置標識碼和模組標識符、對應項 etag、版本屬性，以及裝置或模組對應項的所有標記、屬性和相關聯的元數據。

範例

下列 JSON 顯示針對所需屬性的更新和模組對應項上的標籤所發出的對應項變更事件。事件是使用 az iot hub monitor-events Azure CLI 命令來擷取。

{
    "event": {
        "origin": "contoso-device-3",
        "module": "module-1",
        "interface": "",
        "component": "",
        "properties": {
            "system": {
                "content_encoding": "utf-8",
                "content_type": "application/json",
                "correlation_id": "4d1f1e2e74f",
                "user_id": "contoso-routing-hub"
            },
            "application": {
                "hubName": "contoso-routing-hub",
                "deviceId": "contoso-device-3",
                "operationTimestamp": "2022-06-01T22:27:50.2612586Z",
                "moduleId": "module-1",
                "iothub-message-schema": "twinChangeNotification",
                "opType": "updateTwin"
            }
        },
        "annotations": {
            "iothub-connection-device-id": "contoso-device-3",
            "iothub-connection-module-id": "module-1",
            "iothub-enqueuedtime": 1654122470282,
            "iothub-message-source": "twinChangeEvents",
            "x-opt-sequence-number": 17,
            "x-opt-offset": "12352",
            "x-opt-enqueued-time": 1654122470329
        },
        "payload": {
            "version": 7,
            "tags": {
                "tag1": "new value"
            },
            "properties": {
                "desired": {
                    "property1": "new value",
                    "$metadata": {
                        "$lastUpdated": "2022-06-01T22:27:50.2612586Z",
                        "$lastUpdatedVersion": 6,
                        "property1": {
                            "$lastUpdated": "2022-06-01T22:27:50.2612586Z",
                            "$lastUpdatedVersion": 6
                        }
                    },
                    "$version": 6
                }
            }
        }
    }
}

下一步

若要深入了解訊息路由，請參閱 IoT 中樞訊息路由。
若要了解如何將查詢新增至訊息路由，請參閱 IoT 中樞訊息路由查詢語法。
若要了解裝置到雲端和雲端到裝置訊息的結構，請參閱建立和讀取 IoT 中樞訊息。

共用方式為