Schémas d’événements Azure IoT Hub autres que la télémétrie
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 d’appareil-à-cloud et de 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
IoT Hub définit les propriétés système suivantes 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
IoT Hub définit les propriétés d’application suivantes 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 | deviceConnected ou deviceDisconnected |
Les deux modules et appareils utilisent les propriétés d’application deviceConnected et deviceDisconnected pour signaler les événements d’état de la connexion. Si l’événement provient d’un module, il comporte également une propriété moduleId. S’il n’existe aucune propriété moduleId, l’événement provient donc d’un appareil.
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 croissant, de manière à ce que le dernier événement ait un numéro plus élevé que les autres événements. Cela est utile en cas de connexions et de déconnexions 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": "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"
}
}
}
É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 | L’une des valeurs suivantes : createDeviceIdentity, deleteDeviceIdentity. |
Les deux modules et appareils utilisent les propriétés d’application createDeviceIdentity et deleteDeviceIdentity pour signaler les événements d’état de la connexion. Si l’événement provient d’un module, il comporte également une propriété moduleId. S’il n’existe aucune propriété moduleId, l’événement provient donc d’un appareil.
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, l’étiquette d’entité de jumeau, 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": "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
}
}
}
}
}
É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, l’étiquette d’entité de jumeau, 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
Pour en savoir plus sur le routage des messages, consultez Routage des messages IoT Hub.
Pour savoir comment ajouter des requêtes à vos itinéraires de message, consultez syntaxe de requête de routage des messages IoT Hub.
Pour en savoir plus sur la structure des messages appareil-à-cloud et cloud-à-appareil, consultez Créer et lire des messages IoT Hub.