Azure IoT Hub-händelsescheman som inte är telemetri

  • Artikel

Den här artikeln innehåller egenskaper och scheman för icke-telemetrihändelser som genereras av Azure IoT Hub. Icke-telemetrihändelser skiljer sig från enhets-till-moln- och moln-till-enhet-meddelanden eftersom de genereras direkt av IoT Hub som svar på specifika typer av tillståndsändringar som är associerade med dina enheter. Livscykeländringar som en enhet eller modul som skapas eller tas bort, eller anslutningstillstånd ändras till exempel en enhet eller modul som ansluter eller kopplar från.

Du kan dirigera icke-telemetrihändelser med hjälp av meddelanderoutning eller nå händelser som inte är telemetrihändelser med hjälp av Azure Event Grid. Mer information om IoT Hub-meddelanderoutning finns i IoT Hub-meddelanderoutning och React to IoT Hub events by using Event Grid (Reagera på IoT Hub-händelser med Event Grid).

Händelseexemplen i den här artikeln hämtades med hjälp av az iot hub monitor-events Azure CLI-kommandot. Du kan se en delmängd av egenskaper som ingår i händelserna som kommer till en slutpunkt för meddelanderoutning.

Tillgängliga händelsetyper

Azure IoT Hub genererar icke-telemetrihändelser i följande kategorier:

Händelsekategori beskrivning
Händelser för enhetsanslutningstillstånd Genereras när en enhet ansluter till eller kopplar från en IoT-hubb.
Händelser i enhetens livscykel Genereras när en enhet eller modul skapas på eller tas bort från en IoT-hubb.
Ändringshändelser för enhetstvillingar Genereras när en enhet eller modultvilling ändras eller ersätts.
Ändringshändelser för digitala tvillingar Genereras när en enhets eller moduls digitala tvilling ändras eller ersätts.

Vanliga händelseegenskaper

Icke-telemetrihändelser har flera vanliga egenskaper.

Systemegenskaper

Följande systemegenskaper anges av IoT Hub för varje händelse.

Property Type Beskrivning Nyckelord för routningsfråga
content-encoding sträng utf-8 $contentEncoding
innehållstyp sträng application/json $contentType
korrelations-ID sträng Ett unikt ID som identifierar händelsen. $correlationId
användar-ID sträng Namnet på IoT Hub som genererade händelsen. $userId
iothub-connection-device-id sträng Enhets-ID:t. $connectionDeviceId
iothub-connection-module-id sträng Modul-ID:t. Den här egenskapen är endast utdata för modulens livscykel och tvillinghändelser. $connectionModuleId
iothub-enqueuedtime Nummer Datum och tid då meddelandet skickades. I routningsfrågor använder du en ISO8601 tidsstämpel, till exempel $enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source sträng Händelsekategorin som identifierar meddelandekällan. Till exempel deviceLifecycleEvents. Ej tillämpligt

Egenskaper för program

Följande programegenskaper anges av IoT Hub för varje händelse.

Property Type Beskrivning
deviceId sträng Enhets-ID:t.
hubName sträng Namnet på den IoT Hub som genererade händelsen.
iothub-message-schema sträng Meddelandeschemat som är associerat med händelsekategorin. till exempel deviceLifecycleNotification.
moduleId sträng Modul-ID:t. Den här egenskapen är endast utdata för modulens livscykel och tvillingändringshändelser.
operationTimestamp sträng Åtgärdens ISO8601 tidsstämpel.
opType sträng Identifieraren för åtgärden som genererade händelsen. Till exempel createDeviceIdentity eller deleteDeviceIdentity.

Använd egenskapsnamnet i routningsfrågor. Exempel: deviceId = "my-device"

Anslut ionstillståndshändelser

Anslut ionstillståndshändelser genereras när en enhet eller modul ansluter eller kopplar från IoT-hubben.

Programegenskaper: I följande tabell visas hur programegenskaper anges för anslutningstillståndshändelser:

Property Värde
iothub-message-schema device Anslut ionStateNotification
opType Ett av följande värden: enhet Anslut ed, deviceDisconnected, module Anslut ed eller moduleDisconnected.

Systemegenskaper: Följande tabell visar hur systemegenskaper anges för anslutningstillståndshändelser:

Property Värde
iothub-message-source device Anslut ionStateEvents

Brödtext: Brödtexten innehåller ett sekvensnummer. Sekvensnumret är en strängrepresentation av ett hexadecimalt tal. Du kan använda strängjäxning för att identifiera det större talet. Om du konverterar strängen till hex blir talet ett 256-bitars tal. Sekvensnumret ökar strikt och den senaste händelsen har ett högre antal än andra händelser. Detta är användbart om du har frekventa enhetsanslutningar och frånkopplingar och vill se till att endast den senaste händelsen används för att utlösa en nedströmsåtgärd.

Exempel

Följande JSON visar en händelse för enhetsanslutningstillstånd som genereras när en enhet kopplas från.

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

Händelser i enhetens livscykel

Händelser i enhetens livscykel genereras när en enhet eller modul skapas eller tas bort från identitetsregistret. Mer information om när enhetens livscykelhändelser genereras finns i Meddelanden om enhets- och modullivscykel.

Programegenskaper: I följande tabell visas hur programegenskaper anges för enhetens livscykelhändelser:

Property Värde
iothub-message-schema deviceLifecycleNotification
opType Ett av följande värden: createDeviceIdentity, deleteDeviceIdentity, createModuleIdentity eller deleteModuleIdentity.

Systemegenskaper: Följande tabell visar hur systemegenskaper anges för enhetens livscykelhändelser:

Property Värde
iothub-message-source deviceLifecycleEvents

Brödtext: Brödtexten innehåller en representation av enhetstvillingen eller modultvillingen. Den innehåller enhets-ID och modul-ID, tvillingetaggenskapen, versionsegenskapen och taggarna, egenskaperna och tillhörande metadata för tvillingen.

Exempel

Följande JSON visar en enhetslivscykelhändelse som genereras när en modul skapas. Händelsen registreras med hjälp av az iot hub monitor-events Azure CLI-kommandot.

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

Ändringshändelser för enhetstvillingar

Ändringshändelser för enhetstvillingar genereras när en enhetstvilling eller en modultvilling uppdateras eller ersätts. I vissa fall kan flera ändringar paketeras i en enda händelse. Mer information finns i Säkerhetskopieringsåtgärder för enhetstvillingar eller Serverdelsåtgärder för modultvillingar.

Programegenskaper: I följande tabell visas hur programegenskaper anges för enhetstvillingens ändringshändelser:

Property Värde
iothub-message-schema twinChangeNotification
opType Ett av följande värden: replaceTwin eller updateTwin.

Systemegenskaper: Följande tabell visar hur systemegenskaper anges för enhetstvillingens ändringshändelser:

Property Värde
iothub-message-source twinChangeEvents

Brödtext: Vid en uppdatering innehåller brödtexten versionsegenskapen för tvillingen och de uppdaterade taggarna och egenskaperna samt tillhörande metadata. Vid en ersättning innehåller brödtexten enhets-ID och modul-ID, tvillingetaggenskapen, versionsegenskapen och alla taggar, egenskaper och associerade metadata för enheten eller modultvillingen.

Exempel

Följande JSON visar en tvillingändringshändelse som genereras för en uppdatering av en önskad egenskap och en tagg på en modultvilling. Händelsen registreras med hjälp av az iot hub monitor-events Azure CLI-kommandot.

{
    "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ästa steg