Schémata událostí mimo telemetrii služby Azure IoT Hub
Tento článek obsahuje vlastnosti a schémata pro události mimo telemetrii generované službou Azure IoT Hub. Události nesouvisející s telemetrií se liší od zpráv typu zařízení-cloud a cloud-zařízení v tom, že jsou generovány přímo službou IoT Hub v reakci na konkrétní druhy změn stavu přidružených k vašim zařízením. Například změny životního cyklu, jako je vytvoření nebo odstranění zařízení nebo modulu, nebo změny stavu připojení, jako je zařízení nebo modul, které se připojují nebo odpojí.
Události, které nejsou telemetrií, můžete směrovat směrováním zpráv nebo se spojit s událostmi mimo telemetrii pomocí služby Azure Event Grid. Další informace o směrování zpráv služby IoT Hub najdete v tématu Směrování zpráv služby IoT Hub a reakce na události služby IoT Hub pomocí služby Event Grid.
Příklady událostí v tomto článku byly zachyceny pomocí az iot hub monitor-events příkazu Azure CLI. Může se zobrazit podmnožina vlastností zahrnutých v událostech, které přicházejí do koncového bodu směrování zpráv.
Dostupné typy událostí
Azure IoT Hub generuje události, které nejsou telemetrií, v následujících kategoriích:
| Kategorie události | Popis |
|---|---|
| Události stavu připojení zařízení | Vygenerováno, když se zařízení připojí k centru IoT nebo se od ho odpojí. |
| Události životního cyklu zařízení | Vygeneruje se při vytvoření nebo odstranění zařízení nebo modulu z ioT Hubu. |
| Události změny dvojčete zařízení | Vygeneruje se při změně nebo nahrazení dvojčete zařízení nebo modulu. |
| Události změn digitálního dvojčete | Vygeneruje se při změně nebo nahrazení digitálního dvojčete zařízení nebo modulu. |
Běžné vlastnosti událostí
Události mimo telemetrii sdílejí několik společných vlastností.
Systémové vlastnosti
IoT Hub pro každou událost nastaví následující systémové vlastnosti.
| Vlastnost | Type | Popis | Klíčové slovo pro dotaz směrování |
|---|---|---|---|
| kódování obsahu | string | utf-8 | $contentEncoding |
| content-type | string | application/json | $contentType |
| ID korelace | string | Jedinečné ID, které identifikuje událost. | $correlationId |
| ID uživatele | string | Název ioT Hubu, který událost vygeneroval. | $userId |
| iothub-connection-device-id | string | ID zařízení. | $connectionDeviceId |
| iothub-connection-module-id | string | ID modulu. Tato vlastnost je výstupem pouze pro události životního cyklu modulu a dvojčete. | $connectionModuleId |
| iothub-enqueuedtime | Číslo | Datum a čas odeslání oznámení V dotazech směrování použijte časové razítko ISO8601 , například $enqueuedTime > "2022-06-06T22:56:06Z" |
$enqueuedTime |
| iothub-message-source | string | Kategorie události, která identifikuje zdroj zprávy. Například deviceLifecycleEvents. | – |
Vlastnosti aplikace
Pro každou událost nastaví služba IoT Hub následující vlastnosti aplikace.
| Vlastnost | Type | Popis |
|---|---|---|
| deviceId | string | ID zařízení. |
| hubName | string | Název ioT Hubu, který událost vygeneroval. |
| iothub-message-schema | string | Schéma zpráv přidružené k kategorii události; například deviceLifecycleNotification. |
| moduleId | string | ID modulu. Tato vlastnost je výstupem pouze pro události životního cyklu modulu a změny dvojčete. |
| operationTimestamp | string | Časové razítko ISO8601 operace. |
| opType | string | Identifikátor operace, která událost vygenerovala. Například createDeviceIdentity nebo deleteDeviceIdentity. |
V dotazech směrování použijte název vlastnosti. Například deviceId = "my-device".
události stavu Připojení
Připojení události stavu se vygenerují při každém připojení zařízení nebo modulu nebo odpojení od centra IoT.
Vlastnosti aplikace: Následující tabulka ukazuje, jak jsou vlastnosti aplikace nastaveny pro události stavu připojení:
| Vlastnost | Hodnota |
|---|---|
| iothub-message-schema | device Připojení ionStateNotification |
| opType | Jedna z následujících hodnot: device Připojení ed, deviceDisconnected, module Připojení ed nebo moduleDisconnected. |
Systémové vlastnosti: Následující tabulka ukazuje, jak jsou vlastnosti systému nastaveny pro události stavu připojení:
| Vlastnost | Hodnota |
|---|---|
| iothub-message-source | device Připojení ionStateEvents |
Text: Tělo obsahuje pořadové číslo. Pořadové číslo je řetězcové vyjádření šestnáctkového čísla. K identifikaci většího čísla můžete použít porovnání řetězců. Pokud převádíte řetězec na šestnáctkový, bude číslo 256bitové číslo. Pořadové číslo se striktně zvyšuje a nejnovější událost bude mít vyšší počet než jiné události. To je užitečné, pokud máte časté připojení a odpojení zařízení a chcete zajistit, aby se k aktivaci podřízené akce použila pouze nejnovější událost.
Příklad
Následující KÓD JSON ukazuje událost stavu připojení zařízení, která se vygeneruje při odpojení zařízení.
{
"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"
}
}
}
Události životního cyklu zařízení
Události životního cyklu zařízení se generují při každém vytvoření nebo odstranění zařízení nebo modulu z registru identit. Další podrobnosti o vygenerování událostí životního cyklu zařízení najdete v tématu Oznámení o životním cyklu zařízení a modulu.
Vlastnosti aplikace: Následující tabulka ukazuje, jak jsou vlastnosti aplikace nastaveny pro události životního cyklu zařízení:
| Vlastnost | Hodnota |
|---|---|
| iothub-message-schema | deviceLifecycleNotification |
| opType | Jedna z následujících hodnot: createDeviceIdentity, deleteDeviceIdentity, createModuleIdentity nebo deleteModuleIdentity. |
Vlastnosti systému: Následující tabulka ukazuje, jak jsou systémové vlastnosti nastaveny pro události životního cyklu zařízení:
| Vlastnost | Hodnota |
|---|---|
| iothub-message-source | deviceLifecycleEvents |
Tělo: Tělo obsahuje reprezentaci dvojčete zařízení nebo dvojče modulu. Zahrnuje ID zařízení a ID modulu, značku dvojčete, vlastnost verze a značky, vlastnosti a přidružená metadata dvojčete.
Příklad
Následující JSON ukazuje událost životního cyklu zařízení, která se vygeneruje při vytvoření modulu. Událost se zaznamenává pomocí az iot hub monitor-events příkazu Azure CLI.
{
"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
}
}
}
}
}
Události změny dvojčete zařízení
Události změny dvojčete zařízení se vygenerují při každé aktualizaci nebo nahrazení dvojčete zařízení nebo dvojčete modulu. V některých případech může být v jedné události zabaleno několik změn. Další informace najdete v tématu Operace back-endu dvojčete zařízení nebo operace back-endu dvojčete modulu.
Vlastnosti aplikace: Následující tabulka ukazuje, jak jsou vlastnosti aplikace nastaveny pro události změny dvojčete zařízení:
| Vlastnost | Hodnota |
|---|---|
| iothub-message-schema | twinChangeNotification |
| opType | Jedna z následujících hodnot: replaceTwin nebo updateTwin. |
Systémové vlastnosti: Následující tabulka ukazuje, jak jsou systémové vlastnosti nastaveny pro události změny dvojčete zařízení:
| Vlastnost | Hodnota |
|---|---|
| iothub-message-source | twinChangeEvents |
Text: V aktualizaci obsahuje tělo vlastnost verze dvojčete a aktualizované značky a vlastnosti a jejich přidružená metadata. Nahrazování obsahuje tělo ID zařízení a ID modulu, značku dvojčete, vlastnost verze a všechny značky, vlastnosti a přidružená metadata dvojčete zařízení nebo modulu.
Příklad
Následující KÓD JSON ukazuje událost změny dvojčete vygenerované pro aktualizaci požadované vlastnosti a značky dvojčete modulu. Událost se zaznamenává pomocí az iot hub monitor-events příkazu Azure CLI.
{
"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
}
}
}
}
}
Další kroky
Další informace o směrování zpráv najdete v tématu Směrování zpráv ve službě IoT Hub.
Informace o tom, jak přidávat dotazy do tras zpráv, najdete v tématu Syntaxe dotazů směrování zpráv služby IoT Hub.
Další informace o struktuře zpráv typu zařízení-cloud a cloud-zařízení najdete v tématu Vytváření a čtení zpráv ioT Hubu.