hub IoT di Azure schemi di eventi non di telemetria

  • Articolo

Questo articolo fornisce le proprietà e gli schemi per gli eventi non di telemetria generati da 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 da 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 hub IoT, vedere hub IoT routing dei messaggi e React to hub IoT events by using Event Grid .To learn more about hub IoT message routing, see hub IoT message routing and React to hub IoT events by using Event Grid.

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

Tipi di evento disponibili

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 da hub IoT per ogni evento.

Proprietà Type Descrizione Parola chiave per la 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 di 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 da hub IoT per ogni evento.

Proprietà Type Descrizione
deviceId string ID del dispositivo.
hubName string Nome del 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 di stato Connessione ion

Connessione eventi di stato vengono generati ogni volta che un dispositivo o un modulo si connette o si disconnette dall'hub IoT.

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

Proprietà valore
iothub-message-schema device Connessione ionStateNotification
opType Uno dei valori seguenti: device Connessione ed, deviceDisconnected, module Connessione ed o moduleDisconnected.

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 device Connessione ionStateEvents

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 esadecimale, il numero sarà un numero 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 dell'interfaccia della az iot hub monitor-events 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 del dispositivo gemello 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 dell'interfaccia della az iot hub monitor-events 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 hub IoT routing dei messaggi.

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

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