Sdílet prostřednictvím

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 mimo telemetrii se liší od zpráv typu zařízení-cloud a cloud-zařízení v tom, že IoT Hub tyto události vysílá v reakci na konkrétní změny stavu přidružené k vašim zařízením. Například události, které nejsou telemetrií, zahrnují 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 k odesílání zpráv typu zařízení-cloud do služeb Azure a reakce na události služby IoT Hub pomocí služby Event Grid k aktivaci akcí.

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 nastavuje pro každou událost následující systémové vlastnosti.

Vlastnost Typ Popis Klíčové slovo pro dotaz směrování
kódování obsahu řetězec utf-8 $contentEncoding
content-type řetězec application/json $contentType
ID korelace řetězec Jedinečné ID, které identifikuje událost. $correlationId
ID uživatele řetězec Název ioT Hubu, který událost vygeneroval. $userId
iothub-connection-device-id řetězec ID zařízení. $connectionDeviceId
iothub-connection-module-id řetězec 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í Ve směrovacích dotazech použijte časové razítko ISO 8601 ; například $enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source řetězec Kategorie události, která identifikuje zdroj zprávy. Například deviceLifecycleEvents. –

Vlastnosti aplikace

IoT Hub nastaví pro každou událost následující vlastnosti aplikace.

Vlastnost Typ Popis
deviceId řetězec ID zařízení.
hubName řetězec Název ioT Hubu, který událost vygeneroval.
iothub-message-schema řetězec Schéma zpráv přidružené k kategorii události; například deviceLifecycleNotification.
moduleId řetězec ID modulu. Tato vlastnost je výstupem pouze pro události životního cyklu modulu a změny dvojčete.
operationTimestamp řetězec Časové razítko ISO 8601 operace.
opType řetězec 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í

Události stavu připojení se vygenerují vždy, když se zařízení nebo modul připojí nebo odpojí 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 deviceConnectionStateNotification
opType deviceConnected nebo deviceDisconnected

Moduly i zařízení používají deviceConnected vlastnosti aplikace k deviceDisconnected hlášení událostí stavu připojení. Pokud událost pochází z modulu, událost obsahuje moduleId také vlastnost. Pokud žádná vlastnost neexistuje moduleId , událost pochází ze zařízení.

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 deviceConnectionStateEvents

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é číslo, jedná se o 256bitové číslo. Pořadové číslo se striktně zvyšuje, takže nejnovější událost má vyšší počet než starší události. Toto pořadové číslo 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": "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"
        }
    }
}

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.

Moduly i zařízení používají createDeviceIdentity vlastnosti aplikace k deleteDeviceIdentity hlášení událostí stavu připojení. Pokud událost pochází z modulu, událost obsahuje moduleId také vlastnost. Pokud žádná vlastnost neexistuje moduleId , událost pochází ze zařízení.

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

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 pro dvojčata zařízení nebo operace back-endu pro dvojčata modulů.

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

Tělo: Při události aktualizace obsahuje tělo verzi digitálního dvojčete spolu s aktualizovanými značkami a vlastnostmi a jejich přidruženou metadatou. V události nahrazení obsahuje tělo ID zařízení a ID modulu, "etag" dvojčete, vlastnost verze a všechny značky, vlastnosti a přidružená metadata zařízení nebo dvojčete 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

  • Last updated on