Esportare i dati IoT nel bus di servizio

Questo articolo descrive come configurare l'esportazione dei dati per l'invio di dati a 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.

Prerequisiti

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

Configurare una destinazione di esportazione del bus di servizio

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

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 campi iotcentral-device-id,iotcentral-application-id, iotcentral-message-source e iotcentral-message-type con gli stessi valori dei campi corrispondenti nel corpo del messaggio.

Opzioni di connessione

Le destinazioni di bus di servizio consentono di configurare la connessione con una stringa di connessione 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:

Creare una destinazione della coda o dell'argomento del 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"

# 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"

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

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

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

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 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 dispositivo
• messageProperties: 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:

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);
}

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);
}

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 }}.");
}

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'ambito dell'applicazione IoT Central.
• messageSource: origine del messaggio - properties.
• messageType: cloudPropertyChange, devicePropertyDesiredChange o 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'ambito dell'applicazione IoT Central.
• messageSource: origine del messaggio - deviceConnectivity.
• messageType: connected 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'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 e 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'ambito dell'applicazione IoT Central.
• messageSource: origine del messaggio - deviceTemplateLifecycle.
• messageType: created, updated o 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'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 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 il bus di servizio, IoT Central esporta nuovi dati di messaggi nella coda o nell'argomento del bus di servizio quasi in tempo reale. Nelle proprietà utente (dette anche proprietà dell'applicazione) di ogni messaggio, iotcentral-device-id, iotcentral-application-id, iotcentral-message-source e 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.