Esportare i dati IoT in Esplora dati di Azure
Questo articolo descrive come configurare l'esportazione dei dati per l'invio di dati a Esplora dati di Azure.
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 recuperano solo i dati a partire dal momento dell'attivazione. Per conservare una maggiore quantità di dati cronologici, attivare presto l'esportazione dei dati. Per esportare manualmente i dati da periodi in cui l'esportazione dei dati era 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 di Esplora dati di Azure
È possibile usare un cluster di Esplora dati di Azure o un pool di Esplora dati di Azure Synapse. Per altre informazioni vedere Qual è la differenza tra Esplora dati di Azure Synapse ed Esplora dati di Azure?.
IoT Central esporta i dati quasi in tempo reale in una tabella di database nel cluster di Esplora dati di Azure. I dati si trovano nel corpo del messaggio ed è in formato JSON codificato come UTF-8. È possibile aggiungere una trasformazione in IoT Central per esportare i dati corrispondenti allo schema della tabella.
Per eseguire query sui dati esportati nel portale di Esplora dati di Azure, andare al database e selezionare Query.
Il video seguente illustra come esportare i dati in Esplora dati di Azure:
Opzioni di connessione
Le destinazioni di Esplora dati di Azure consentono di configurare la connessione con un'entità servizio o un'identità gestita.
Le identità gestite sono più sicure perché:
- Le credenziali per la risorsa non vengono archiviate in una stringa di connessione nell'applicazione IoT Central.
- Le credenziali vengono associate automaticamente alla durata dell'applicazione IoT Central.
- Le identità gestite ruotano automaticamente le chiavi di sicurezza regolarmente.
IoT Central usa attualmente identità gestite assegnate dal sistema.
Quando si configura un'identità gestita, la configurazione include un ambito e un ruolo:
- L'ambito definisce dove è possibile usare l'identità gestita. Ad esempio, è possibile usare un gruppo di risorse di Azure come ambito. In questo caso, sia l'applicazione IoT Central che la destinazione devono trovarsi nello stesso gruppo di risorse.
- Il ruolo definisce le autorizzazioni concesse all'applicazione IoT Central nel servizio di destinazione. Ad esempio, per un'applicazione IoT Central per inviare dati a un hub eventi, l'identità gestita richiede l'assegnazione di ruolo Mittente dati di Hub eventi di Azure.
Il video seguente fornisce altre informazioni sulle identità gestite assegnate dal sistema:
Attenzione
Per esportare nell'archiviazione BLOB, non usare Collaboratore account di archiviazione, come illustrato nel video. Usare invece il ruolo Collaboratore dati BLOB di archiviazione.
Creare una destinazione di Esplora dati di Azure
Questo articolo illustra come creare un'identità gestita usando l'interfaccia della riga di comando di Azure. È anche possibile usare il portale di Azure per creare un'identità gestita.
Se non si dispone di un database di Esplora dati di Azure esistente in cui eseguire l'esportazione, seguire questa procedura. Sono disponibili due opzioni per creare un database di Esplora dati di Azure:
- Creare un nuovo database e un cluster di Esplora dati di Azure. Per altre informazioni, vedere l'avvio rapido di Esplora dati di Azure. Prendere nota dell'URI del cluster e del nome del database creato, in quanto questi valori sono necessari nei passaggi seguenti.
- Creare un nuovo pool e database di Esplora dati di Azure Synapse. Per altre informazioni, vedere l'avvio rapido di Esplora dati di Azure. Prendere nota dell'URI del pool e del nome del database creato, in quanto questi valori sono necessari nei passaggi seguenti.
Per configurare l'identità gestita che consente all'applicazione IoT Central di esportare in modo sicuro i dati nella risorsa di Azure:
Creare un'identità gestita per l'applicazione IoT Central da usare per connettersi al database. Usare Azure Cloud Shell per eseguire il comando seguente:
az iot central app identity assign --name {your IoT Central app name} \ --resource-group {resource group name} \ --system-assigned
Prendere nota dell'output
principalId
etenantId
dal comando. Questi valori vengono usati nel passaggio seguente.Configurare le autorizzazioni del database per consentire le connessioni dall'applicazione IoT Central. Usare Azure Cloud Shell per eseguire il comando seguente:
az kusto database-principal-assignment create --cluster-name {name of your cluster} \ --database-name {name of your database} \ --resource-group {resource group name} \ --principal-assignment-name {name of your IoT Central application} \ --principal-id {principal id from the previous step} \ --principal-type App --role Admin \ --tenant-id {tenant id from the previous step}
Suggerimento
Se si usa Azure Synapse, vedere
az synapse kusto database-principal-assignment
.Creare una tabella nel database con uno schema appropriato per i dati da esportare. Nell'esempio seguente la query crea una tabella denominata
smartvitalspatch
. Per altre informazioni, vedere Trasformare i dati all'interno dell'applicazione IoT Central per l'esportazione:.create table smartvitalspatch ( EnqueuedTime:datetime, Message:string, Application:string, Device:string, Simulated:boolean, Template:string, Module:string, Component:string, Capability:string, Value:dynamic )
(Facoltativo) Per velocizzare l'inserimento dei dati nel database di Esplora dati di Azure:
Andare alla pagina Configurazioni per il cluster di Esplora dati di Azure. Abilitare quindi l'opzione Inserimento in streaming.
Eseguire la query seguente per modificare i criteri di tabella per abilitare l'inserimento in streaming:
.alter table smartvitalspatch policy streamingingestion enable
Per creare la destinazione di Esplora dati di Azure in IoT Central nella pagina Esportazione dati:
Selezionare + Nuova destinazione.
Selezionare Esplora dati di Azure come tipo di destinazione.
Immettere l'URL del cluster o del pool di Esplora dati di Azure, il nome del database e il nome della tabella. Selezionare Identità gestita assegnata dal sistema come tipo di autorizzazione.
Suggerimento
L'URL del cluster per Esplora dati di Azure autonomo è simile a
https://<ClusterName>.<AzureRegion>.kusto.windows.net
. L'URL del cluster per un pool di Esplora dati di Azure Synapse è simile ahttps://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net
.
Se non vengono visualizzati i dati in arrivo nel servizio di destinazione, vedere Risolvere i problemi relativi alle esportazioni di dati dall'applicazione Azure IoT Central.
Configurare un'esportazione dei dati
Ora che è disponibile una destinazione in cui esportare i dati, configurare l'esportazione dei dati nell'applicazione IoT Central:
Accedere all'applicazione IoT Central.
Selezionare Esportazione dati nel riquadro a sinistra.
Suggerimento
Se nel riquadro sinistro non viene visualizzato 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.
Selezionare + Nuova esportazione.
Immettere un nome visualizzato per la nuova esportazione e assicurarsi che l'esportazione dei dati sia Abilitata.
Scegliere il tipo di dati da esportare. Nella tabella seguente sono elencati i tipi di esportazione 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 alla 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 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 dalla documentazione dell'hub IoT
Modifiche alla 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 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:
Selezionare + Destinazione per aggiungere una destinazione già creata o selezionare Crea una nuova destinazione.
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.
Selezionare + Destinazione per aggiungere fino a cinque destinazioni a una singola esportazione.
Al termine della configurazione dell'esportazione, selezionare Salva. Dopo alcuni minuti, i dati vengono 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 nel 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 dei dati 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'ambito 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 dispositivomessageProperties
: altre proprietà inviate dal dispositivo con il messaggio. Queste proprietà vengono talvolta definite proprietà dell'applicazione. Altre informazioni sono disponibili nella documentazione dell'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 dell'hub IoT da dispositivo a cloud.
È 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 proprietà iothub-creation-time-utc
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 e 2021-04-21T11:30:16-07:00
non è valido.
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);
}
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'ambito dell'applicazione IoT Central.messageSource
: origine del messaggio -properties
.messageType
:cloudPropertyChange
,devicePropertyDesiredChange
odevicePropertyReportedChange
.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'ambito dell'applicazione IoT Central.messageSource
: origine del messaggio -deviceConnectivity
.messageType
:connected
odisconnected
.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'ambito dell'applicazione IoT Central.messageSource
: origine del messaggio -deviceLifecycle
.messageType
: tipo di modifica che si è verificato. Uno di:registered
,deleted
,provisioned
enabled
,disabled
,displayNameChanged
edeviceTemplateChanged
.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'ambito dell'applicazione IoT Central.messageSource
: origine del messaggio -deviceTemplateLifecycle
.messageType
:created
,updated
odeleted
.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'ambito dell'applicazione IoT Central.messageSource
: origine del messaggio -audit
.messageType
: tipo di modifica che si è verificato. Uno dei seguenti:updated
,created
,deleted
.updated
: presente solo semessageType
è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 Esplora dati di Azure, un passaggio successivo consigliato consiste nell'apprendere l'esportazione in Webhook.