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

  • 發行項

本文提供 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、moduleConnected 或 moduleDisconnected。

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

屬性 值
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": "98dcbcf6-3398-c488-c62c-06330e65ea98",
                "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、createModuleIdentity 或 deleteModuleIdentity。

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

屬性 值
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": "createModuleIdentity",
                "iothub-message-schema": "moduleLifecycleNotification"
            }
        },
        "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
                }
            }
        }
    }
}

下一步