Schemi di eventi non di telemetria dell'hub IoT di Azure

Questo articolo fornisce le proprietà e gli schemi per gli eventi non di telemetria generati dall'hub IoT di Azure. Gli eventi non di telemetria sono diversi dai messaggi da dispositivo a cloud e da cloud a dispositivo in che hub IoT genera questi eventi in risposta a modifiche di stato specifiche associate ai dispositivi. Ad esempio, le modifiche del ciclo di vita come un dispositivo o un modulo creato o eliminato, o lo stato della connessione cambia come un dispositivo o un modulo che si connette o si disconnette.

È possibile instradare eventi non di telemetria usando il routing dei messaggi o raggiungere eventi non di telemetria usando Griglia di eventi di Azure. Per altre informazioni sul routing dei messaggi dell'hub IoT, vedere Routing dei messaggi dell'hub IoT e Reagire agli eventi dell'hub IoT tramite Griglia di eventi.

Gli esempi di eventi in questo articolo sono stati acquisiti usando il comando dell'interfaccia della riga di comando di Azure az iot hub monitor-events. È possibile che venga visualizzato un subset di proprietà incluse negli eventi che arrivano a un endpoint di routing dei messaggi.

Tipi di evento disponibili

L'hub IoT di Azure genera gli eventi non di telemetria nelle categorie seguenti:

Proprietà dell'evento comune

Gli eventi non di telemetria condividono diverse proprietà comuni.

Proprietà di sistema

hub IoT imposta le proprietà di sistema seguenti per ogni evento.

Proprietà dell'applicazione

hub IoT imposta le proprietà dell'applicazione seguenti per ogni evento.

Nelle query di routing usare il nome della proprietà. Ad esempio: deviceId = "my-device".

Eventi dello stato della connessione

Gli eventi dello stato della connessione vengono generati ogni volta che un dispositivo o un modulo si connette o si disconnette dall'hub IoT.

Proprietà dell'applicazione: la tabella seguente illustra come vengono impostate le proprietà dell'applicazione per gli eventi di stato della connessione:

I moduli e i dispositivi usano le deviceConnected proprietà dell'applicazione e deviceDisconnected per segnalare gli eventi di stato della connessione. Se l'evento proviene da un modulo, l'evento include anche una moduleId proprietà . Se non è presente alcuna moduleId proprietà, l'evento proviene da un dispositivo.

Proprietà di sistema: nella tabella seguente viene illustrato come vengono impostate le proprietà di sistema per gli eventi di stato della connessione:

Corpo: il corpo contiene un numero di sequenza. Il numero di sequenza è una rappresentazione in formato stringa di un numero esadecimale. È possibile usare il confronto tra stringhe per identificare il numero maggiore. Se si converte la stringa in formato esadecimale, il numero sarà a 256 bit. Il numero di sequenza è strettamente crescente, quindi l'evento più recente ha un numero maggiore rispetto agli eventi precedenti. Ciò è utile se il dispositivo si connette e si disconnette frequentemente e si vuole assicurarsi che venga usato solo l'evento più recente per attivare un'azione downstream.

Esempio

Il codice JSON seguente mostra un evento di stato della connessione del dispositivo generato quando un dispositivo si disconnette.

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

Eventi relativi al ciclo di vita del dispositivo

Gli eventi del ciclo di vita del dispositivo vengono generati ogni volta che un dispositivo o un modulo viene creato o eliminato dal registro delle identità. Per altri dettagli sui casi in cui vengono generati gli eventi del ciclo di vita del dispositivo, vedere Notifiche relative al ciclo di vita dei dispositivi e dei moduli.

Proprietà dell'applicazione: nella tabella seguente viene illustrato come vengono impostate le proprietà dell'applicazione per gli eventi del ciclo di vita del dispositivo:

I moduli e i dispositivi usano le createDeviceIdentity proprietà dell'applicazione e deleteDeviceIdentity per segnalare gli eventi di stato della connessione. Se l'evento proviene da un modulo, l'evento include anche una moduleId proprietà . Se non è presente alcuna moduleId proprietà, l'evento proviene da un dispositivo.

Proprietà di sistema: nella tabella seguente viene illustrato come vengono impostate le proprietà di sistema per gli eventi del ciclo di vita del dispositivo:

Corpo: il corpo contiene una rappresentazione del dispositivo gemello o del modulo gemello. Include l'ID dispositivo e l'ID del modulo, l'etag del gemello, la proprietà della versione e i tag, le proprietà e i metadati associati del gemello.

Esempio

Il codice JSON seguente mostra un evento del ciclo di vita del dispositivo generato quando viene creato un modulo. L'evento viene acquisito usando il comando az iot hub monitor-events dell'interfaccia della riga di comando di 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
                }
            }
        }
    }
}

Eventi di modifica del dispositivo gemello

Gli eventi di modifica del dispositivo gemello vengono generati ogni volta che un dispositivo gemello o un modulo gemello viene aggiornato o sostituito. In alcuni casi, è possibile creare un pacchetto di diverse modifiche in un singolo evento. Per altre informazioni, vedere operazioni back-end di dispositivi gemelli o operazioni back-end del modulo gemello.

Proprietà dell'applicazione: nella tabella seguente viene illustrato come vengono impostate le proprietà dell'applicazione per gli eventi di modifica dei dispositivi gemelli:

Proprietà di sistema: nella tabella seguente viene illustrato come vengono impostate le proprietà di sistema per gli eventi di modifica dei dispositivi gemelli:

Corpo: in un aggiornamento, il corpo contiene la proprietà version del gemello e i tag e le proprietà aggiornati e i relativi metadati associati. In una sostituzione, il corpo contiene l'ID dispositivo e l'ID del modulo, l'etag gemello, la proprietà della versione e tutti i tag, le proprietà e i metadati associati del dispositivo o del modulo gemello.

Esempio

Il codice JSON seguente mostra un evento di modifica del gemello generato per un aggiornamento di una proprietà desiderata e un tag in un modulo gemello. L'evento viene acquisito usando il comando az iot hub monitor-events dell'interfaccia della riga di comando di 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
                }
            }
        }
    }
}

Passaggi successivi

• Per informazioni sul routing dei messaggi, vedere routing dei messaggi dell'hub IoT.

• Per informazioni su come aggiungere query alle route dei messaggi, vedere Sintassi delle query di routing dei messaggi dell'hub IoT.

• Per informazioni sulla struttura dei messaggi da dispositivo a cloud e da cloud a dispositivo, vedere Creare e leggere i messaggi dell'hub IoT.