Exportieren von IoT-Daten in Service Bus

In diesem Artikel wird beschrieben, wie Sie den Datenexport konfigurieren, um Daten an den Service Bus zu senden.

Verwenden Sie dieses Feature für den fortlaufenden Export von gefilterten und angereicherten IoT-Daten aus Ihrer IoT Central-Anwendung. Beim Datenexport werden Änderungen nahezu in Echtzeit in andere Teile Ihrer Cloudlösung gepusht, damit Sie umsetzbare Einblicke, Analyseergebnisse und Speicherinformationen erhalten.

Beispielsweise können Sie folgende Aktionen ausführen:

• Fortlaufendes Exportieren von Telemetriedaten, Eigenschaftsänderungen, Gerätekonnektivität, Gerätelebenszyklus, Lebenszyklus der Gerätevorlage und Überwachungsprotokolldaten im JSON-Format nahezu in Echtzeit
• Filtern der Datenströme zum Exportieren von Daten, die die benutzerdefinierten Bedingungen erfüllen.
• Anreichern der Datenströme mit benutzerdefinierten Werten und Eigenschaftswerten aus dem Gerät.
• Transformieren Sie die Datenströme , um deren Shape und Inhalt zu ändern.

Voraussetzungen

Zum Verwenden von Datenexportfeatures benötigen Sie die Datenexportberechtigung .

Einrichten eines Service Bus-Exportziels

Sowohl Warteschlangen als auch Themen werden für Azure Service Bus-Ziele unterstützt.

IoT Central exportiert Daten nahezu in Echtzeit. Die Daten befinden sich im Nachrichtentext und liegen im JSON-Format vor, das als UTF-8 codiert ist.

Die Sammlung von Anmerkungen bzw. Systemeigenschaften der Nachricht enthält die Felder iotcentral-device-id, iotcentral-application-id, iotcentral-message-source und iotcentral-message-type mit denselben Werten wie die entsprechenden Felder im Nachrichtentext.

Verbindungsoptionen

Mit den Service Bus-Zielen können Sie die Verbindung mit einer Verbindungszeichenfolge oder einer verwalteten Identität konfigurieren.

Verwaltete Identitäten sind aus folgenden Gründen sicherer:

• Sie speichern die Anmeldeinformationen für Ihre Ressource nicht in einer Verbindungszeichenfolge in Ihrer IoT Central-Anwendung.
• Die Anmeldeinformationen sind automatisch an die Lebensdauer Ihrer IoT Central-Anwendung gebunden.
• Verwaltete Identitäten rotieren ihre Sicherheitsschlüssel automatisch regelmäßig.

IoT Central verwendet derzeit vom System zugewiesene verwaltete Identitäten.

Wenn Sie eine verwaltete Identität konfigurieren, enthält die Konfiguration einen Bereich und eine Rolle:

• Mit dem Bereich wird definiert, wo die verwaltete Identität verwendet werden kann. Sie können zum Beispiel eine Azure-Ressourcengruppe als Bereich festlegen. In diesem Fall müssen sich die IoT Central-Anwendung und das Ziel in derselben Ressourcengruppe befinden.
• Mit der Rolle wird definiert, über welche Berechtigungen die IoT Central-Anwendung im Zieldienst verfügt. Damit eine IoT Central-Anwendung Daten an einen Event Hub senden kann, muss der verwalteten Identität beispielsweise die Rolle Azure Event Hubs Data Sender (Azure Event Hubs-Datensender) zugewiesen sein.

Das folgende Video enthält weitere Informationen zu vom System zugewiesenen verwalteten Identitäten:

Erstellen eines Ziels für Service Bus-Warteschlangen oder -Themen

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

Einrichten des Datenexports

Sie haben ein Ziel für den Export Ihrer Daten eingerichtet und richten jetzt den Datenexport in ihrer IoT Central Anwendung mit den folgenden Schritten ein:

1. Melden Sie sich bei Ihrer IoT Central-Anwendung an.

2. Wählen Sie im linken Bereich " Datenexport" aus.

   Tipp

   Wenn der Datenexport im linken Bereich nicht angezeigt wird, verfügen Sie nicht über die Berechtigung zum Konfigurieren des Datenexports in Ihrer App. Wenden Sie sich an Ihren Administrator, damit dieser den Datenexport einrichtet.

3. Wählen Sie +Neuer Export aus.

4. Geben Sie einen Anzeigenamen für den neuen Export ein, und stellen Sie sicher, dass der Datenexport aktiviert ist.

5. Wählen Sie den zu exportierenden Datentyp aus. In der folgenden Tabelle sind die unterstützten Datenexporttypen aufgeführt:

   Datentyp	BESCHREIBUNG	Datenformat
   Telemetrie	Exportiert Telemetrienachrichten von Geräten nahezu in Echtzeit. Jede exportierte Nachricht enthält den vollständigen Inhalt der ursprünglichen Gerätenachricht (normalisiert).	Telemetrieformat
   Eigenschaftsänderungen	Exportiert Änderungen zu den Geräte- und Cloudeigenschaften nahezu in Echtzeit. Bei schreibgeschützten Geräteeigenschaften werden Änderungen an den gemeldeten Werten exportiert. Bei Lese-/Schreibeigenschaften werden sowohl gemeldete als auch gewünschte Werte exportiert.	Format für Eigenschaftsänderungen
   Gerätekonnektivität	Exportieren von Ereignissen zu verbundenen und getrennten Geräten	Gerätekonnektivität ändert das Format
   Lebenszyklus von Geräten	Exportieren der Geräteereignisse „registered“, „deleted“, „provisioned“, „enabled“, „disabled“, „displayNameChanged“ und „deviceTemplateChanged“	Formatänderungen des Gerätelebenszyklus
   Gerätevorlagenlebenszyklus	Exportiert Änderungen an veröffentlichten Gerätevorlagen wie etwa Erstellungs-, Aktualisierungs- und Löschvorgänge.	Formatänderungen im Lebenszyklus von Gerätevorlagen
   Überwachungsprotokolle	Protokolle von benutzerseitig ausgelösten Updates für Entitäten in der Anwendung. Weitere Informationen finden Sie unter Verwenden von Überwachungsprotokollen zum Nachverfolgen von Aktivitäten in Ihrer IoT Central-Anwendung	Überwachungsprotokollformat

6. Fügen Sie optional Filter hinzu, um die Menge der exportierten Daten zu verringern. Für jeden Datenexporttyp gibt es verschiedene Arten von Filtern:

   Datentyp	Verfügbare Filter
   Telemetrie	Filtern nach Gerätename, Geräte-ID, Gerätevorlage und simulierten Geräten Filtern des Datenstroms, sodass er nur Telemetriedaten enthält, die den Filterbedingungen entsprechen Filtern des Datenstroms, sodass er nur Telemetriedaten von Geräten mit Eigenschaften enthält, die den Filterbedingungen entsprechen Filtere den Datenstrom, sodass nur Telemetrie enthalten ist, deren Nachrichteneigenschaften die Filterbedingung erfüllen. Nachrichteneigenschaften (auch als Anwendungseigenschaften bezeichnet) werden in einer Reihe von Schlüssel-Wert-Paaren für jede Telemetrienachricht gesendet. Zum Erstellen eines Nachrichteneigenschaftenfilters geben Sie den gesuchten Nachrichteneigenschaftsschlüssel ein, und geben Sie eine Bedingung an. Nur Telemetrienachrichten mit Eigenschaften, die die angegebene Filterbedingung erfüllen, werden exportiert. Weitere Informationen zu Anwendungseigenschaften finden Sie in der IoT Hub-Dokumentation.
   Eigenschaftsänderungen	Filtern nach Gerätename, Geräte-ID, Gerätevorlage und simulierten Geräten Filtern des Datenstroms, sodass er nur Eigenschaftsänderungen enthält, die den Filterbedingungen entsprechen
   Gerätekonnektivität	Filtern nach Gerätename, Geräte-ID, Gerätevorlage, Organisationen und ob das Gerät simuliert ist Filtern des Datenstroms, sodass er nur Änderungen von Geräten mit Eigenschaften enthält, die den Filterbedingungen entsprechen
   Lebenszyklus von Geräten	Filtern nach Gerätename, Geräte-ID, Gerätevorlage und bereitgestellten, aktivierten oder simulierten Geräten Filtern des Datenstroms, sodass er nur Änderungen von Geräten mit Eigenschaften enthält, die den Filterbedingungen entsprechen
   Gerätevorlagenlebenszyklus	Filtern nach Gerätevorlage
   Überwachungsprotokolle	–

7. Reichern Sie optional exportierte Nachrichten mit zusätzlichen Metadaten für Schlüssel-Wert-Paare an. Die folgenden Anreicherungen stehen für die Datenexporttypen „Telemetrie“, „Eigenschaftsänderungen“, „Gerätekonnektivität“ und „Gerätelebenszyklus“ zur Verfügung:

   • Benutzerdefinierte Zeichenfolge: Fügt jeder Nachricht eine benutzerdefinierte statische Zeichenfolge hinzu. Geben Sie einen beliebigen Schlüssel und einen beliebigen Zeichenfolgenwert ein.
   • Eigenschaft, die jeder Nachricht hinzugefügt wird:
     • Gerätemetadaten wie Gerätename, Gerätevorlagenname, aktiviert, Organisationen, bereitgestellt und simuliert.
     • Die aktuelle vom Gerät gemeldete Eigenschaft oder den Cloudeigenschaftswert Wenn die exportierte Nachricht aus einem Gerät stammt, das die angegebene Eigenschaft nicht hat, erhält die exportierte Nachricht die Anreicherung nicht.

Konfigurieren Sie das Exportziel:

1. Wählen Sie +Ziel aus, um ein Ziel hinzuzufügen, das Sie bereits erstellt haben, oder wählen Sie "Neues erstellen" aus.

2. Wenn Sie Ihre Daten vor dem Exportieren transformieren möchten, wählen Sie +TRANSFORMATION aus. Weitere Informationen finden Sie unter Transformieren von Daten in Ihrer IoT Central-Anwendung für den Export.

3. Wählen Sie +Ziel aus, um bis zu fünf Ziele zu einem einzelnen Export hinzuzufügen.

4. Wenn Sie den Export abgeschlossen haben, wählen Sie "Speichern" aus. Nach einigen Minuten werden Ihre Daten in Ihren Zielen angezeigt.

Überwachen des Exports

Auf der Seite " Datenexport " in IoT Central können Sie den Status Ihrer Exporte überprüfen. Sie können auch Azure Monitor verwenden, um zu sehen, wie viele Daten Sie exportieren, und alle Exportfehler. Sie können auf Metriken zum Export und zur Geräteintegrität in Diagrammen im Azure-Portal über die REST-API sowie über Abfragen in PowerShell oder über die Azure CLI zugreifen. Derzeit können Sie die folgenden Datenexportmetriken in Azure Monitor überwachen:

• Anzahl der eingehenden Nachrichten für den Export vor dem Anwenden von Filtern
• Anzahl der Nachrichten, die die Filter durchlaufen
• Anzahl von Nachrichten, die erfolgreich an die Ziele exportiert wurden
• Anzahl der gefundenen Fehler.

Weitere Informationen finden Sie unter Überwachen des Anwendungsstatus.

Datenformate

In den folgenden Abschnitten werden die Formate der exportierten Daten beschrieben:

Telemetrieformat

Jede exportierte Nachricht enthält eine normalisierte Form der vollständigen Nachricht, die das Gerät im Nachrichtentext gesendet hat. Die Nachricht ist im JSON-Format und als UTF-8 codiert. Jede Nachricht enthält folgende Informationen:

• applicationId: Die ID der IoT Central-Anwendung.
• messageSource: Die Quelle für die Nachricht (telemetry).
• deviceId:Die ID des Geräts, von dem die Telemetrienachricht gesendet wurde.
• schema: Den Namen und die Version des Nutzdatenschemas.
• templateId: Die ID der Gerätevorlage, die dem Gerät zugewiesen ist
• enqueuedTime: Den Zeitpunkt, zu dem diese Nachricht von IoT Central empfangen wurde.
• enrichments: Alle im Export eingerichteten Anreicherungen.
• module: Das IoT Edge-Modul, das diese Nachricht gesendet hat. Dieses Feld wird nur angezeigt, wenn die Nachricht aus einem IoT Edge-Modul stammt.
• component: Die Komponente, die diese Nachricht gesendet hat. Dieses Feld wird nur angezeigt, wenn die in der Nachricht gesendeten Funktionen als eine Komponente in der Gerätevorlage modelliert wurden.
• messageProperties: Hierbei handelt es sich um weitere Eigenschaften, die das Gerät zusammen mit der Nachricht gesendet hat. Diese Eigenschaften werden manchmal als Anwendungseigenschaften bezeichnet. Weitere Informationen finden Sie in der IoT Hub-Dokumentation.

Nachrichteneigenschaften

Telemetrienachrichten verfügen über Eigenschaften für Metadaten und die Telemetrienutzlast. Der vorherige Codeausschnitt zeigt Beispiele für Systemmeldungen wie deviceId und enqueuedTime. Weitere Informationen zu den Systemnachrichteneigenschaften finden Sie unter Systemeigenschaften von Geräte-zu-Cloud-Nachrichten.

Sie können Telemetrienachrichten Eigenschaften hinzufügen, wenn Sie Ihren Telemetrienachrichten benutzerdefinierte Metadaten hinzufügen möchten. Beispielsweise können Sie einen Zeitstempel für den Zeitpunkt hinzufügen, zu dem das Gerät die Meldung erstellt hat.

Der folgende Codeausschnitt zeigt, wie Sie der Nachricht die iothub-creation-time-utc-Eigenschaft hinzufügen, wenn diese auf dem Gerät erstellt wird:

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)

Format für Eigenschaftsänderungen

Jede Nachricht oder jeder Datensatz stellt Änderungen an Geräte- und Cloudeigenschaften dar. Die exportierte Nachricht enthält folgende Informationen:

• applicationId: Die ID der IoT Central-Anwendung.
• messageSource: Die Quelle für die Nachricht (properties).
• messageType: Entweder cloudPropertyChange, devicePropertyDesiredChange oder devicePropertyReportedChange
• deviceId:Die ID des Geräts, von dem die Telemetrienachricht gesendet wurde.
• schema: Den Namen und die Version des Nutzdatenschemas.
• enqueuedTime: Den Zeitpunkt, zu dem diese Änderung von IoT Central erkannt wurde.
• templateId: Die ID der Gerätevorlage, die dem Gerät zugewiesen ist
• properties: Ein Array von Eigenschaften, die geändert wurden, einschließlich der Namen der geänderten Eigenschaften und Werte. Die Komponenten- und Modulinformationen werden eingeschlossen, wenn die Eigenschaft innerhalb einer Komponente oder eines IoT Edge-Moduls modelliert wird.
• enrichments: Alle im Export eingerichteten Anreicherungen.

Änderungsformat bei der Gerätekonnektivität

Jede Nachricht und jeder Datensatz stellt ein Konnektivitätsereignis von einem einzelnen Gerät dar. Die exportierte Nachricht enthält folgende Informationen:

• applicationId: Die ID der IoT Central-Anwendung.
• messageSource: Die Quelle für die Nachricht (deviceConnectivity).
• messageType: Entweder connected oder disconnected
• deviceId: Die ID des Geräts, das geändert wurde.
• schema: Den Namen und die Version des Nutzdatenschemas.
• templateId: Die ID der Gerätevorlage, die dem Gerät zugewiesen ist
• enqueuedTime: Der Zeitpunkt, zu dem diese Änderung in IoT Central aufgetreten ist
• enrichments: Alle im Export eingerichteten Anreicherungen.

Format der Gerätelebenszyklusänderungen

Jede Nachricht bzw. jeder Datensatz stellt eine Änderung an einem einzelnen Gerät dar. Die exportierte Nachricht enthält folgende Informationen:

• applicationId: Die ID der IoT Central-Anwendung.
• messageSource: Die Quelle für die Nachricht (deviceLifecycle).
• messageType: Der Typ des aufgetretenen Fehlers. Einer der Werte registered, deleted, provisioned, enabled, disabled, displayNameChanged oder deviceTemplateChanged.
• deviceId: Die ID des Geräts, das geändert wurde.
• schema: Den Namen und die Version des Nutzdatenschemas.
• templateId: Die ID der Gerätevorlage, die dem Gerät zugewiesen ist
• enqueuedTime: Der Zeitpunkt, zu dem diese Änderung in IoT Central aufgetreten ist
• enrichments: Alle im Export eingerichteten Anreicherungen.

Format der Änderungen des Gerätevorlagenlebenszyklus

Jede Nachricht bzw. jeder Datensatz stellt eine Änderung an einer einzelnen veröffentlichten Gerätevorlage dar. Die exportierte Nachricht enthält folgende Informationen:

• applicationId: Die ID der IoT Central-Anwendung.
• messageSource: Die Quelle für die Nachricht (deviceTemplateLifecycle).
• messageType: Entweder created, updated oder deleted
• schema: Den Namen und die Version des Nutzdatenschemas.
• templateId: Die ID der Gerätevorlage, die dem Gerät zugewiesen ist
• enqueuedTime: Der Zeitpunkt, zu dem diese Änderung in IoT Central aufgetreten ist
• enrichments: Alle im Export eingerichteten Anreicherungen.

Format der Überwachungsprotokolle

Jede Überwachungsprotokollmeldung stellt eine benutzerseitig ausgelöste Änderung an einer überprüfbaren Entität innerhalb der IoT Central-Anwendung dar. Die exportierte Nachricht enthält folgende Informationen:

• actor: Informationen zu dem Benutzer, der die Entität geändert hat.
• applicationId: Die ID der IoT Central-Anwendung.
• messageSource: Die Quelle für die Nachricht (audit).
• messageType: Der Typ des aufgetretenen Fehlers. Einer der folgenden Werte: updated, created, deleted.
• updated: Nur vorhanden, wenn messageTypeupdated lautet. Bietet weitere Details zum Update.
• resource: Details der geänderten Entität
• schema: Den Namen und die Version des Nutzdatenschemas.
• deviceId: Die ID des Geräts, das geändert wurde.
• enqueuedTime: Der Zeitpunkt, zu dem diese Änderung in IoT Central aufgetreten ist
• enrichments: Alle im Export eingerichteten Anreicherungen.

Für Service Bus exportiert IoT Central neue Nachrichtendaten nahezu in Echtzeit in Ihre Service Bus-Warteschlange oder in Ihr Service Bus-Thema. In die Benutzereigenschaften (auch als „Anwendungseigenschaften“ bezeichnet) jeder Nachricht werden die Eigenschaften iotcentral-device-id, iotcentral-application-id, iotcentral-message-source und iotcentral-message-type automatisch einbezogen.

Nächste Schritte

Nachdem Sie nun wissen, wie Sie nach Service Bus exportieren, erfahren Sie im nächsten Schritt, wie IoT-Daten in Event Hubs exportiert werden.