Esportare i dati IoT in bus di servizio

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

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 bus di servizio

Sia le code che gli argomenti sono supportati per bus di servizio di Azure destinazioni.

IoT Central esporta i dati quasi in tempo reale. I dati si trovano nel corpo del messaggio ed è in formato JSON codificato come UTF-8.

L'elenco delle annotazioni o delle proprietà di sistema del messaggio contiene i iotcentral-device-idcampi , iotcentral-application-idiotcentral-message-source, e iotcentral-message-type con gli stessi valori dei campi corrispondenti nel corpo del messaggio.

Opzioni di connessione

bus di servizio destinazioni consentono di configurare la connessione con un stringa di connessione o un'identità gestita.

Le identità gestite sono più sicure perché:

• Non archiviare le credenziali per la risorsa in un 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 Hub eventi di Azure Mittente dati.

Il video seguente fornisce altre informazioni sulle identità gestite assegnate dal sistema:

Attenzione

Per esportare nell'archivio BLOB, non usare il Archiviazione Collaboratore account, come illustrato nel video. Usare invece il ruolo Collaboratore dati BLOB Archiviazione.

Creare una destinazione della coda o dell'argomento bus di servizio

Identità gestita

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

Se non si dispone di uno spazio dei nomi bus di servizio esistente in cui eseguire l'esportazione, eseguire lo script seguente nell'ambiente Bash di Azure Cloud Shell. Lo script crea un gruppo di risorse, uno spazio dei nomi bus di servizio e una coda. Lo script abilita quindi l'identità gestita per l'applicazione IoT Central e assegna il ruolo necessario per accedere alla coda bus di servizio:

# Replace the Service Bus namespace name with your own unique value
SBNS=your-service-bus-namespace-$RANDOM

# Replace the IoT Central app name with the name of your
# IoT Central application.
CA=your-iot-central-app

SBQ=exportdata
RG=centralexportresources
LOCATION=eastus

RGID=$(az group create -n $RG --location $LOCATION --query "id" --output tsv)
az servicebus namespace create --name $SBNS --resource-group $RG -l $LOCATION
az servicebus queue create --name $SBQ --resource-group $RG --namespace-name $SBNS

# This assumes your IoT Central application is in the 
# default `IOTC` resource group.
az iot central app identity assign --name $CA --resource-group IOTC --system-assigned
PI=$(az iot central app identity show --name $CA --resource-group IOTC --query "principalId" --output tsv)

az role assignment create --assignee $PI --role "Azure Service Bus Data Sender" --scope $RGID

az role assignment list --assignee $PI --all -o table

echo "Host name: $SBNS.servicebus.windows.net"
echo "Queue: $SBQ"

Per proteggere ulteriormente la coda o l'argomento e consentire l'accesso solo da servizi attendibili con identità gestite, vedere Esportare i dati in una destinazione sicura in un'istanza di Azure Rete virtuale.

Per creare la destinazione bus di servizio in IoT Central nella pagina Esportazione dati:

1. Selezionare + Nuova destinazione.

2. Selezionare bus di servizio di Azure Coda o bus di servizio di Azure Argomento come tipo di destinazione.

3. Selezionare Identità gestita assegnata dal sistema come tipo di autorizzazione.

4. Immettere il nome host della risorsa bus di servizio. Immettere quindi il nome della coda o dell'argomento con distinzione tra maiuscole e minuscole. Un nome host è simile al seguente: contoso-waste.servicebus.windows.net.

5. Seleziona Salva.

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.

Stringa di connessione

Se non si dispone di uno spazio dei nomi bus di servizio esistente in cui eseguire l'esportazione, eseguire lo script seguente nell'ambiente Bash di Azure Cloud Shell. Lo script crea un gruppo di risorse, uno spazio dei nomi bus di servizio e una coda. Stampa quindi il stringa di connessione da usare quando si configura l'esportazione dei dati in IoT Central:

# Replace the Service Bus namespace name with your own unique value
SBNS=your-service-bus-namespace-$RANDOM
SBQ=exportdata
RG=centralexportresources
LOCATION=eastus

az group create -n $RG --location $LOCATION
az servicebus namespace create --name $SBNS --resource-group $RG -l $LOCATION

# This example uses a Service Bus queue. You can use a Service Bus topic.
az servicebus queue create --name $SBQ --resource-group $RG --namespace-name $SBNS
az servicebus queue authorization-rule create --queue-name $SBQ --resource-group $RG --namespace-name $SBNS --name SendRule --rights Send

CS=$(az servicebus queue authorization-rule keys list --queue-name $SBQ --resource-group $RG --namespace-name $SBNS --name SendRule --query "primaryConnectionString" -o tsv)

echo "Service bus connection string: $CS"

Per creare la destinazione bus di servizio in IoT Central nella pagina Esportazione dati:

1. Selezionare + Nuova destinazione.

2. Selezionare bus di servizio di Azure Coda o bus di servizio di Azure Argomento come tipo di destinazione.

3. Selezionare Connessione ion string come tipo di autorizzazione.

4. Incollare il stringa di connessione per la risorsa bus di servizio e immettere il nome della coda o dell'argomento con distinzione tra maiuscole e minuscole, se necessario.

5. Seleziona Salva.

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.

Per bus di servizio, IoT Central esporta nuovi dati di messaggi nella coda o nell'argomento bus di servizio quasi in tempo reale. Nelle proprietà utente (dette anche proprietà dell'applicazione) di ogni messaggio, iotcentral-device-idiotcentral-application-idiotcentral-message-sourcee iotcentral-message-type vengono incluse automaticamente.

Passaggi successivi

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