Схемы событий Центра Интернета вещей 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 |
Модули и устройства используют 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 показано событие жизненного цикла устройства, создаваемое при создании модуля. Событие записывается с помощью команды 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": "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 показано событие изменения двойника, выдаваемое для обновления требуемого свойства и тега двойника модуля. Событие записывается с помощью команды 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
}
}
}
}
}
Следующие шаги
Дополнительные сведения о маршрутизации сообщений см. в разделе Маршрутизация сообщений Центра Интернета вещей.
Сведения о том, как добавить запросы в маршруты сообщений, см. в разделе Синтаксис запросов при маршрутизации сообщений Центра Интернета вещей.
Сведения о структуре сообщений, передаваемых с устройства в облако и из облака на устройство, см. в разделе Создание и чтение сообщений Центра Интернета вещей.