Esportare i dati IoT nel webhook

Questo articolo descrive come configurare l'esportazione dei dati per l'invio di dati al webhook.

Usare questa funzionalità per esportare continuamente i dati IoT filtrati e arricchiti dall'applicazione IoT Central. L'esportazione dei dati esegue il push delle modifiche ad altre parti della soluzione cloud in tempo quasi reale per informazioni dettagliate, analisi e archiviazione a caldo.

È ad esempio possibile:

• Esportare continuamente i dati di telemetria, le modifiche alle proprietà, la connettività dei dispositivi, il ciclo di vita del dispositivo, il ciclo di vita del modello di dispositivo e i dati del log di controllo in formato JSON quasi in tempo reale.
• Filtrare i flussi di dati per esportare i dati che corrispondono alle condizioni personalizzate.
• Arricchire i flussi di dati con valori personalizzati e i valori delle proprietà del dispositivo.
• Trasformare i flussi di dati per modificarne la forma e il contenuto.

Suggerimento

Quando si attiva l'esportazione dei dati, si ottengono solo i dati da quel momento in poi. Per conservare più dati cronologici, attivare l'esportazione dei dati in anticipo. Per esportare manualmente i dati da orari in cui l'esportazione dei dati è stata disattivata, vedere Come usare l'API REST di IoT Central per eseguire query sui dispositivi.

Nota

In alcuni casi potrebbero essere necessari fino a 60 secondi per l'esportazione dei messaggi. Questo tempo viene misurato da quando IoT Central riceve il messaggio dall'hub IoT sottostante a quando il messaggio viene recapitato all'endpoint di destinazione.

Prerequisiti

Per usare le funzionalità di esportazione dei dati, è necessario disporre dell'autorizzazione Esportazione dati.

Configurare una destinazione di esportazione webhook

Per le destinazioni webhook, IoT Central esporta i dati quasi in tempo reale. I dati nel corpo del messaggio sono nello stesso formato di Hub eventi e bus di servizio.

Creare una destinazione webhook

È possibile esportare i dati in un endpoint webhook HTTP disponibile pubblicamente. È possibile creare un endpoint webhook di test usando RequestBin. RequestBin limita la richiesta quando viene raggiunto il limite di richieste:

1. Passare a RequestBin.

2. Selezionare Create a RequestBin (Crea un elemento RequestBin).

3. Accedere con uno dei metodi disponibili.

4. Copiare l'URL di RequestBin Usare questo URL quando si testa l'esportazione dei dati.

Per creare la destinazione di Azure Esplora dati in IoT Central nella pagina Esportazione dati:

1. Selezionare + Nuova destinazione.

2. Selezionare Webhook come tipo di destinazione.

3. Incollare l'URL di callback per l'endpoint del webhook. Facoltativamente, è possibile configurare l'autorizzazione webhook e aggiungere intestazioni personalizzate.

   • Per OAuth2.0 è supportato solo il flusso di concessione delle credenziali client. Quando si salva la destinazione, IoT Central comunica con il provider OAuth per recuperare un token di autorizzazione. Questo token è associato all'intestazione Authorization per ogni messaggio inviato a questa destinazione.
   • Per Token di autorizzazione, è possibile specificare un valore del token collegato direttamente all'intestazione Authorization per ogni messaggio inviato a questa destinazione.

4. Seleziona Salva.

Esempio di configurazione di OAuth 2.0

Questo esempio illustra come configurare una destinazione webhook per l'uso di un'app per le funzioni di Azure protetta tramite l'accesso a Microsoft Entra:

Impostazione	Esempio	Note
Tipo destinazione	Webhook
Callback URL (URL callback)	https://myapp.azurewebsites.net/api/HttpExample	URL della funzione.
Autorizzazione	OAuth 2.0
URL token	https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token	URL da usare per recuperare un token. Questo valore è disponibile nell'app per le > funzioni: autenticazione > endpoint del provider di > identità Microsoft OAuth 2.0 (v2)
Client ID	your-client-id	ID client dell'app per le funzioni. È possibile trovare questo valore nell'app per le funzioni: Autenticazione dell'ID > applicazione del provider di > identità Microsoft (client)
Segreto client	your-client-secret	Segreto client dell'app per le funzioni. È possibile trovare questo valore nell'app per le funzioni: Autenticazione > certificati e segreti del provider di > identità Microsoft
Destinatari	N/D	Vuoto se si usa un'app per le funzioni.
Ambito	https://your-client-id/.default	Ambito del token. Per un'app per le funzioni, usare il valore ID client.**
Tipo di contenuto della richiesta di token	Auto

Altre destinazioni webhook potrebbero richiedere valori diversi per queste impostazioni.

Configurare un'esportazione dei dati

Ora che è disponibile una destinazione in cui esportare i dati, configurare l'esportazione dei dati nell'applicazione IoT Central:

1. Accedere all'applicazione IoT Central.

2. Nel riquadro sinistro selezionare Esportazione dati.

   Suggerimento

   Se nel riquadro sinistro non viene visualizzata l'esportazione dei dati, non si dispone delle autorizzazioni per configurare l'esportazione dei dati nell'app. Chiedere a un amministratore di configurare l'esportazione dei dati.

3. Selezionare + Nuova esportazione.

4. Immettere un nome visualizzato per la nuova esportazione e assicurarsi che l'esportazione dei dati sia Abilitata.

5. Scegliere il tipo di dati da esportare. Nella tabella seguente sono elencati i tipi di esportazione dei dati supportati:

   Tipo di dati	Descrizione	Formato dati
   Telemetria	Esportare i messaggi di telemetria dai dispositivi quasi in tempo reale. Ogni messaggio esportato contiene il contenuto completo del messaggio originale del dispositivo normalizzato.	Formato messaggio di telemetria
   Modifiche alle proprietà	Esportare le modifiche alle proprietà del dispositivo e del cloud quasi in tempo reale. Per le proprietà del dispositivo di sola lettura, le modifiche apportate ai valori segnalati vengono esportate. Per le proprietà di lettura/scrittura, vengono esportati sia i valori segnalati che i valori desiderati.	Formato del messaggio di modifica della proprietà
   Connettività dei dispositivi	Esportare gli eventi connessi e disconnessi del dispositivo.	Formato del messaggio di connettività del dispositivo
   Ciclo di vita dei dispositivi	Esportare il dispositivo registrato, eliminato, sottoposto a provisioning, abilitato, disabilitato, displayNameChanged e gli eventi deviceTemplateChanged.	Il formato del messaggio cambia il ciclo di vita del dispositivo
   Ciclo di vita del modello di dispositivo	Esportare le modifiche del modello di dispositivo pubblicate, incluse le modifiche create, aggiornate ed eliminate.	Il ciclo di vita del modello di dispositivo modifica il formato dei messaggi
   Log di audit	Log degli aggiornamenti avviati dall'utente alle entità nell'applicazione. Per altre informazioni, vedere Usare i log di controllo per tenere traccia dell'attività nell'applicazione IoT Central	Formato del messaggio del log di controllo

6. Facoltativamente, aggiungere filtri per ridurre la quantità di dati esportati. Per ogni tipo di esportazione dati sono disponibili diversi tipi di filtro:

   Tipo di dati	Filtri disponibili
   Telemetria	Filtrare in base al nome del dispositivo, all'ID dispositivo, al modello di dispositivo e se il dispositivo è simulato Filtrare il flusso in modo che contenga solo i dati di telemetria che soddisfano le condizioni di filtro Filtrare il flusso in modo che contenga solo i dati di telemetria dai dispositivi con proprietà corrispondenti alle condizioni di filtro Filtrare il flusso in modo che contenga solo i dati di telemetria con proprietà del messaggio che soddisfano la condizione di filtro. Le proprietà del messaggio (note anche come proprietà dell'applicazione) vengono inviate in un contenitore di coppie chiave-valore in ogni messaggio di telemetria. Per creare un filtro di proprietà del messaggio, immettere la chiave della proprietà del messaggio che si sta cercando e specificare una condizione. Vengono esportati solo i messaggi di telemetria con proprietà che corrispondono alla condizione di filtro specificata. Altre informazioni sulle proprietà dell'applicazione sono disponibili nella documentazione di hub IoT
   Modifiche alle proprietà	Filtrare in base al nome del dispositivo, all'ID dispositivo, al modello di dispositivo e se il dispositivo è simulato Filtrare il flusso in modo che contenga solo modifiche alle proprietà che soddisfano le condizioni di filtro
   Connettività dei dispositivi	Filtrare in base al nome del dispositivo, all'ID dispositivo, al modello di dispositivo, alle organizzazioni e se il dispositivo è simulato Filtrare il flusso in modo che contenga solo modifiche dai dispositivi con proprietà corrispondenti alle condizioni di filtro
   Ciclo di vita dei dispositivi	Filtrare in base al nome del dispositivo, all'ID dispositivo, al modello di dispositivo e se viene effettuato il provisioning, l'abilitazione o la simulazione del dispositivo Filtrare il flusso in modo che contenga solo modifiche dai dispositivi con proprietà corrispondenti alle condizioni di filtro
   Ciclo di vita del modello di dispositivo	Filtrare in base al modello di dispositivo
   Log di audit	N/D

7. Facoltativamente, arricchire i messaggi esportati con metadati di coppia chiave-valore aggiuntivi. Per i dati di telemetria, le modifiche alle proprietà, la connettività dei dispositivi e i tipi di esportazione dei dati del ciclo di vita del dispositivo sono disponibili i seguenti arricchimenti:

   • Stringa personalizzata: aggiunge una stringa statica personalizzata a ogni messaggio. Immettere qualsiasi chiave e immettere qualsiasi valore stringa.
   • Proprietà, che aggiunge a ogni messaggio:
     • Metadati del dispositivo, ad esempio nome del dispositivo, nome del modello di dispositivo, abilitato, organizzazioni, provisioning e simulato.
     • Valore della proprietà segnalata dal dispositivo corrente o della proprietà cloud a ogni messaggio. Se il messaggio esportato proviene da un dispositivo che non ha la proprietà specificata, il messaggio esportato non ottiene l'arricchimento.

Configurare la destinazione di esportazione:

1. Selezionare + Destinazione per aggiungere una destinazione già creata o selezionare Crea una nuova destinazione.

2. Per trasformare i dati prima dell'esportazione, selezionare + Trasforma. Per altre informazioni, vedere Trasformare i dati all'interno dell'applicazione IoT Central per l'esportazione.

3. Selezionare + Destinazione per aggiungere fino a cinque destinazioni a una singola esportazione.

4. Al termine della configurazione dell'esportazione, selezionare Salva. Dopo alcuni minuti, i dati sono visualizzati nelle destinazioni.

Monitorare l'esportazione

In IoT Central la pagina Esportazione dati consente di controllare lo stato delle esportazioni. È anche possibile usare Monitoraggio di Azure per verificare la quantità di dati da esportare ed eventuali errori di esportazione. È possibile accedere alle metriche di esportazione e integrità dei dispositivi nei grafici nella portale di Azure usando, l'API REST, le query in PowerShell o l'interfaccia della riga di comando di Azure. Attualmente, è possibile monitorare le metriche di esportazione dei dati seguenti in Monitoraggio di Azure:

• Numero di messaggi in arrivo da esportare prima dell'applicazione dei filtri.
• Numero di messaggi che passano attraverso filtri.
• Numero di messaggi esportati correttamente nelle destinazioni.
• Numero di errori rilevati.

Per altre informazioni, vedi Monitorare l'integrità dell'applicazione.

Formati di dati

Le sezioni seguenti descrivono i formati dei dati esportati:

Formato di telemetria

Ogni messaggio esportato contiene una forma normalizzata del messaggio completo inviato nel corpo del messaggio. Il messaggio è in formato JSON e codificato come UTF-8. Le informazioni in ogni messaggio includono:

• applicationId: ID dell'applicazione IoT Central.
• messageSource: origine del messaggio - telemetry.
• deviceId: ID del dispositivo che ha inviato il messaggio di telemetria.
• schema: nome e versione dello schema del payload.
• templateId: ID del modello di dispositivo assegnato al dispositivo.
• enqueuedTime: ora in cui IoT Central ha ricevuto questo messaggio.
• enrichments: eventuali arricchimenti impostati nell'esportazione.
• module: modulo IoT Edge che ha inviato questo messaggio. Questo campo viene visualizzato solo se il messaggio proviene da un modulo IoT Edge.
• component: componente che ha inviato il messaggio. Questo campo viene visualizzato solo se le funzionalità inviate nel messaggio sono state modellate come componente nel modello di dispositivo
• messageProperties: altre proprietà inviate dal dispositivo con il messaggio. Queste proprietà vengono talvolta definite proprietà dell'applicazione. Altre informazioni sono disponibili nella documentazione di hub IoT.

Proprietà del messaggio

I messaggi di telemetria hanno proprietà per i metadati e il payload di telemetria. Il frammento precedente mostra esempi di messaggi di sistema come deviceId e enqueuedTime. Per altre informazioni sulle proprietà dei messaggi di sistema, vedere Proprietà di sistema dei messaggi D2C hub IoT.

È possibile aggiungere proprietà ai messaggi di telemetria se è necessario aggiungere metadati personalizzati ai messaggi di telemetria. Ad esempio, è necessario aggiungere un timestamp quando il dispositivo crea il messaggio.

Il frammento di codice seguente mostra come aggiungere la iothub-creation-time-utc proprietà al messaggio quando la si crea nel dispositivo:

Importante

Il formato di questo timestamp deve essere UTC senza informazioni sul fuso orario. Ad esempio, 2021-04-21T11:30:16Z è valido, 2021-04-21T11:30:16-07:00 non è valido.

JavaScript

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

Java

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

C#

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

Python

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(msg)

Formato delle modifiche delle proprietà

Ogni messaggio o record rappresenta le modifiche apportate alle proprietà del dispositivo e del cloud. Le informazioni nel messaggio esportato includono:

• applicationId: ID dell'applicazione IoT Central.
• messageSource: origine del messaggio - properties.
• messageTypecloudPropertyChange: , devicePropertyDesiredChangeo devicePropertyReportedChange.
• deviceId: ID del dispositivo che ha inviato il messaggio di telemetria.
• schema: nome e versione dello schema del payload.
• enqueuedTime: ora in cui IoT Central ha rilevato questa modifica.
• templateId: ID del modello di dispositivo assegnato al dispositivo.
• properties: matrice di proprietà che sono state modificate, inclusi i nomi delle proprietà e dei valori modificati. Le informazioni sul componente e sul modulo vengono incluse se la proprietà viene modellata all'interno di un componente o di un modulo IoT Edge.
• enrichments: eventuali arricchimenti impostati nell'esportazione.

Formato delle modifiche alla connettività del dispositivo

Ogni messaggio o record rappresenta un evento di connettività da un singolo dispositivo. Le informazioni nel messaggio esportato includono:

• applicationId: ID dell'applicazione IoT Central.
• messageSource: origine del messaggio - deviceConnectivity.
• messageTypeconnected: o disconnected.
• deviceId: ID del dispositivo modificato.
• schema: nome e versione dello schema del payload.
• templateId: ID del modello di dispositivo assegnato al dispositivo.
• enqueuedTime: ora in cui si è verificata questa modifica in IoT Central.
• enrichments: eventuali arricchimenti impostati nell'esportazione.

Formato delle modifiche del ciclo di vita del dispositivo

Ogni messaggio o record rappresenta una modifica a un singolo dispositivo. Le informazioni nel messaggio esportato includono:

• applicationId: ID dell'applicazione IoT Central.
• messageSource: origine del messaggio - deviceLifecycle.
• messageType: tipo di modifica che si è verificato. Uno di: registered, deleted, provisionedenabled, disabled, , displayNameChangede deviceTemplateChanged.
• deviceId: ID del dispositivo modificato.
• schema: nome e versione dello schema del payload.
• templateId: ID del modello di dispositivo assegnato al dispositivo.
• enqueuedTime: ora in cui si è verificata questa modifica in IoT Central.
• enrichments: eventuali arricchimenti impostati nell'esportazione.

Formato delle modifiche del ciclo di vita del modello di dispositivo

Ogni messaggio o record rappresenta una modifica a un singolo modello di dispositivo pubblicato. Le informazioni nel messaggio esportato includono:

• applicationId: ID dell'applicazione IoT Central.
• messageSource: origine del messaggio - deviceTemplateLifecycle.
• messageTypecreated: , updatedo deleted.
• schema: nome e versione dello schema del payload.
• templateId: ID del modello di dispositivo assegnato al dispositivo.
• enqueuedTime: ora in cui si è verificata questa modifica in IoT Central.
• enrichments: eventuali arricchimenti impostati nell'esportazione.

Formato del log di controllo

Ogni messaggio del log di controllo rappresenta una modifica avviata dall'utente in un'entità controllabile all'interno dell'applicazione IoT Central. Le informazioni nel messaggio esportato includono:

• actor: informazioni sull'utente che ha modificato l'entità.
• applicationId: ID dell'applicazione IoT Central.
• messageSource: origine del messaggio - audit.
• messageType: tipo di modifica che si è verificato. Uno di: updated, created, deleted.
• updated: presente solo se messageType è updated. Fornisce altri dettagli sull'aggiornamento.
• resource: dettagli dell'entità modificata.
• schema: nome e versione dello schema del payload.
• deviceId: ID del dispositivo modificato.
• enqueuedTime: ora in cui si è verificata questa modifica in IoT Central.
• enrichments: eventuali arricchimenti impostati nell'esportazione.

Passaggi successivi

Ora che si è appreso come esportare in bus di servizio, un passaggio successivo consigliato consiste nell'apprendere l'esportazione in Hub eventi.