Schematy zdarzeń spoza telemetrii usługi Azure IoT Hub

Ten artykuł zawiera właściwości i schematy zdarzeń nie telemetrycznych emitowanych przez usługę Azure IoT Hub. Zdarzenia inne niż zdarzenia telemetryczne różnią się od komunikatów urządzenie-chmura i chmura-urządzenie w usłudze IoT Hub emitujących te zdarzenia w odpowiedzi na określone zmiany stanu skojarzone z urządzeniami. Na przykład zdarzenia niezwiązane z telemetrią obejmują zmiany cyklu życia, takie jak tworzenie lub usuwanie urządzenia lub modułu albo zmiany stanu połączenia, takie jak łączenie lub rozłączanie urządzenia lub modułu.

Zdarzenia niezwiązane z telemetrią można kierować przy użyciu routingu komunikatów lub dotrzeć do zdarzeń niezwiązanych z telemetrią przy użyciu usługi Azure Event Grid. Aby dowiedzieć się więcej na temat routingu komunikatów usługi IoT Hub, zobacz Używanie routingu komunikatów usługi IoT Hub do wysyłania komunikatów z urządzenia do chmury do usług platformy Azure i reagowania na zdarzenia usługi IoT Hub przy użyciu usługi Event Grid do wyzwalania akcji.

Przykłady zdarzeń w tym artykule zostały przechwycone przy użyciu polecenia interfejsu wiersza polecenia platformy az iot hub monitor-events Azure. Może zostać wyświetlony podzestaw właściwości uwzględnionych w zdarzeniach, które docierają do punktu końcowego routingu komunikatów.

Dostępne typy zdarzeń

Usługa Azure IoT Hub emituje zdarzenia niezwiązane z telemetrią w następujących kategoriach:

Typowe właściwości zdarzenia

Zdarzenia niezwiązane z telemetrią mają kilka typowych właściwości.

Właściwości systemu

Usługa IoT Hub ustawia następujące właściwości systemowe dla każdego zdarzenia.

Właściwości aplikacji

Usługa IoT Hub ustawia następujące właściwości aplikacji dla każdego zdarzenia.

W zapytaniach routingu użyj nazwy właściwości. Na przykład deviceId = "my-device".

Zdarzenia stanu połączenia

Zdarzenia stanu połączenia są emitowane za każdym razem, gdy urządzenie lub moduł łączy się lub rozłącza z centrum IoT.

Właściwości aplikacji: W poniższej tabeli przedstawiono sposób ustawiania właściwości aplikacji dla zdarzeń stanu połączenia:

Oba moduły i urządzenia używają deviceConnected właściwości i deviceDisconnected aplikacji do raportowania zdarzeń stanu połączenia. Jeśli zdarzenie pochodzi z modułu, zdarzenie zawiera moduleId również właściwość. Jeśli nie ma moduleId właściwości, zdarzenie pochodzi z urządzenia.

Właściwości systemu: W poniższej tabeli przedstawiono sposób ustawiania właściwości systemu dla zdarzeń stanu połączenia:

Treść: treść zawiera numer sekwencji. Numer sekwencji jest reprezentacją ciągu liczby szesnastkowej. Możesz użyć porównania ciągów, aby zidentyfikować większą liczbę. Jeśli konwertujesz ciąg na format szesnastkowy, to liczba jest 256-bitowa. Liczba sekwencji jest ściśle zwiększana, więc najnowsze zdarzenie ma większą liczbę niż starsze zdarzenia. Ten numer sekwencji jest przydatny, jeśli często łączy się i rozłącza urządzenie i chcesz upewnić się, że do wyzwalania akcji podrzędnej jest używane tylko najnowsze zdarzenie.

Przykład

Poniższy kod JSON pokazuje zdarzenie stanu połączenia urządzenia emitowane po rozłączeniu urządzenia.

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

Zdarzenia cyklu życia urządzenia

Zdarzenia cyklu życia urządzenia są emitowane za każdym razem, gdy urządzenie lub moduł zostanie utworzone lub usunięte z rejestru tożsamości. Aby uzyskać więcej informacji na temat generowania zdarzeń cyklu życia urządzenia, zobacz Powiadomienia dotyczące cyklu życia urządzenia i modułu.

Właściwości aplikacji: W poniższej tabeli przedstawiono sposób ustawiania właściwości aplikacji dla zdarzeń cyklu życia urządzenia:

Oba moduły i urządzenia używają createDeviceIdentity właściwości i deleteDeviceIdentity aplikacji do raportowania zdarzeń stanu połączenia. Jeśli zdarzenie pochodzi z modułu, zdarzenie zawiera moduleId również właściwość. Jeśli nie ma moduleId właściwości, zdarzenie pochodzi z urządzenia.

Właściwości systemu: W poniższej tabeli przedstawiono sposób ustawiania właściwości systemu dla zdarzeń cyklu życia urządzenia:

Treść: treść zawiera reprezentację bliźniaczej reprezentacji urządzenia lub bliźniaczej reprezentacji modułu. Zawiera identyfikator urządzenia i identyfikator modułu, bliźniacze elementy etag, właściwość wersji oraz tagi, właściwości i skojarzone metadane bliźniaczej reprezentacji.

Przykład

Poniższy kod JSON przedstawia zdarzenie cyklu życia urządzenia emitowane podczas tworzenia modułu. Zdarzenie jest przechwytywane przy użyciu polecenia interfejsu wiersza polecenia platformy az iot hub monitor-events 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": "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
                }
            }
        }
    }
}

Zdarzenia zmiany bliźniaczej reprezentacji urządzenia

Zdarzenia zmiany bliźniaczej reprezentacji urządzenia są emitowane za każdym razem, gdy bliźniacze reprezentacje urządzenia lub bliźniacze reprezentacje modułu zostaną zaktualizowane lub zastąpione. W niektórych przypadkach kilka zmian może być spakowanych w jednym zdarzeniu. Aby dowiedzieć się więcej, zobacz Operacje zaplecza dla bliźniaczych reprezentacji urządzeń lub Operacje zaplecza dla bliźniaczych reprezentacji modułów.

Właściwości aplikacji: W poniższej tabeli przedstawiono sposób ustawiania właściwości aplikacji dla zdarzeń zmiany bliźniaczej reprezentacji urządzenia:

Właściwości systemu: W poniższej tabeli przedstawiono sposób ustawiania właściwości systemu dla zdarzeń zmiany bliźniaczej reprezentacji urządzenia:

Treść: W przypadku zdarzenia aktualizacji treść zawiera właściwość wersji bliźniaka cyfrowego oraz zaktualizowane tagi i właściwości oraz skojarzone z nimi metadane. W przypadku zdarzenia zastąpienia treść zawiera identyfikator urządzenia i identyfikator modułu, etag bliźniaka, właściwość wersji oraz wszystkie tagi, właściwości i skojarzone metadane bliźniaka urządzenia lub modułu.

Przykład

Poniższy kod JSON przedstawia zdarzenie zmiany bliźniaczej reprezentacji emitowane dla aktualizacji żądanej właściwości i tagu na bliźniaczej reprezentacji modułu. Zdarzenie jest przechwytywane przy użyciu polecenia interfejsu wiersza polecenia platformy az iot hub monitor-events 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
                }
            }
        }
    }
}

Następne kroki

• Aby dowiedzieć się więcej na temat routingu komunikatów, zobacz Wysyłanie komunikatów z urządzenia do chmury do usług platformy Azure przy użyciu routingu komunikatów usługi IoT Hub.

• Aby dowiedzieć się, jak dodawać zapytania do tras komunikatów, zobacz Składnia zapytania routingu komunikatów usługi IoT Hub.

• Aby dowiedzieć się więcej o strukturze komunikatów urządzenie-chmura i komunikaty z chmury do urządzenia, zobacz Tworzenie i odczytywanie komunikatów usługi IoT Hub.