Rispondere agli eventi dell'hub IoT usando Griglia di eventi per attivare le azioniReact to IoT Hub events by using Event Grid to trigger actions

L'hub IoT di Azure si integra con Griglia di eventi di Azure per consentire l'invio di notifiche degli eventi ad altri servizi e attivare processi downstream.Azure IoT Hub integrates with Azure Event Grid so that you can send event notifications to other services and trigger downstream processes. Configurare le applicazioni aziendali per l'ascolto degli eventi dell'hub IoT in modo da poter reagire a eventi critici in modo affidabile, scalabile e sicuro.Configure your business applications to listen for IoT Hub events so that you can react to critical events in a reliable, scalable, and secure manner.Creare ad esempio un'applicazione che aggiorna un database, crea un ticket di lavoro e recapita una notifica di posta elettronica ogni volta che viene registrato un nuovo dispositivo IoT nell'hub IoT. For example, build an application that updates a database, creates a work ticket, and delivers an email notification every time a new IoT device is registered to your IoT hub.

Griglia di eventi di Azure è un servizio di routing di eventi completamente gestito che usa un modello di pubblicazione-sottoscrizione.Azure Event Grid is a fully managed event routing service that uses a publish-subscribe model. Griglia di eventi include il supporto predefinito per i servizi di Azure, ad esempio Funzioni di Azure e App per la logica di Azure, e può recapitare gli avvisi relativi agli eventi ai servizi non di Azure usando i webhook.Event Grid has built-in support for Azure services like Azure Functions and Azure Logic Apps, and can deliver event alerts to non-Azure services using webhooks. Per un elenco completo dei gestori di eventi supportati da Griglia di eventi, vedere Introduzione a Griglia di eventi di Azure.For a complete list of the event handlers that Event Grid supports, see An introduction to Azure Event Grid.

Architettura di Griglia di eventi di Azure

Disponibilità a livello di areaRegional availability

L'integrazione di Griglia di eventi è disponibile per gli hub IoT situati nelle aree in cui Griglia di eventi è supportata.The Event Grid integration is available for IoT hubs located in the regions where Event Grid is supported. Per l'elenco aggiornato delle aree, vedere Introduzione a Griglia di eventi di Azure.For the latest list of regions, see An introduction to Azure Event Grid.

Tipi di eventiEvent types

L'hub IoT pubblica i tipi di eventi seguenti:IoT Hub publishes the following event types:

Tipo di eventoEvent type DescrizioneDescription
Microsoft.Devices.DeviceCreatedMicrosoft.Devices.DeviceCreated Pubblicato quando un dispositivo viene registrato in un hub IoT.Published when a device is registered to an IoT hub.
Microsoft.Devices.DeviceDeletedMicrosoft.Devices.DeviceDeleted Pubblicato quando un dispositivo viene eliminato da un hub IoT.Published when a device is deleted from an IoT hub.
Microsoft.Devices.DeviceConnectedMicrosoft.Devices.DeviceConnected Pubblicato quando un dispositivo è connesso a un hub IoT.Published when a device is connected to an IoT hub.
Microsoft.Devices.DeviceDisconnectedMicrosoft.Devices.DeviceDisconnected Pubblicato quando un dispositivo è disconnesso da un hub IoT.Published when a device is disconnected from an IoT hub.
Microsoft.Devices.DeviceTelemetryMicrosoft.Devices.DeviceTelemetry Pubblicato quando viene inviato un messaggio di telemetria del dispositivo a un hub IoTPublished when a device telemetry message is sent to an IoT hub

Usare il portale di Azure o l'interfaccia della riga di comando di Azure per configurare gli eventi da pubblicare da ogni hub IoT.Use either the Azure portal or Azure CLI to configure which events to publish from each IoT hub. Per un esempio, provare l'esercitazione Send email notifications about Azure IoT Hub events using Logic Apps (Inviare notifiche di posta elettronica sugli eventi dell'hub IoT di Azure usando App per la logica).For an example, try the tutorial Send email notifications about Azure IoT Hub events using Logic Apps.

Schema di eventiEvent schema

Gli eventi dell'hub IoT contengono tutte le informazioni necessarie per rispondere alle modifiche del ciclo di vita del dispositivo.IoT Hub events contain all the information you need to respond to changes in your device lifecycle. È possibile identificare un evento dell'hub IoT controllando che la proprietà eventType inizi con Microsoft.Devices.You can identify an IoT Hub event by checking that the eventType property starts with Microsoft.Devices. Per altre informazioni su come usare le proprietà degli eventi di Griglia di eventi, vedere lo schema di eventi di Griglia di eventi.For more information about how to use Event Grid event properties, see the Event Grid event schema.

Schema di dispositivo connessoDevice connected schema

L'esempio seguente illustra lo schema di un evento di dispositivo connesso:The following example shows the schema of a device connected event:

[{  
  "id": "f6bbf8f4-d365-520d-a878-17bf7238abd8",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceConnected",
  "eventTime": "2018-06-02T19:17:44.4383997Z",
  "data": {
      "deviceConnectionStateEventInfo": {
        "sequenceNumber":
          "000000000000000001D4132452F67CE200000002000000000000000000000001"
      },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice",
    "moduleId" : "DeviceModuleID",
  }, 
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Schema di telemetria del dispositivoDevice Telemetry schema

Il messaggio di telemetria del dispositivo deve essere in un formato JSON valido con contentType impostato su Application/JSON e ContentEncoding impostato su UTF-8 nelle proprietà del sistemadel messaggio.Device telemetry message must be in a valid JSON format with the contentType set to application/json and contentEncoding set to UTF-8 in the message system properties. Entrambe le proprietà non fanno distinzione tra maiuscole e minuscole.Both of these properties are case insensitive. Se la codifica del contenuto non è impostata, l'hub Internet scriverà i messaggi nel formato con codifica base 64.If the content encoding is not set, then IoT Hub will write the messages in base 64 encoded format.

È possibile arricchire gli eventi di telemetria del dispositivo prima che vengano pubblicati in griglia di eventi selezionando l'endpoint come griglia di eventi.You can enrich device telemetry events before they are published to Event Grid by selecting the endpoint as Event Grid. Per ulteriori informazioni, vedere Cenni preliminari sugli arricchimenti dei messaggi.For more information, see Message Enrichments Overview.

L'esempio seguente illustra lo schema di un evento di telemetria del dispositivo:The following example shows the schema of a device telemetry event:

[{  
  "id": "9af86784-8d40-fe2g-8b2a-bab65e106785",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceTelemetry",
  "eventTime": "2019-01-07T20:58:30.48Z",
  "data": {
      "body": {
          "Weather": {
              "Temperature": 900
            },
            "Location": "USA"
        },
        "properties": {
            "Status": "Active"
        },
        "systemProperties": {
          "iothub-content-type": "application/json",
          "iothub-content-encoding": "utf-8",
          "iothub-connection-device-id": "d1",
          "iothub-connection-auth-method": "{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
          "iothub-connection-auth-generation-id": "123455432199234570",
          "iothub-enqueuedtime": "2019-01-07T20:58:30.48Z",
          "iothub-message-source": "Telemetry"
        }
  },
  "dataVersion": "",
  "metadataVersion": "1"
}]

Schema creato da un dispositivoDevice created schema

L'esempio seguente illustra lo schema di un evento creato da un dispositivo:The following example shows the schema of a device created event:

[{
  "id": "56afc886-767b-d359-d59e-0da7877166b2",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceCreated",
  "eventTime": "2018-01-02T19:17:44.4383997Z",
  "data": {
    "twin": {
      "deviceId": "LogicAppTestDevice",
      "etag": "AAAAAAAAAAE=",
      "deviceEtag":"null",
      "status": "enabled",
      "statusUpdateTime": "0001-01-01T00:00:00",
      "connectionState": "Disconnected",
      "lastActivityTime": "0001-01-01T00:00:00",
      "cloudToDeviceMessageCount": 0,
      "authenticationType": "sas",
      "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
      },
      "version": 2,
      "properties": {
        "desired": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        },
        "reported": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        }
      }
    },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice"
  },
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Avviso

I dati gemelli associati a un evento di creazione del dispositivo sono una configurazione predefinita e non devono essere considerati per authenticationType le proprietà effettive e altre periferiche in un dispositivo appena creato.Twin data associated with a device creation event is a default configuration and shouldn't be relied on for actual authenticationType and other device properties in a newly created device. Per authenticationType e altre proprietà del dispositivo in un nuovo dispositivo creato, usare l'API Register Manager fornita negli SDK Azure.For authenticationType and other device properties in a newly created device, use the Register Manager API provided in Azure IoT SDKs.

Per una descrizione dettagliata di ogni proprietà, vedere schema di eventi di griglia di eventi di Azure per l'hubInternet.For a detailed description of each property, see Azure Event Grid event schema for IoT Hub.

Filtrare gli eventiFilter events

Le sottoscrizioni degli eventi dell'hub Internet possono filtrare gli eventi in base al tipo di evento, al contenuto dei dati e al soggetto, ovvero il nome del dispositivo.IoT Hub event subscriptions can filter events based on event type, data content and subject, which is the device name.

Griglia di eventi consente di filtrare i tipi di eventi, gli oggetti e il contenuto dei dati.Event Grid enables filtering on event types, subjects and data content. Durante la creazione della sottoscrizione di griglia di eventi, è possibile scegliere di sottoscrivere gli eventi di un sacco selezionato.While creating the Event Grid subscription, you can choose to subscribe to selected IoT events. I filtri degli oggetti in Griglia di eventi funzionano in base alle corrispondenze Inizia con (prefisso) e Termina con (suffisso).Subject filters in Event Grid work based on Begins With (prefix) and Ends With (suffix) matches. Il filtro utilizza un AND operatore in modo che gli eventi con un oggetto che corrisponde sia al prefisso che al suffisso viene recapitato al sottoscrittore.The filter uses an AND operator, so events with a subject that match both the prefix and suffix are delivered to the subscriber.

L'oggetto di eventi IoT usa il formato:The subject of IoT Events uses the format:

devices/{deviceId}

Griglia di eventi consente inoltre di filtrare gli attributi di ogni evento, incluso il contenuto dei dati.Event Grid also allows for filtering on attributes of each event, including the data content. In questo modo è possibile scegliere quali eventi vengono recapitati in base al contenuto del messaggio di telemetria.This allows you to choose what events are delivered based contents of the telemetry message. Per visualizzare esempi, vedere filtro avanzato .Please see advanced filtering to view examples. Per filtrare il corpo del messaggio di telemetria, è necessario impostare contentType su Application/JSON e ContentEncoding su UTF-8 nelle proprietà del sistemadel messaggio.For filtering on the telemetry message body, you must set the contentType to application/json and contentEncoding to UTF-8 in the message system properties. Entrambe le proprietà non fanno distinzione tra maiuscole e minuscole.Both of these properties are case insensitive.

Per gli eventi non di telemetria come DeviceConnected, DeviceDisconnected, DeviceCreated e DeviceDeleted, è possibile usare il filtro di griglia di eventi durante la creazione della sottoscrizione.For non-telemetry events like DeviceConnected, DeviceDisconnected, DeviceCreated and DeviceDeleted, the Event Grid filtering can be used when creating the subscription. Per gli eventi di telemetria, oltre al filtro in griglia di eventi, gli utenti possono anche filtrare in dispositivi gemelli, proprietà e corpo del messaggio tramite la query di routing dei messaggi.For telemetry events, in addition to the filtering in Event Grid, users can also filter on device twins, message properties and body through the message routing query.

Quando si effettua la sottoscrizione agli eventi di telemetria tramite griglia di eventi, l'hub Internet crea una route di messaggio predefinita per inviare i messaggi del dispositivo di tipo origine dati a griglia di eventi.When you subscribe to telemetry events via Event Grid, IoT Hub creates a default message route to send data source type device messages to Event Grid. Per ulteriori informazioni sul routing dei messaggi, vedere il routing dei messaggi dell'hubInternet.For more information about message routing, see IoT Hub message routing. Questa route sarà visibile nel portale nell'hub degli indirizzi Internet > il routing dei messaggi.This route will be visible in the portal under IoT Hub > Message Routing. Viene creata una sola route per griglia di eventi indipendentemente dal numero di sottoscrizioni ad esempio create per gli eventi di telemetria.Only one route to Event Grid is created regardless of the number of EG subscriptions created for telemetry events. Quindi, se sono necessarie più sottoscrizioni con filtri diversi, è possibile usare l'operatore OR in queste query sulla stessa route.So, if you need several subscriptions with different filters, you can use the OR operator in these queries on the same route. La creazione e l'eliminazione della route vengono controllate tramite la sottoscrizione di eventi di telemetria tramite griglia di eventi.The creation and deletion of the route is controlled through subscription of telemetry events via Event Grid. Non è possibile creare o eliminare una route a griglia di eventi usando il routing del messaggio dell'hub Internet.You cannot create or delete a route to Event Grid using IoT Hub Message Routing.

Per filtrare i messaggi prima dell'invio dei dati di telemetria, è possibile aggiornare la query di routing.To filter messages before telemetry data is sent, you can update your routing query. Si noti che la query di routing può essere applicata al corpo del messaggio solo se il corpo è JSON.Note that routing query can be applied to the message body only if the body is JSON. È inoltre necessario impostare contentType su Application/JSON e ContentEncoding su UTF-8 nelle proprietà del sistemadel messaggio.You must also set the contentType to application/json and contentEncoding to UTF-8 in the message system properties.

Limitazioni per gli eventi correlati a dispositivi connessi e disconnessiLimitations for device connected and device disconnected events

Per ricevere gli eventi dello stato di connessione del dispositivo, un dispositivo deve eseguire un'operazione di invio dei dati di telemetria di tipo ' 2C ' o ' C2D Receive message ' con l'hub Internet.To receive device connection state events, a device must do either a 'D2C Send Telemetry' OR a 'C2D Receive Message' operation with Iot Hub. Si noti tuttavia che se un dispositivo usa il protocollo AMQP per connettersi all'hub Internet, è consigliabile eseguire un'operazione di "messaggio di ricezione C2D", altrimenti le notifiche dello stato di connessione potrebbero essere ritardate di pochi minuti.However, note that if a device is using AMQP protocol to connect with Iot Hub, it is recommended that they do a 'C2D Receive Message' operation otherwise their connection state notifications may be delayed by few minutes. Se il dispositivo usa il protocollo MQTT, l'hub IoT mantiene aperto il collegamento C2D.If your device is using MQTT protocol, IoT Hub will keep the C2D link open. Per AMQP, è possibile aprire il collegamento C2D chiamando l'API asincrona Receive per l'SDK per C# o il client del dispositivo per AMQP.For AMQP, you can open the C2D link by calling the Receive Async API for IoT Hub C# SDK, or device client for AMQP.

Il collegamento D2C è aperto se si inviano dati di telemetria.The D2C link is open if you are sending telemetry.

Se la connessione del dispositivo è tremolante, il che significa che il dispositivo si connette e si disconnette di frequente, non verrà inviato ogni singolo stato di connessione, ma lo stato della connessione corrente verrà pubblicato in uno snapshot periodico finché lo sfarfallio continuerà.If the device connection is flickering, which means the device connects and disconnects frequently, we will not send every single connection state, but will publish the current connection state taken at a periodic snapshot, till the flickering continues. La ricezione dello stesso evento dello stato di connessione con numeri di sequenza diversi o eventi di stato della connessione diversi significa che è stata apportata una modifica allo stato di connessione del dispositivo.Receiving either the same connection state event with different sequence numbers or different connection state events both mean that there was a change in the device connection state.

Suggerimenti per l'utilizzo di eventiTips for consuming events

Le applicazioni che gestiscono gli eventi dell'hub IoT devono seguire queste procedure consigliate:Applications that handle IoT Hub events should follow these suggested practices:

  • È possibile configurare più sottoscrizioni per indirizzare gli eventi allo stesso gestore, quindi non presupporre che gli eventi provengano da un'origine particolare.Multiple subscriptions can be configured to route events to the same event handler, so don't assume that events are from a particular source. Controllare sempre l'argomento del messaggio per assicurarsi che provenga dall'hub IoT previsto.Always check the message topic to ensure that it comes from the IoT hub that you expect.

  • Non presupporre che tutti gli eventi ricevuti siano del tipo previsto.Don't assume that all events you receive are the types that you expect. Controllare sempre eventType prima di elaborare il messaggio.Always check the eventType before processing the message.

  • I messaggi possono arrivare non in ordine o dopo un ritardo.Messages can arrive out of order or after a delay. Usare il campo ETag per capire se le informazioni sugli oggetti sono aggiornate per gli eventi creati dal dispositivo o eliminati dal dispositivo.Use the etag field to understand if your information about objects is up-to-date for device created or device deleted events.

Passaggi successiviNext steps