Gebeurtenisschema's voor niet-telemetriegegevens in Azure IoT Hub

Dit artikel bevat de eigenschappen en schema's voor niet-telemetriegebeurtenissen die worden verzonden door Azure IoT Hub. Niet-telemetriegebeurtenissen verschillen van apparaat-naar-cloud- en cloud-naar-apparaat-berichten in die IoT Hub deze gebeurtenissen verzendt als reactie op specifieke statuswijzigingen die zijn gekoppeld aan uw apparaten. Niet-telemetriegebeurtenissen bevatten bijvoorbeeld levenscycluswijzigingen, zoals een apparaat of module die wordt gemaakt of verwijderd, of wijzigingen in de verbindingsstatus, zoals een apparaat of module die verbinding maakt of de verbinding verbreekt.

U kunt niet-telemetriegebeurtenissen routeren met behulp van berichtroutering of bereiken naar niet-telemetriegebeurtenissen met behulp van Azure Event Grid. Zie IoT Hub-berichtroutering gebruiken om apparaat-naar-cloud-berichten te verzenden naar Azure-services en React to IoT Hub-gebeurtenissen door Event Grid te gebruiken om acties te activeren voor meer informatie over ioT Hub-berichtroutering.

De gebeurtenisvoorbeelden in dit artikel zijn vastgelegd met behulp van de az iot hub monitor-events Azure CLI-opdracht. Mogelijk ziet u een subset eigenschappen die zijn opgenomen in de gebeurtenissen die binnenkomen bij een eindpunt voor berichtroutering.

Beschikbare gebeurtenistypen

Azure IoT Hub verzendt de niet-telemetriegebeurtenissen in de volgende categorieën:

Algemene gebeurteniseigenschappen

Niet-telemetriegebeurtenissen delen verschillende algemene eigenschappen.

Systeemeigenschappen

IoT Hub stelt de volgende systeemeigenschappen voor elke gebeurtenis in.

Toepassingseigenschappen

IoT Hub stelt de volgende toepassingseigenschappen voor elke gebeurtenis in.

Gebruik in routeringsquery's de naam van de eigenschap. Bijvoorbeeld: deviceId = "my-device".

Verbindingsstatus-gebeurtenissen

Verbindingsstatus-gebeurtenissen worden verzonden wanneer een apparaat of module verbinding maakt of de verbinding met de IoT-hub verbreekt.

Toepassingseigenschappen: In de volgende tabel ziet u hoe toepassingseigenschappen worden ingesteld voor verbindingsstatus gebeurtenissen:

Zowel modules als apparaten gebruiken de deviceConnected en deviceDisconnected toepassingseigenschappen om verbindingsstatus gebeurtenissen te rapporteren. Als de gebeurtenis afkomstig is van een module, bevat de gebeurtenis ook een moduleId eigenschap. Als er geen moduleId eigenschap is, is de gebeurtenis afkomstig van een apparaat.

Systeemeigenschappen: In de volgende tabel ziet u hoe systeemeigenschappen worden ingesteld voor verbindingsstatus gebeurtenissen:

Hoofdtekst: De hoofdtekst bevat een volgnummer. Het volgnummer is een tekenreeksweergave van een hexadecimaal getal. U kunt tekenreeksen vergelijken om het grotere getal te identificeren. Als u de tekenreeks converteert naar hex, is het getal een 256-bits getal. Het volgnummer neemt strikt toe, dus de laatste gebeurtenis heeft een hoger aantal dan oudere gebeurtenissen. Dit volgnummer is handig als u regelmatig verbinding maakt met het apparaat en de verbinding verbreekt en ervoor wilt zorgen dat alleen de meest recente gebeurtenis wordt gebruikt om een downstreamactie te activeren.

Opmerking

In de volgende JSON ziet u een gebeurtenis van de verbindingsstatus van het apparaat die wordt gegenereerd wanneer een apparaat wordt verbroken.

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

Gebeurtenissen voor de levenscyclus van apparaten

Gebeurtenissen voor de levenscyclus van apparaten worden verzonden wanneer een apparaat of module wordt gemaakt of verwijderd uit het identiteitsregister. Zie meldingen over de levenscyclus van apparaten en modules voor meer informatie over wanneer gebeurtenissen voor de levenscyclus van apparaten worden gegenereerd.

Toepassingseigenschappen: In de volgende tabel ziet u hoe toepassingseigenschappen worden ingesteld voor levenscyclus-gebeurtenissen van apparaten:

Zowel modules als apparaten gebruiken de createDeviceIdentity en deleteDeviceIdentity toepassingseigenschappen om verbindingsstatus gebeurtenissen te rapporteren. Als de gebeurtenis afkomstig is van een module, bevat de gebeurtenis ook een moduleId eigenschap. Als er geen moduleId eigenschap is, is de gebeurtenis afkomstig van een apparaat.

Systeemeigenschappen: In de volgende tabel ziet u hoe systeemeigenschappen worden ingesteld voor levenscyclus-gebeurtenissen van apparaten:

Hoofdtekst: De hoofdtekst bevat een weergave van de apparaatdubbel of moduledubbel. Het bevat de apparaat-id en module-id, de tweeling-etag, de versie-eigenschap en de tags, eigenschappen en gekoppelde metagegevens van de dubbel.

Opmerking

In de volgende JSON ziet u een gebeurtenis voor de levenscyclus van apparaten die wordt gegenereerd wanneer een module wordt gemaakt. De gebeurtenis wordt vastgelegd met behulp van de az iot hub monitor-events Azure CLI-opdracht.

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

Wijzigingen van apparaatdubbels

Wijzigingsgebeurtenissen voor apparaatdubbels worden verzonden wanneer een apparaatdubbel of een moduledubbel wordt bijgewerkt of vervangen. In sommige gevallen kunnen verschillende wijzigingen in één gebeurtenis worden verpakt. Voor meer informatie, zie Back-endbewerkingen voor apparaat-tweelingen of Back-endbewerkingen voor module-tweelingen.

Toepassingseigenschappen: In de volgende tabel ziet u hoe toepassingseigenschappen worden ingesteld voor wijzigingsactiviteiten van apparaatdubbels:

Systeemeigenschappen: In de volgende tabel ziet u hoe systeemeigenschappen worden ingesteld voor wijzigingsactiviteiten van apparaatdubbels:

Hoofdtekst: Bij een update-gebeurtenis bevat de hoofdtekst de versie-eigenschap van de tweeling en de bijgewerkte tags en eigenschappen, samen met de bijbehorende metagegevens. Bij een vervangings gebeurtenis bevat de hoofdtekst de apparaat-id en module-id, de tweeling-etag, de versie-eigenschap en alle tags, eigenschappen en gekoppelde metagegevens van het apparaat of de moduledubbel.

Opmerking

In de volgende JSON ziet u een wijzigings gebeurtenis van een dubbel die is verzonden voor een update van een gewenste eigenschap en een tag op een moduledubbel. De gebeurtenis wordt vastgelegd met behulp van de az iot hub monitor-events Azure CLI-opdracht.

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

Volgende stappen

• Zie IoT Hub-berichtroutering gebruiken om apparaat-naar-cloud-berichten naar Azure-services te verzenden voor meer informatie over berichtroutering.

• Zie de syntaxis van ioT Hub-berichtroutering voor meer informatie over het toevoegen van query's aan uw berichtroutes.

• Zie IoT Hub-berichten maken en lezen voor meer informatie over de structuur van apparaat-naar-cloud- en cloud-naar-apparaat-berichten.