Azure IoT 中心非遥测事件架构

项目
06/02/2023

本文提供 Azure IoT 中心发出的非遥测事件的属性和架构。非遥测事件与设备到云和云到设备消息的不同之处在于，它们由 IoT 中心直接发出，以响应与设备关联的特定类型的状态更改。例如，生命周期更改（如创建或删除设备或模块），或连接状态更改（如设备或模块连接或断开连接）。若要观察非遥测事件，必须配置合适的消息路由。若要详细了解 IoT 中心消息路由，请参阅 IoT 中心消息路由。

可用事件类型

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

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

自定义事件属性

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

系统属性

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

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

应用程序属性

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

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

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

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