Esquemas de eventos que no son de telemetría de Azure IoT Hub

Artículo
12/12/2024

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

Tanto los módulos como los dispositivos usan las propiedades de la aplicación deviceConnected y deviceDisconnected para notificar eventos de estado de conexión. Si el evento procede de un módulo, el evento también incluye una propiedad moduleId. Si no hay ninguna propiedad moduleId, el evento procede de un dispositivo.

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 siguientes valores: createDeviceIdentity, deleteDeviceIdentity.

Tanto los módulos como los dispositivos usan las propiedades de la aplicación createDeviceIdentity y deleteDeviceIdentity para notificar eventos de estado de conexión. Si el evento procede de un módulo, el evento también incluye una propiedad moduleId. Si no hay ninguna propiedad moduleId, el evento procede de un dispositivo.

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

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.

Compartir vía

Esquemas de eventos que no son de telemetría de Azure IoT Hub

Tipos de eventos disponibles

Propiedades personalizadas del evento

Propiedades del sistema

Propiedades de la aplicación

Eventos de estado de conexión

Ejemplo

Eventos de ciclo de vida del dispositivo

Ejemplo

Eventos de cambio de dispositivo gemelo

Ejemplo

Pasos siguientes

Comentarios

Recursos adicionales