Поделиться через

Схемы событий Центра Интернета вещей Azure, не связанных с телеметрией

  • Статья

В этой статье описаны свойства и схема для событий, создаваемых Центром Интернета вещей Azure и не связанных с телеметрией. События, не связанные с телеметрией, отличаются от сообщений с устройства в облако и из облака на устройство тем, что они создаются непосредственно Центром Интернета вещей в ответ на определенные изменения состояния, связанные с устройствами. К таким изменениям относятся, например, изменения в рамках жизненного цикла, такие как создание или удаление устройства или модуля, или изменения состояния подключения, например, подключение или отключение устройства или модуля.

События, отличные от телеметрии, можно направлять с помощью маршрутизации сообщений или обращаться к событиям, не относящихся к телеметрии, с помощью Сетка событий Azure. Дополнительные сведения о маршрутизации сообщений Центр Интернета вещей см. в статье Центр Интернета вещей маршрутизации сообщений и Реагирование на события Центр Интернета вещей с помощью сетки событий.

Примеры событий в этой статье были записаны с помощью az iot hub monitor-events команды Azure CLI. Вы можете увидеть подмножество свойств, включенных в события, поступающие в конечную точку маршрутизации сообщений.

Доступные типы событий

Центр Интернета вещей Azure создает события, не связанные с телеметрией, в следующих категориях:

Категория событий Description
События, связанные с состоянием подключения устройства Создаются, когда устройство подключается к Центру Интернета вещей или отключается от него.
События жизненного цикла устройства Создаются при создании устройства или модуля в Центре Интернета вещей или их удалении из него.
События изменения двойников устройств Создается при изменении или замене двойника устройства или модуля.
События изменения цифровых двойников Создается при изменении или замене цифрового двойника устройства или модуля.

Общие свойства событий

События, не связанные с телеметрией, имеют несколько общих свойств.

Свойства системы

Следующие системные свойства задаются Центром Интернета вещей для каждого события.

Свойство Type Описание Ключевое слово для запроса маршрутизации
content-encoding строка utf-8 $contentEncoding
тип_содержимого строка application/json $contentType
correlation-id строка Уникальный идентификатор, определяющий событие. $correlationId
user-id строка Имя Центра Интернета вещей, создавшего событие. $userId
iothub-connection-device-id строка идентификатор устройства; $connectionDeviceId
iothub-connection-module-id строка Идентификатор модуля. Это свойство выводится только для событий жизненного цикла модуля и двойников. $connectionModuleId
iothub-enqueuedtime number Дата и время отправки уведомления. В запросах маршрутизации используйте метку времени ISO8601, например, $enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source строка Категория событий, идентифицирующая источник сообщения. Например, deviceLifecycleEvents. Н/П

Свойства приложения

Следующие свойства приложения задаются Центром Интернета вещей для каждого события.

Свойство Type Описание
deviceId строка идентификатор устройства;
hubName строка Имя Центра Интернета вещей, создавшего событие.
iothub-message-schema строка Схема сообщения, связанная с категорией события; например, deviceLifecycleNotification.
moduleId строка Идентификатор модуля. Это свойство выводится только для событий жизненного цикла модуля и событий изменения двойников.
operationTimestamp строка Метка времени операции в формате ISO8601.
opType строка Идентификатор операции, создавшей событие. Например, createDeviceIdentity или deleteDeviceIdentity.

В запросах маршрутизации используйте имя свойства. Например, deviceId = "my-device".

События, связанные с состоянием подключения

События, связанные с состоянием подключения, создаются всякий раз, когда устройство или модуль подключаются к Центру Интернета вещей или отключаются от него.

Свойства приложения: в следующей таблице показано, как свойства приложения задаются для событий, связанных с состоянием подключения:

Свойство Значение
iothub-message-schema deviceConnectionStateNotification
opType deviceConnected или deviceDisconnected

Системные свойства: в следующей таблице показано, как задаются системные свойства для событий, связанных с состоянием подключения:

Свойство Значение
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

Текст: текст содержит представление двойника устройства или двойника модуля. Он включает идентификатор устройства и идентификатор модуля, тег сущности двойника, свойство версии, а также теги, свойства и связанные метаданные двойника.

Пример

В следующем коде JSON показано событие жизненного цикла устройства, создаваемое при создании модуля. Событие записывается с помощью команды Azure CLI az iot hub monitor-events.

{
    "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

Текст: при обновлении текст содержит свойство версии двойника, а также обновленные теги и свойства и связанные с ними метаданные. При замене текст содержит идентификатор устройства и идентификатор модуля, тег сущности двойника, свойство версии, а также все теги, свойства и связанные метаданные двойника устройства или модуля.

Пример

В следующем коде JSON показано событие изменения двойника, выдаваемое для обновления требуемого свойства и тега двойника модуля. Событие записывается с помощью команды Azure CLI az iot hub monitor-events.

{
    "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
                }
            }
        }
    }
}

Следующие шаги