Rispondere agli eventi dell'hub IoT usando Griglia di eventi per attivare le azioni

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. 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. 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.

Griglia di eventi di Azure è un servizio di routing di eventi completamente gestito che usa un modello di pubblicazione-sottoscrizione. 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. Per un elenco completo dei gestori di eventi supportati da Griglia di eventi, vedere Introduzione a Griglia di eventi di Azure.

Per guardare un video che illustra questa integrazione, vedere integrazione hub IoT di Azure con Griglia di eventi di Azure.

Disponibilità a livello di area

L'integrazione di Griglia di eventi è disponibile per gli hub IoT situati nelle aree in cui Griglia di eventi è supportata. Per l'elenco più recente delle aree geografiche, vedere Prodotti disponibili in base all'area.

Tipi di evento

L'hub IoT pubblica i tipi di eventi seguenti:

Tipo di evento	Descrizione
Microsoft.Devices.DeviceCreated	Pubblicato quando viene registrato un dispositivo in un hub IoT.
Microsoft.Devices.DeviceDeleted	Pubblicato quando viene eliminato un dispositivo da un hub IoT.
Microsoft.Devices.DeviceConnected	Pubblicato quando un dispositivo si connette a un hub IoT.
Microsoft.Devices.DeviceDisconnected	Pubblicato quando un dispositivo si disconnette da un hub IoT.
Microsoft.Devices.DeviceTelemetry	Pubblicato quando viene inviato un messaggio di telemetria del dispositivo a un hub IoT

Usare il portale di Azure o l'interfaccia della riga di comando di Azure per configurare gli eventi da pubblicare da ogni hub IoT. 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).

Schema di eventi

Gli eventi dell'hub IoT contengono tutte le informazioni necessarie per rispondere alle modifiche del ciclo di vita del dispositivo. Per identificare un evento dell'hub IoT, controllare se la proprietà eventType inizia con 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.

Schema di dispositivo connesso

L'esempio seguente illustra lo schema di un evento di dispositivo connesso:

[{  
  "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 dispositivo

I messaggi di telemetria del dispositivo devono essere in un formato JSON valido con contentType impostato su application/json e contentEncoding impostato su UTF-8 nelle proprietà del sistema dei messaggi. Entrambe queste proprietà non fanno distinzione tra maiuscole e minuscole. Se la codifica del contenuto non è impostata, hub IoT scrive i messaggi in formato con codifica base 64.

È possibile arricchire gli eventi di telemetria dei dispositivi prima che vengano pubblicati in Griglia di eventi selezionando l'endpoint come Griglia di eventi. Per altre informazioni, vedere Arricchimenti dei messaggi.

L'esempio seguente illustra lo schema di un evento di telemetria del dispositivo:

[{  
  "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 dispositivo

L'esempio seguente illustra lo schema di un evento creato da un dispositivo:

[{
  "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 dei dispositivi gemelli associati a un evento di creazione del dispositivo sono una configurazione predefinita e non devono essere basati su per le proprietà effettive authenticationType e di altre proprietà del dispositivo in un dispositivo appena creato. Per authenticationType e altre proprietà del dispositivo in un dispositivo appena creato, usare l'API di gestione dei registri fornita negli SDK di Azure IoT.

Per una descrizione dettagliata di ogni proprietà, vedere Griglia di eventi di Azure schema di eventi per hub IoT.

Filtrare gli eventi

Griglia di eventi consente di filtrare in base a tipi di eventi, soggetti e contenuto dei dati. Durante la creazione della sottoscrizione di Griglia di eventi, è possibile scegliere di sottoscrivere eventi IoT selezionati.

• Tipo di evento: per l'elenco dei tipi di evento hub IoT, vedere Tipi di evento.
• Oggetto: per gli eventi hub IoT, l'oggetto è il nome del dispositivo. L'oggetto accetta il formato devices/{deviceId}. È possibile filtrare i soggetti in base alle corrispondenze Inizia con (prefisso) e Termina con (suffisso). 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.
• Contenuto dei dati: il contenuto dei dati viene popolato da hub IoT usando il formato del messaggio. È possibile scegliere quali eventi vengono recapitati in base al contenuto del messaggio di telemetria. Per esempi, vedere Filtro avanzato. Per filtrare il corpo del messaggio di telemetria, è necessario impostare contentType su application/json e contentEncoding su UTF-8 nelle proprietà del sistema dei messaggi. Entrambe queste proprietà non fanno distinzione tra maiuscole e minuscole.

Per gli eventi di telemetria del dispositivo, hub IoT creerà la route di messaggi predefinita denominata RouteToEventGrid in base alla sottoscrizione. Per filtrare i messaggi prima dell'invio dei dati di telemetria, aggiornare la query di routing.

Limitazioni per gli eventi di stato della connessione del dispositivo

Gli eventi connessi al dispositivo e disconnessi del dispositivo sono disponibili per i dispositivi che si connettono usando il protocollo MQTT o AMQP o usando uno di questi protocolli su WebSocket. Le richieste effettuate solo con HTTPS non attiveranno le notifiche sullo stato della connessione del dispositivo.

Per informazioni sul monitoraggio dello stato del dispositivo con Griglia di eventi, vedere Monitorare lo stato della connessione del dispositivo.

Intervallo di stato della connessione del dispositivo

hub IoT tenta di segnalare ogni evento di modifica dello stato della connessione del dispositivo, ma alcuni potrebbero non essere visualizzati. Almeno, hub IoT segnala gli eventi di modifica dello stato della connessione che si verificano 60 secondi l'uno dall'altro. Questo comportamento può portare a risultati come più eventi di connessione del dispositivo segnalati senza eventi di disconnessione del dispositivo tra di essi.

Suggerimenti per l'utilizzo di eventi

Le applicazioni che gestiscono gli eventi dell'hub IoT devono seguire queste procedure consigliate:

• È possibile configurare più sottoscrizioni per indirizzare gli eventi allo stesso gestore, quindi non presupporre che gli eventi provengano da un'origine particolare. Controllare sempre l'argomento del messaggio per assicurarsi che provenga dall'hub IoT previsto.
• Non presupporre che tutti gli eventi ricevuti siano del tipo previsto. Controllare sempre l'oggetto eventType prima di elaborare il messaggio.
• I messaggi possono arrivare non in ordine o dopo un ritardo. Usare il campo etag per capire se le informazioni sugli oggetti sono aggiornate per gli eventi creati dal dispositivo o eliminati dal dispositivo.

Passaggi successivi

• Informazioni sull'ordinamento di eventi di connessione e disconnessione dispositivi
• Compare the differences between routing IoT Hub events and messages (Confrontare le differenze tra il routing degli eventi dell'hub IoT e quello dei messaggi)
• Altre informazioni su come usare Griglia di eventi e Monitoraggio di Azure per monitorare, diagnosticare e risolvere i problemi di connettività dei dispositivi a hub IoT