Nicht-Telemetrieereignisschemas von Azure IoT Hub

  • Artikel

Dieser Artikel enthält die Eigenschaften und Schemas für Nicht-Telemetrie-Ereignisse, die von Azure IoT Hub ausgegeben werden. Nicht-Telemetrie-Ereignisse unterscheiden sich von Gerät-zu-Cloud- und Cloud-zu-Gerät-Nachrichten dadurch, dass sie direkt von IoT Hub als Reaktion auf bestimmte Arten von Zustandsänderungen ausgegeben werden, die Ihren Geräten zugeordnet sind. Zum Beispiel Änderungen des Lebenszyklus wie das Erstellen oder Löschen eines Geräts oder Moduls oder Änderungen des Verbindungsstatus wie das Verbinden oder Trennen eines Geräts oder Moduls.

Sie können Nicht-Telemetrieereignisse mithilfe des Nachrichtenroutings weiterleiten oder mithilfe von Azure Event Grid zu Nicht-Telemetrieereignissen gelangen. Weitere Informationen zum IoT Hub-Nachrichtenrouting finden Sie unter IoT Hub-Nachrichtenrouting und React auf IoT Hub-Ereignisse mithilfe von Event Grid.

Die Ereignisbeispiele in diesem Artikel wurden mithilfe des az iot hub monitor-events Azure CLI-Befehls erfasst. Möglicherweise sehen Sie eine Teilmenge von Eigenschaften, die in den Ereignissen enthalten sind, die an einem Nachrichtenweiterleitungsendpunkt ankommen.

Verfügbare Ereignistypen

Azure IoT Hub gibt die Nicht-Telemetrieereignisse in den folgenden Kategorien aus:

Ereigniskategorie BESCHREIBUNG
Geräteverbindungsstatus-Ereignisse Wird ausgegeben, wenn ein Gerät eine Verbindung zu einem IoT-Hub herstellt oder trennt.
Ereignisse im Gerätelebenszyklus Wird ausgegeben, wenn ein Gerät oder Modul auf einem IoT-Hub erstellt oder gelöscht wird.
Änderungsereignisse für Gerätezwillinge Wird ausgegeben, wenn ein Gerät oder Modulzwilling geändert oder ersetzt wird.
Änderungsereignisse bei digitalen Zwillingen Wird ausgegeben, wenn der digitale Zwilling eines Geräts oder Moduls geändert oder ersetzt wird.

Allgemeine Ereigniseigenschaften

Nicht-Telemetrie-Ereignisse haben mehrere gemeinsame Eigenschaften.

Systemeigenschaften

Die folgenden Systemeigenschaften werden von IoT Hub für jedes Ereignis festgelegt.

Eigenschaft Typ BESCHREIBUNG Schlüsselwort für Routingabfrage
content-encoding Zeichenfolge UTF-8 $contentEncoding
content-type Zeichenfolge Anwendung/json $contentType
correlation-id Zeichenfolge Eine eindeutige ID, die das Ereignis identifiziert. $correlationId
user-id Zeichenfolge Der Name von IoT Hub, der das Ereignis generiert hat. $userId
iothub-connection-device-id string Der Geräte-ID $connectionDeviceId
iothub-connection-module-id Zeichenfolge Die Modul-ID. Diese Eigenschaft wird nur für Modullebenszyklus- und Zwillingsereignisse ausgegeben. $connectionModuleId
iothub-enqueuedtime number Datum und Uhrzeit des Versands der Benachrichtigung. Verwenden Sie in Routing-Abfragen einen ISO8601-Zeitstempel; zum Beispiel $enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source Zeichenfolge Die Ereigniskategorie, die die Nachrichtenquelle identifiziert. Beispiel: deviceLifecycleEvents. –

Anwendungseigenschaften

Die folgenden Anwendungseigenschaften werden von IoT Hub für jedes Ereignis festgelegt.

Eigenschaft Typ Beschreibung
deviceId Zeichenfolge Der Geräte-ID
hubName Zeichenfolge Der Name des IoT Hub, der das Ereignis generiert hat.
iothub-message-schema Zeichenfolge Das der Ereigniskategorie zugeordnete Nachrichtenschema; beispielsweise deviceLifecycleNotification.
moduleId Zeichenfolge Die Modul-ID. Diese Eigenschaft wird nur für Modullebenszyklus- und Zwillingsänderungsereignisse ausgegeben.
operationTimestamp Zeichenfolge Der ISO8601-Zeitstempel des Vorgangs.
opType Zeichenfolge Der Bezeichner für den Vorgang, der das Ereignis generiert hat. Beispiel: createDeviceIdentity oder deleteDeviceIdentity.

Verwenden Sie in Routing-Abfragen den Eigenschaftsnamen. Beispiel: deviceId = "my-device".

Geräteverbindungsstatus-Ereignisse

Verbindungsstatusereignisse werden immer dann ausgegeben, wenn ein Gerät oder Modul eine Verbindung zum IoT-Hub herstellt oder trennt.

Anwendungseigenschaften: Die folgende Tabelle zeigt, wie Anwendungseigenschaften für Verbindungsstatusereignisse festgelegt werden:

Eigenschaft Wert
iothub-message-schema deviceConnectionStateNotification
opType Einer der folgenden Werte: deviceConnected, deviceDisconnected, moduleConnected oder moduleDisconnected.

Systemeigenschaften: Die folgende Tabelle zeigt, wie Systemeigenschaften für Verbindungsstatusereignisse festgelegt werden:

Eigenschaft Wert
iothub-message-source deviceConnectionStateEvents

Der Body: Der Body enthält eine Sequenznummer. Die Sequenznummer ist eine Zeichenfolgendarstellung einer Hexadezimalzahl. Sie können einen Zeichenfolgenvergleich verwenden, um die größere Zahl zu ermitteln. Wenn Sie die Zeichenfolge in Hex umwandeln, ist die Zahl eine 256-Bit-Zahl. Die Sequenznummer ist immer ansteigend, wobei das letzte Ereignis eine größere Zahl als andere Ereignisse hat. Dies ist nützlich, wenn Sie Geräte häufig verbinden und trennen und sicherstellen möchten, dass nur das letzte Ereignis verwendet wird, um eine nachgelagerte Aktion auszulösen.

Beispiel

Das folgende JSON zeigt ein Geräteverbindungsstatusereignis, das ausgegeben wird, wenn ein Gerät die Verbindung trennt.

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

Ereignisse im Gerätelebenszyklus

Gerätelebenszyklus-Ereignisse werden immer dann ausgegeben, wenn ein Gerät oder Modul erstellt oder aus der Identitätsregistrierung gelöscht wird. Weitere Einzelheiten dazu, wann Gerätelebenszyklus-Ereignisse generiert werden, finden Sie unter Geräte- und Modullebenszyklus-Benachrichtigungen.

Anwendungseigenschaften: Die folgende Tabelle zeigt, wie Anwendungseigenschaften für Gerätelebenszyklusereignisse festgelegt werden:

Eigenschaft Wert
iothub-message-schema deviceLifecycleNotification
opType Einer der folgenden Werte: createDeviceIdentity, deleteDeviceIdentity, createModuleIdentity oder deleteModuleIdentity.

Systemeigenschaften: Die folgende Tabelle zeigt, wie Systemeigenschaften für Gerätelebenszyklusereignisse festgelegt werden:

Eigenschaft Wert
iothub-message-source deviceLifecycleEvents

Der Body: Der Body enthält eine Darstellung des Gerätezwillings oder Modulzwillings. Es enthält die Geräte-ID und die Modul-ID, das Zwillings-Etag, die Versionseigenschaft und die Tags, Eigenschaften und zugehörigen Metadaten des Zwillings.

Beispiel

Das folgende JSON zeigt ein Gerätelebenszyklus-Ereignis, das ausgegeben wird, wenn ein Modul erstellt wird. Das Ereignis wird mithilfe des az iot hub monitor-eventsAzure CLI-Befehls erfasst.

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

Änderungsereignisse für Gerätezwillinge

Änderungsereignisse für Gerätezwillinge werden ausgegeben, wenn ein Gerätezwilling oder ein Modulzwilling aktualisiert oder ersetzt wird. In einigen Fällen können mehrere Änderungen in einem einzigen Ereignis gepackt werden. Weitere Informationen finden Sie unter Gerätezwillings-Back-End-Vorgänge oder Modulzwillings-Back-End-Vorgänge.

Anwendungseigenschaften: Die folgende Tabelle zeigt, wie Anwendungseigenschaften für Gerätezwillings-Änderungsereignisse festgelegt werden:

Eigenschaft Wert
iothub-message-schema twinChangeNotification
opType Einer der folgenden Werte: replaceTwin oder updateTwin.

Systemeigenschaften: Die folgende Tabelle zeigt, wie Systemeigenschaften für Gerätezwillings-Änderungsereignisse festgelegt werden:

Eigenschaft Wert
iothub-message-source twinChangeEvents

Der Body: Auf einem Update enthält der Body die Versionseigenschaft des Zwillings und die aktualisierten Tags und Eigenschaften und deren zugeordnete Metadaten. Bei einem Austausch enthält der Body die Geräte-ID und die Modul-ID, das Zwillings-Etag, die Versionseigenschaft und alle Tags, Eigenschaften und zugehörigen Metadaten des Geräte- oder Modulzwillings.

Beispiel

Das folgende JSON zeigt ein Zwillingsänderungsereignis, das für eine Aktualisierung einer gewünschten Eigenschaft und eines Tags auf einem Modulzwilling ausgegeben wird. Das Ereignis wird mithilfe des az iot hub monitor-eventsAzure CLI-Befehls erfasst.

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

Nächste Schritte