Azure IoT 中心非遥测事件架构

2025-10-30

本文提供 Azure IoT 中心发出的非遥测事件的属性和架构。非遥测事件与设备到云和云到设备消息的不同之处在于，这些事件由 IoT 中心发出，以响应与设备关联的特定状态更改。例如，非遥测事件包括生命周期更改，例如正在创建或删除的设备或模块，或者连接状态更改（如设备或模块连接或断开连接）。

可以使用消息路由路由非遥测事件，或使用 Azure 事件网格访问非遥测事件。若要了解有关 IoT 中心消息路由的详细信息，请参阅使用 IoT 中心消息路由将设备到云的消息发送到 Azure 服务，并使用事件网格触发作来响应 IoT 中心事件。

本文中的事件示例是使用 az iot hub monitor-events Azure CLI 命令捕获的。你可能会看到到达消息路由终结点的事件中包含的属性子集。

可用事件类型

Azure IoT 中心发出以下类别的非遥测事件：

事件类别	说明
设备连接状态事件	当设备连接到 IoT 中心或从 IoT 中心断开连接时发出。
设备生命周期事件	在 IoT 中心创建或删除设备或模块时发出。
设备孪生更改事件	当更改或替换设备或模块孪生时发出。
数字孪生体更改事件	当设备或模块的数字孪生被更改或替换时发出。

自定义事件属性

非遥测事件共享多个共同的属性。

系统属性

IoT 中心在每个事件上设置以下系统属性。

properties	类型	说明	路由查询的关键字
content-encoding	字符串	utf-8	$contentEncoding
content-type	字符串	application/json	$contentType
correlation-id	字符串	识别事件的唯一 ID。	$correlationId
user-id	字符串	生成事件的 IoT 中心的名称。	$userId
iothub-connection-device-id	字符串	设备 ID。	$connectionDeviceId
iothub-connection-module-id	字符串	模块 ID。此属性仅针对模块生命周期和孪生事件输出。	$connectionModuleId
iothub-enqueuedtime	数字	发送通知的日期和时间。在路由查询中，使用 ISO 8601 时间戳;例如 `$enqueuedTime > "2022-06-06T22:56:06Z"`	$enqueuedTime
iothub-message-source	字符串	识别消息源的事件类别。例如，deviceLifecycleEvents。	空值

应用程序属性

IoT 中心在每个事件上设置以下应用程序属性。

properties	类型	说明
deviceId	字符串	设备 ID。
hubName	字符串	生成事件的 IoT 中心的名称。
iothub-message-schema	字符串	该消息架构与事件类别相关联；例如，deviceLifecycleNotification。
moduleId	字符串	模块 ID。此属性仅针对模块生命周期和孪生更改事件输出。
operationTimestamp	字符串	操作的 ISO 8601 时间戳。
opType	字符串	生成事件的操作的标识符。例如，createDeviceIdentity 或者 deleteDeviceIdentity。

在路由查询中，使用该属性名称。例如，deviceId = "my-device"。

连接状态事件

每当设备或模块与 IoT 中心连接或断开连接时，都会发出连接状态事件。

应用程序属性：下表显示了如何为连接状态事件设置应用程序属性：

properties	值
iothub-message-schema	deviceConnectionStateNotification
opType	deviceConnected 或 deviceDisconnected

模块和设备都使用 deviceConnected 和 deviceDisconnected 应用程序属性来报告连接状态事件。如果事件来自模块，则事件还包含一个 moduleId 属性。 moduleId如果没有属性，则事件来自设备。

系统属性：下表显示了如何为连接状态事件设置系统属性：

properties	值
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"
        }
    }
}

设备生命周期事件

每当在标识注册表中创建或删除设备或模块时，都会发出设备生命周期事件。有关何时生成设备生命周期事件的更多详细信息，请参阅设备和模块生命周期通知。

应用程序属性：下表显示了如何为设备生命周期事件设置应用程序属性：

properties	值
iothub-message-schema	deviceLifecycleNotification
opType	以下值之一：createDeviceIdentity、deleteDeviceIdentity。

模块和设备都使用 createDeviceIdentity 和 deleteDeviceIdentity 应用程序属性来报告连接状态事件。如果事件来自模块，则事件还包含一个 moduleId 属性。 moduleId如果没有属性，则事件来自设备。

系统属性：下表显示了如何为设备生命周期事件设置系统属性：

properties	值
iothub-message-source	deviceLifecycleEvents

正文：正文包含设备孪生或模块孪生的表示形式。它包括设备 ID 和模块 ID、孪生 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
                }
            }
        }
    }
}

设备孪生更改事件

每当更新或替换设备孪生或模块孪生时，都会发出设备孪生更改事件。在某些情况下，可能会在单个事件中打包多个更改。若要了解详细信息，请参阅有关设备孪生的后端操作或有关模块孪生的后端操作。

应用程序属性：下表显示了如何为设备孪生更改事件设置应用程序属性：

properties	值
iothub-message-schema	twinChangeNotification
opType	以下值之一：replaceTwin 或 updateTwin。

系统属性：下表显示了如何为设备孪生更改事件设置系统属性：

properties	值
iothub-message-source	twinChangeEvents

正文：在更新事件中，正文包含孪生体的版本属性以及更新的标记和属性及其关联的元数据。在替换事件中，正文包含设备 ID 和模块 ID、孪生 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 中心消息路由将设备到云的消息发送到 Azure 服务。
要了解如何向消息路由添加查询，请参阅 IoT 中心消息路由查询语法。
要了解设备到云和云到设备消息的结构，请参阅创建和读取 IoT 中心消息。

通过