Schémas d’événements Azure IoT Hub autres que la télémétrie

  • Article

Cet article fournit les propriétés et les schémas des événements autres que la télémétrie émis par Azure IoT Hub. Les événements autres que la télémétrie sont différents des messages appareil-à-cloud et cloud-à-appareil, car ils sont émis directement par IoT Hub en réponse à des types spécifiques de modifications d’état associées à vos appareils. Par exemple, les changements de cycle de vie tels qu’un appareil ou un module en cours de création ou de suppression, ou des modifications d’état de connexion comme un appareil ou un module qui se connecte ou se déconnecte.

Vous pouvez router des événements non liés à la télémétrie à l’aide du routage des messages ou atteindre des événements non liés à la télémétrie à l’aide d’Azure Event Grid. Pour en savoir plus sur le routage de messages IoT Hub, consultez Routage de messages IoT Hub et Réagir aux événements IoT Hub à l’aide d’Event Grid.

Les exemples d’événements de cet article ont été capturés à l’aide de la commande Azure CLI az iot hub monitor-events. Vous pouvez voir un sous-ensemble de propriétés incluses dans les événements survenant dans un point de terminaison de routage des messages.

Types d’événement disponibles

Azure IoT Hub émet les événements de non-télémétrie dans les catégories suivantes :

Catégorie d'événements Description
Événements d'état de la connexion de l'appareil Émis lorsqu’un appareil se connecte ou se déconnecte d’un hub IoT.
Événements de cycle de vie d'appareil Émis lorsqu’un appareil ou un module est créé ou supprimé d’un hub IoT.
Événements de changement du jumeau d'appareil Émis lorsqu’un jumeau d’appareil ou de module est modifié ou remplacé.
Événements de changement de jumeau numérique Émis lorsque le jumeau numérique d’un appareil ou d’un module est modifié ou remplacé.

Propriétés d’événements courantes

Les événements non de télémétrie partagent plusieurs propriétés communes.

Propriétés système

Les propriétés système suivantes sont définies par IoT Hub sur chaque événement.

Propriété Type Description Mot clé de la requête de routage
content-encoding string utf-8 $contentEncoding
content-type string application/json $contentType
correlation-id string ID unique qui identifie l’événement. $correlationId
user-id string Nom de IoT Hub qui a généré l’événement. $userId
iothub-connection-device-id string L’ID de l’appareil. $connectionDeviceId
iothub-connection-module-id string ID de module. Cette propriété est en sortie uniquement pour les événements de cycle de vie et de jumeau de module. $connectionModuleId
iothub-enqueuedtime nombre Date et heure d’envoi de la notification. Dans les requêtes de routage, utilisez un horodatage ISO8601 ; par exemple $enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source string Catégorie d’événement qui identifie la source du message. Par exemple, deviceLifecycleEvents. N/A

Propriétés de l’application

Les propriétés d’application suivantes sont définies par IoT Hub sur chaque événement.

Propriété Type Description
deviceId string L’ID de l’appareil.
hubName string Nom de IoT Hub qui a généré l’événement.
iothub-message-schema string Schéma de message associé à la catégorie d’événement ; par exemple, deviceLifecycleNotification.
moduleId string ID de module. Cette propriété est en sortie uniquement pour les événements de changement de cycle de vie et de jumeau de module.
operationTimestamp string Horodatage ISO8601 de l’opération.
opType string Identificateur de l’opération qui a généré l’événement. Par exemple, createDeviceIdentity ou deleteDeviceIdentity.

Dans les requêtes de routage, utilisez le nom de la propriété. Par exemple : deviceId = "my-device".

Événements d'état de la connexion

Les événements d’état de connexion sont émis chaque fois qu’un appareil ou un module se connecte ou se déconnecte du hub IoT.

Propriétés de l’application : Le tableau suivant montre comment les propriétés d’application sont définies pour les événements d’état de connexion :

Propriété Valeur
iothub-message-schema deviceConnectionStateNotification
opType L’une des valeurs suivantes : deviceConnected, deviceDisconnected, moduleConnected ou moduleDisconnected.

Propriétés système : Le tableau suivant montre comment les propriétés système sont définies pour les événements d’état de connexion :

Propriété Valeur
iothub-message-source deviceConnectionStateEvents

Corps : le corps contient un numéro de séquence. Le numéro de séquence est la représentation d’un nombre hexadécimal sous la forme d’une chaîne. Vous pouvez utiliser la comparaison de chaînes pour identifier le plus grand nombre. Si vous convertissez la chaîne en hexadécimal, vous obtenez un nombre de 256 bits. Le numéro de séquence est strictement croissante, et le dernier événement aura un nombre plus élevé que les autres événements. Cela est utile en cas de connexion et de déconnexion fréquentes d’appareils, et si vous souhaitez vous assurer que seul le dernier événement est utilisé pour déclencher une action en aval.

Exemple

Le code JSON suivant montre un événement d’état de connexion d’appareil émis lorsqu’un appareil se déconnecte.

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

Événements de cycle de vie d'appareil

Les événements de cycle de vie des appareils sont émis chaque fois qu’un appareil ou un module est créé ou supprimé du registre d’identités. Pour plus d’informations sur la façon dont les événements de cycle de vie des appareils sont générés, consultez Notifications de cycle de vie des appareils et des modules.

Propriétés de l’application : Le tableau suivant montre comment les propriétés d’application sont définies pour les événements de cycle de vie des appareils :

Propriété Valeur
iothub-message-schema deviceLifecycleNotification
opType Une des valeurs suivantes : createDeviceIdentity, deleteDeviceIdentity, createModuleIdentity ou deleteModuleIdentity.

Propriétés système : Le tableau suivant montre comment les propriétés système sont définies pour les événements de cycle de vie des appareils :

Propriété Valeur
iothub-message-source deviceLifecycleEvents

Corps : le corps contient une représentation du jumeau d’appareil ou du jumeau de module. Il inclut l’ID d’appareil et l’ID de module, le jumeau et la propriété de version, ainsi que les balises, les propriétés et les métadonnées associées du jumeau.

Exemple

Le code JSON suivant montre un événement de cycle de vie d’appareil émis lorsqu’un module est créé. L’événement est capturé à l’aide de la commande 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
                }
            }
        }
    }
}

Événements de changement du jumeau d'appareil

Les événements de modification de jumeau d’appareil sont émis chaque fois qu’un jumeau d’appareil ou un jumeau de module est mis à jour ou remplacé. Dans certains cas, plusieurs modifications peuvent être empaquetées dans un seul événement. Pour plus d’informations, consultez Opérations back-end de jumeau d’appareil ou Opérations back-end de jumeau de module.

Propriétés de l’application : Le tableau suivant montre comment les propriétés d’application sont définies pour les événements de modification de jumeau d'appareil :

Propriété Valeur
iothub-message-schema twinChangeNotification
opType L’une des valeurs suivantes : replaceTwin ou updateTwin.

Propriétés système : Le tableau suivant montre comment les propriétés système sont définies pour les événements de modification de jumeau d'appareil :

Propriété Valeur
iothub-message-source twinChangeEvents

Corps : sur une mise à jour, le corps contient la propriété de version du jumeau et les balises et propriétés mises à jour et leurs métadonnées associées. Sur un remplacement, le corps contient l’ID d’appareil et l’ID de module, le jumeau et la propriété de version, ainsi que toutes les balises, propriétés et métadonnées associées du jumeau d’appareil ou de module.

Exemple

Le code JSON suivant montre un événement de modification de jumeau émis pour une mise à jour d’une propriété souhaitée et une balise sur un jumeau de module. L’événement est capturé à l’aide de la commande 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
                }
            }
        }
    }
}

Étapes suivantes