Exportieren von IoT-Daten in einen Webhook

In diesem Artikel wird beschrieben, wie Sie den Datenexport konfigurieren, um Daten an den Webhook 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 der Datenströme, um deren Form und Inhalt zu ändern.

Tipp

Wenn Sie den Datenexport aktivieren, erhalten Sie nur die Daten ab dem jeweiligen Aktivierungszeitpunkt. Wenn Sie mehr Verlaufsdaten beibehalten möchten, aktivieren Sie den Datenexport frühzeitig. Informationen zum manuellen Exportieren von Daten für Zeiten, in denen der Datenexport deaktiviert war, finden Sie unter Verwenden der REST-API in IoT Central zum Abfragen von Geräten.

Hinweis

In bestimmten Fällen kann es bis zu 60 Sekunden dauern, bis die Nachrichten exportiert werden. Hierbei handelt es sich um die Zeitspanne zwischen dem Zeitpunkt, zu dem IoT Central die Nachricht vom zugrunde liegenden IoT-Hub empfängt, und dem Zeitpunkt, zu dem die Nachricht an den Zielendpunkt übermittelt wird.

Voraussetzungen

Damit Sie die Datenexportfeatures verwenden können, müssen Sie über die Berechtigung Datenexport verfügen.

Einrichten eines Webhook-Exportziels

Für Webhookziele exportiert IoT Central Daten nahezu in Echtzeit. Die Daten im Nachrichtentext haben dasselbe Format wie bei Event Hubs und Service Bus.

Erstellen eines Webhookziels

Sie können Daten in einen öffentlich verfügbaren HTTP-Webhookendpunkt exportieren. Sie können einen Webhooktestendpunkt mit RequestBin erstellen. „RequestBin“ drosselt die Anforderung, wenn das Anforderungslimit erreicht wird:

1. Navigieren Sie zu RequestBin.

2. Wählen Sie Create a RequestBin aus.

3. Melden Sie sich mit einer der verfügbaren Methoden an.

4. Kopieren Sie die URL Ihres RequestBin. Sie verwenden diese URL beim Testen Ihres Datenexports.

So erstellen Sie das Azure Data Explorer-Ziel in IoT Central auf der Seite Datenexport:

1. Wählen Sie +Neues Ziel aus.

2. Wählen Sie Webhook als Zieltyp aus.

3. Bei Webhook fügen Sie die Callback-URL für Ihren Webhookendpunkt ein. Sie können optional die Webhookautorisierung konfigurieren und benutzerdefinierte Header hinzufügen.

   • Bei OAuth2.0 wird nur der Gewährungsflow für Clientanmeldeinformationen unterstützt. Wenn das Ziel gespeichert ist, kommuniziert IoT Central mit Ihrem OAuth-Anbieter, um ein Autorisierungstoken abzurufen. Dieses Token wird bei jeder an dieses Ziel gesendeten Nachricht an den Authorization-Header angefügt.
   • Für Autorisierungs-Token können Sie einen Token-Wert angeben, der bei jeder an dieses Ziel gesendeten Nachricht direkt an den Authorization-Header angehängt wird.

4. Wählen Sie Speichern.

Exemplarische OAuth 2.0-Konfiguration

In diesem Beispiel wird gezeigt, wie Sie ein Webhookziel für die Verwendung einer Azure-Funktions-App konfigurieren, die durch die Microsoft Entra-Anmeldung geschützt ist:

Einstellung	Beispiel	Hinweise
Zieltyp	Webhook
Rückruf-URL	https://myapp.azurewebsites.net/api/HttpExample	Die Funktions-URL.
Autorisierung	OAuth 2.0
Token-URL	https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token	Die URL zum Abrufen eines Tokens. Sie finden diesen Wert in Ihrer Funktions-App: Authentifizierung > Ihr Microsoft-Identitätsanbieter > Endpunkte > OAuth 2.0-Tokenendpunkt (v2)
Client-ID	your-client-id	Die Client-ID Ihrer Funktions-App. Sie finden diesen Wert in Ihrer Funktions-App: Authentifizierung > Ihr Microsoft-Identitätsanbieter > Anwendungs-ID (Client)
Geheimer Clientschlüssel	your-client-secret	Der geheime Clientschlüssel Ihrer Funktions-App. Sie finden diesen Wert in Ihrer Funktions-App: Authentifizierung > Ihr Microsoft-Identitätsanbieter > Zertifikate und Geheimnisse
Zielgruppe	N/V	Leer, wenn Sie eine Funktions-App verwenden.
`Scope`	https://your-client-id/.default	Der Bereich des Tokens. Verwenden Sie für eine Funktions-App den Client-ID-Wert.**
Inhaltstyp für Tokenanforderung	Automatisch

Bei anderen Webhookzielen müssen ggf. andere Werte für diese Einstellungen angegeben werden.

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 die Option Datenexport aus.

   Tipp

   Falls Datenexport dort nicht angezeigt wird, haben Sie keine Berechtigungen 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 Ihren 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).	Format der Telemetrienachricht
   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 der Eigenschaftsänderungsnachricht
   Gerätekonnektivität	Exportieren von Ereignissen zu verbundenen und getrennten Geräten	Nachrichtenformat zur Gerätekonnektivität
   Gerätelebenszyklus	Exportieren der Geräteereignisse „registered“, „deleted“, „provisioned“, „enabled“, „disabled“, „displayNameChanged“ und „deviceTemplateChanged“	Nachrichtenformat der Gerätelebenszyklusänderungen
   Gerätevorlagenlebenszyklus	Exportiert Änderungen an veröffentlichten Gerätevorlagen wie etwa Erstellungs-, Aktualisierungs- und Löschvorgänge.	Nachrichtenformat der Änderungen des Gerätevorlagenlebenszyklus
   Ü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.	Format der Überwachungsprotokollmeldung

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 Filtern des Datenstroms, sodass er nur Telemetriedaten mit Nachrichteneigenschaften enthält, die den Filterbedingungen entsprechen. Nachrichteneigenschaften (auch als Anwendungseigenschaften bezeichnet) werden in einer Sammlung von Schlüssel-Wert-Paaren in jeder 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
   Gerätelebenszyklus	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	N/V

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 Folgendes hinzufügt:
     • 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 Ein Neues Erstellen aus.

2. Wählen Sie + Transformieren aus, um Ihre Daten vor dem Export zu transformieren. Weitere Informationen finden Sie unter Transformieren von Daten in Ihrer IoT Central-Anwendung für den Export.

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

4. Wenn Sie das Einrichten Ihres Exports abgeschlossen haben, wählen Sie Speichern aus. Nach einigen Minuten werden Ihre Daten in Ihren Zielen angezeigt.

Überwachen des Exports

In IoT Central können Sie auf der Seite Datenexport den Status Ihrer Exporte überprüfen. Darüber hinaus können Sie in Azure Monitor die Datenmenge sehen, die exportiert wird, sowie etwaige 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 der Anwendungsintegrität.

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 auch als Anwendungseigenschaften bezeichnet. Weitere Informationen zu IoT Hub-Dokumenten.

Nachrichteneigenschaften

Telemetrie-Nachrichten haben Eigenschaften für Metadaten sowie für die Telemetrie-Nutzdaten. Der vorherige Codeausschnitt zeigt Beispiele für Systemmeldungen wie deviceId und enqueuedTime. Weitere Informationen zu Eigenschaften von Systemmeldungen finden Sie unter Systemeigenschaften von Gerät-zu-Cloud-IoT Hub-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:

Wichtig

Das Format dieses Zeitstempels muss UTC ohne Zeitzoneninformationen sein. Beispiel: 2021-04-21T11:30:16Z ist gültig, 2021-04-21T11:30:16-07:00 ist ungültig.

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)

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

Nächste Schritte

Nachdem Sie erfahren haben, wie Sie in Service Bus exportieren können, sollten Sie sich als Nächstes über das Exportieren in Event Hubs informieren.