Esquemas de eventos que no son de telemetría de Azure IoT Hub
En este artículo se proporcionan las propiedades y los esquemas de los eventos que no son de telemetría emitidos por Azure IoT Hub. Los eventos que no son de telemetría se diferencian de los mensajes de dispositivo a nube y de nube a dispositivo en que IoT Hub emite estos eventos en respuesta a cambios de estado específicos asociados a sus dispositivos. Estos son, por ejemplo, cambios del ciclo de vida, como la creación o eliminación de un dispositivo o un módulo, o cambios del estado de conexión, como la conexión o desconexión de un dispositivo o un módulo.
Puede enrutar eventos que no son de telemetría mediante el enrutamiento de mensajes o acceder a eventos que no son de telemetría mediante Azure Event Grid. Para más información sobre el enrutamiento de mensajes de IoT Hub, consulte Enrutamiento de mensajes de IoT Hub y Eventos de React to IoT Hub mediante Event Grid.
Los ejemplos de eventos de este artículo se capturaron mediante el az iot hub monitor-events
Comando de la CLI de Azure. Es posible que vea un subconjunto de propiedades incluidas en los eventos que llegan a un punto de conexión de enrutamiento de mensajes.
Tipos de eventos disponibles
Azure IoT Hub emite los eventos que no son de telemetría en las categorías siguientes:
Categoría de eventos | Descripción |
---|---|
Eventos del estado de conexión del dispositivo | Se emiten cuando un dispositivo se conecta o se desconecta de un centro de IoT. |
Eventos de ciclo de vida del dispositivo | Se emiten cuando se crea o se elimina un dispositivo o un módulo de un centro de IoT. |
Eventos de cambio de dispositivo gemelo | Se emiten cuando se cambia o se reemplaza un dispositivo o módulo gemelo. |
Eventos de cambio de gemelo digital | Se emiten cuando se cambia o se reemplaza un gemelo digital de un dispositivo o un módulo. |
Propiedades personalizadas del evento
Los eventos que no son de telemetría comparten varias propiedades comunes.
Propiedades del sistema
IoT Hub establece las siguientes propiedades del sistema en cada evento.
Propiedad | Tipo | Descripción | Palabra clave para el enrutamiento de la consulta |
---|---|---|---|
content-encoding | string | utf-8 | $contentEncoding |
content-type | string | application/json | $contentType |
correlation-id | string | Identificador único que identifica el evento. | $correlationId |
user-id | string | Nombre del IoT Hub que ha generado el evento. | $userId |
iothub-connection-device-id | string | El identificador del dispositivo. | $connectionDeviceId |
iothub-connection-module-id | string | Id. de módulo. Esta propiedad solo se genera para el ciclo de vida del módulo y eventos gemelos. | $connectionModuleId |
iothub-enqueuedtime | number | Fecha y hora en que se envió la notificación. En las consultas de enrutamiento, use una marca de tiempo ISO8601; por ejemplo, $enqueuedTime > "2022-06-06T22:56:06Z" |
$enqueuedTime |
iothub-message-source | string | Categoría de evento que identifica el origen del mensaje. Por ejemplo, deviceLifecycleEvents. | N/D |
Propiedades de la aplicación
IoT Hub establece las siguientes propiedades de la aplicación en cada evento.
Propiedad | Tipo | Descripción |
---|---|---|
deviceId | string | El identificador del dispositivo. |
hubName | string | Nombre del IoT Hub que ha generado el evento. |
iothub-message-schema | string | Esquema de mensaje asociado a la categoría de evento; por ejemplo, deviceLifecycleNotification. |
moduleId | string | Id. de módulo. Esta propiedad solo se genera para el ciclo de vida del módulo y eventos de cambio de gemelo. |
operationTimestamp | string | La marca de tiempo ISO8601 de la operación. |
opType | string | Identificador de la operación que generó el evento. Por ejemplo, createDeviceIdentity o deleteDeviceIdentity. |
En las consultas de enrutamiento, use el nombre de la propiedad. Por ejemplo, deviceId = "my-device"
.
Eventos de estado de conexión
Los eventos de estado de conexión se emiten cada vez que un dispositivo o módulo se conecta o se desconecta del centro de IoT.
Propiedades de la aplicación: en la tabla siguiente se muestra cómo se establecen las propiedades de la aplicación para eventos de estado de conexión:
Propiedad | Valor |
---|---|
iothub-message-schema | deviceConnectionStateNotification |
opType | deviceConnected o deviceDisconnected |
Propiedades del sistema: en la tabla siguiente se muestra cómo se establecen las propiedades del sistema para eventos de estado de conexión:
Propiedad | Valor |
---|---|
iothub-message-source | deviceConnectionStateEvents |
Cuerpo: el cuerpo contiene un número de secuencia. El número de secuencia es una representación de cadena de un número hexadecimal. Puede usar la comparación de cadenas para identificar el número más grande. Si va a convertir la cadena a hexadecimal, el número será de 256 bits. El número de secuencia es estrictamente creciente, por lo que el último evento tiene un número mayor que los eventos más antiguos. Esto resulta útil si tiene conexiones y desconexiones frecuentes de dispositivo y quiere asegurarse de que solo el evento más reciente se usa para desencadenar una acción de bajada.
Ejemplo
El código JSON siguiente muestra un evento de estado de conexión de dispositivo que se emite cuando un dispositivo se desconecta.
{
"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"
}
}
}
Eventos de ciclo de vida del dispositivo
Los eventos de ciclo de vida del dispositivo se emiten cada vez que se crea o se elimina un dispositivo o módulo del registro de identidades. Para obtener más detalles sobre cuándo se generan eventos del ciclo de vida de los dispositivos, consulte Notificaciones de ciclo de vida de dispositivo y módulo.
Propiedades de la aplicación: en la tabla siguiente se muestra cómo se establecen las propiedades de la aplicación para eventos de ciclo de vida del dispositivo:
Propiedad | Valor |
---|---|
iothub-message-schema | deviceLifecycleNotification |
opType | Uno de los valores siguientes: createDeviceIdentity, deleteDeviceIdentity, createModuleIdentity o deleteModuleIdentity. |
Propiedades del sistema: en la tabla siguiente se muestra cómo se establecen las propiedades del sistema para eventos de ciclo de vida del dispositivo:
Propiedad | Valor |
---|---|
iothub-message-source | deviceLifecycleEvents |
Cuerpo: el cuerpo contiene una representación del dispositivo gemelo o del módulo gemelo. Incluye el identificador del dispositivo y el identificador del módulo, la etiqueta de entidad de gemelo, la propiedad de versión, así como las etiquetas, propiedades y metadatos asociados del gemelo.
Ejemplo
El código JSON siguiente muestra un evento de ciclo de vida del dispositivo que se emite cuando se crea un módulo. El evento se captura mediante el comando az iot hub monitor-events
de la CLI de Azure.
{
"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
}
}
}
}
}
Eventos de cambio de dispositivo gemelo
Los eventos de cambio de dispositivo gemelo se emiten cada vez que se actualiza o se reemplaza un dispositivo gemelo o un módulo gemelo. En algunos casos, se pueden empaquetar varios cambios en un único evento. Para obtener más información, consulte Operaciones back-end de dispositivos gemelos u Operaciones back-end de módulos gemelos.
Propiedades de la aplicación: en la tabla siguiente se muestra cómo se establecen las propiedades de la aplicación para eventos de cambio de dispositivo gemelo:
Propiedad | Valor |
---|---|
iothub-message-schema | twinChangeNotification |
opType | Uno de los valores siguientes: replaceTwin o updateTwin. |
Propiedades del sistema: en la tabla siguiente se muestra cómo se establecen las propiedades del sistema para eventos de cambio de dispositivo gemelo:
Propiedad | Valor |
---|---|
iothub-message-source | twinChangeEvents |
Cuerpo: en una actualización, el cuerpo contiene la propiedad de versión del gemelo y las etiquetas y propiedades actualizadas, así como los metadatos asociados. En un reemplazo, el cuerpo contiene el identificador del dispositivo y el identificador del módulo, la etiqueta de entidad de gemelo, la propiedad de versión, así como todas las etiquetas, propiedades y metadatos asociados del dispositivo gemelo o del módulo gemelo.
Ejemplo
El código JSON siguiente muestra un evento de cambio de gemelo que se emite para la actualización de una propiedad deseada y una etiqueta en un módulo gemelo. El evento se captura mediante el comando az iot hub monitor-events
de la CLI de Azure.
{
"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
}
}
}
}
}
Pasos siguientes
Para obtener información sobre el enrutamiento de mensajes, consulte Enrutamiento de mensajes de IoT Hub.
Para obtener información sobre cómo agregar consultas a las rutas de mensajes, consulte Sintaxis de las consultas de enrutamiento de mensajes de IoT Hub.
Para obtener información sobre la estructura de los mensajes del dispositivo a la nube y de la nube al dispositivo, consulte Creación y lectura de mensajes de IoT Hub.