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

  • Articolo

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 quanto vengono generati direttamente dall'hub IoT in risposta a tipi specifici di modifiche dello stato 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:

Categoria evento Descrizione
Eventi dello stato della connessione del dispositivo Generato quando un dispositivo si connette o si disconnette da un hub IoT.
Eventi relativi al ciclo di vita del dispositivo Generato quando un dispositivo o un modulo viene creato o eliminato da un hub IoT.
Eventi di modifica del dispositivo gemello Generato quando un dispositivo o un modulo gemello viene modificato o sostituito.
Eventi di modifica del gemello digitale Generato quando un dispositivo o un modulo gemello digitale viene modificato o sostituito.

Proprietà dell'evento comune

Gli eventi non di telemetria condividono diverse proprietà comuni.

Proprietà di sistema

Le proprietà di sistema seguenti vengono impostate dall'hub IoT in ogni evento.

Proprietà Type Descrizione Parola chiave per query di routing
content-encoding string utf-8 $contentEncoding
content-type string application/json $contentType
correlation-id string ID univoco che identifica l'evento. $correlationId
user-id string Nome dell'hub IoT che ha generato l'evento. $userId
iothub-connection-device-id string ID del dispositivo. $connectionDeviceId
iothub-connection-module-id string ID modulo. Questa proprietà viene restituita solo per gli eventi del ciclo di vita del modulo e dei dispositivi gemelli. $connectionModuleId
iothub-enqueuedtime number Data e ora in cui è stata inviata la notifica. Nelle query di routing usare un timestamp ISO8601; ad esempio, $enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source string Categoria di eventi che identifica l'origine del messaggio. Ad esempio, deviceLifecycleEvents. N/D

Proprietà dell'applicazione

Le proprietà dell'applicazione seguenti vengono impostate dall'hub IoT in ogni evento.

Proprietà Type Descrizione
deviceId string ID del dispositivo.
hubName string Nome dell'hub IoT che ha generato l'evento.
iothub-message-schema string Schema del messaggio associato alla categoria di eventi; ad esempio deviceLifecycleNotification.
moduleId string ID modulo. Questa proprietà viene restituita solo per gli eventi relativi al ciclo di vita del modulo e alla modifica del gemello.
operationTimestamp string Timestamp ISO8601 dell'operazione.
opType string Identificatore dell'operazione che ha generato l'evento. Ad esempio, createDeviceIdentity o deleteDeviceIdentity.

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:

Proprietà valore
iothub-message-schema deviceConnectionStateNotification
opType deviceConnected o deviceDisconnected

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

Proprietà valore
iothub-message-source deviceConnectionStateEvents

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 è sempre in aumento e all'evento più recente viene associato un numero superiore rispetto a quello di altri eventi. 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": "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"
        }
    }
}

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:

Proprietà valore
iothub-message-schema deviceLifecycleNotification
opType Uno dei valori seguenti: createDeviceIdentity, deleteDeviceIdentity, createModuleIdentity o deleteModuleIdentity.

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

Proprietà valore
iothub-message-source deviceLifecycleEvents

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

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à valore
iothub-message-schema twinChangeNotification
opType Uno dei valori seguenti: replaceTwin o updateTwin.

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

Proprietà valore
iothub-message-source twinChangeEvents

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