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

  • Artículo

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 distinguen de los mensajes del dispositivo a la nube y de la nube al dispositivo en que se emiten directamente desde IoT Hub en respuesta a tipos específicos de cambios de estado asociados a los 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 propiedades del sistema siguientes 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 propiedades de aplicación siguientes 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 Uno de los valores siguientes: deviceConnected, deviceDisconnected, moduleConnected o moduleDisconnected.

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 ascendente por lo que el registro más reciente tendrá un número mayor que el de los otros eventos. 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": "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"
        }
    }
}

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 identidad (ETag) 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 identidad (ETag) 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