Freigeben über

Azure Event Hubs-Datenverbindung

  • Artikel

Bei Azure Event Hubs handelt es sich um eine Big Data-Streamingplattform und einen Ereigniserfassungsdienst. Azure Data Explorer bietet eine kontinuierliche Erfassung von Daten aus kundenseitig verwalteten Event Hubs.

Die Event Hubs-Erfassungspipeline überträgt Ereignisse in mehreren Schritten an Azure Data Explorer. Zuerst erstellen Sie im Azure-Portal einen Ereignishub. Erstellen Sie dann eine Zieltabelle im Azure-Daten-Explorer, in die die Daten in einem bestimmten Format aufgenommen werden, mithilfe der bereitgestellten Aufnahmeeigenschaften. Die Event Hubs-Verbindung muss sich über das Routing von Ereignissen bewusst sein. Daten können mit ausgewählten Eigenschaften gemäß den Ereignissystemeigenschaften eingebettet werden. Erstellen Sie eine Verbindung mit Event Hubs, um einen Event Hub zu erstellen und Ereignisse zu senden. Dieser Prozess kann über das Azure-Portal, programmgesteuert mit C# oder Python oder mit der Azure Resource Manager-Vorlage verwaltet werden.

Allgemeine Informationen zur Datenerfassung in Azure Data Explorer finden Sie unter Übersicht über die Datenerfassung in Azure Data Explorer.

Azure Data Explorer-Datenverbindungsauthentifizierungsoptionen

  • Verwaltete Identitätsbasierte Datenverbindung (empfohlen): Die Verwendung einer verwalteten identitätsbasierten Datenverbindung ist die sicherste Methode zum Herstellen einer Verbindung mit Datenquellen. Sie bietet umfassende Steuerungsmöglichkeiten für das Abrufen von Daten aus einer Datenquelle. Das Einrichten einer Datenverbindung mit verwalteter Identität erfordert die folgenden Schritte:

    1. Hinzufügen einer verwalteten Identität zu Ihrem Cluster.
    2. Erteilen Sie Berechtigungen für die verwaltete Identität für die Datenquelle. Um Daten aus Azure Event Hubs abzurufen, muss die verwaltete Identität über Azure Event Hubs Data Receiver-Berechtigungen verfügen.
    3. Legen Sie eine Verwaltete Identitätsrichtlinie für die Zieldatenbanken fest.
    4. Erstellen Sie eine Datenverbindung mithilfe der verwalteten Identitätsauthentifizierung zum Abrufen von Daten.

    Achtung

    Wenn die Berechtigungen für verwaltete Identitäten aus der Datenquelle entfernt werden, funktioniert die Datenverbindung nicht mehr und kann keine Daten aus der Datenquelle abrufen.

  • Schlüsselbasierte Datenverbindung: Wenn in der Datenverbindung keine verwaltete Identitätsauthentifizierung angegeben wird, wird für die Verbindung automatisch eine schlüsselbasierte Authentifizierung verwendet. Bei schlüsselbasierten Verbindungen werden Daten unter Verwendung einer Ressourcenverbindungszeichenfolge abgerufen. (Ein Beispiel wäre etwa die Azure Event Hubs-Verbindungszeichenfolge.) Azure Data Explorer ruft die Ressourcenverbindungszeichenfolge für die angegebene Ressource ab und speichert sie sicher. Die Verbindungszeichenfolge wird dann verwendet, um Daten aus der Datenquelle abzurufen.

    Achtung

    Wenn der Schlüssel rotiert wird, funktioniert die Datenverbindung nicht mehr und kann keine Daten aus der Datenquelle abrufen. Um das Problem zu beheben, aktualisieren oder erstellen Sie die Datenverbindung neu.

Datenformat

Hinweis

  • Die Erfassung von Event Hubs unterstützt kein RAW-Format.
  • Azure Event Hubs-Schemaregistrierung Avro ohne Schema werden nicht unterstützt.
  • Daten können mit dem gzip-Komprimierungsalgorithmus komprimiert werden. Sie können Compression dynamisch mithilfe von Erfassungseigenschaften oder in den statischen Datenverbindungseinstellungen angeben.
  • Für Binärformate (Avro, ApacheAvro, Parquet, ORC und W3CLOGFILE) wird die Datenkomprimierung nicht unterstützt.
  • Benutzerdefinierte Codierungen und eingebettete Systemeigenschaften werden bei Binärformaten und komprimierten Daten nicht unterstützt.
  • Bei Verwendung von Binärformaten (Avro, ApacheAvro, Parquet, ORC und W3CLOGFILE) und Erfassungszuordnungen muss die Reihenfolge der Felder in der Erfassungszuordnungsdefinition mit der Reihenfolge der entsprechenden Spalten in der Tabelle übereinstimmen.

Event Hubs-Eigenschaften

Azure Data Explorer unterstützt die folgenden Event Hubs-Eigenschaften:

  • Eine geschlossene Gruppe von Erfassungseigenschaften, die Sie beim Routen des Ereignisses an die relevante Tabelle unterstützt.
  • Eine geschlossene Gruppe von Ereignissystemeigenschaften, die basierend auf einer bestimmten Zuordnung in die Daten eingebettet werden können.

Hinweis

Das Erfassen der benutzerdefinierten Eigenschaften von Event Hubs, die zum Zuordnen von Metadaten zu Ereignissen verwendet werden, wird nicht unterstützt. Wenn Sie benutzerdefinierte Eigenschaften erfassen müssen, senden Sie sie im Text der Ereignisdaten. Weitere Informationen finden Sie unter Erfassen benutzerdefinierter Eigenschaften.

Erfassungseigenschaften

Erfassungseigenschaften weisen den Erfassungsprozess an, wohin die Daten weitergeleitet und wie sie verarbeitet werden sollen. Sie können Erfassungseigenschaften der Ereigniserfassung mithilfe von EventData.Properties angeben. Sie können die folgenden Eigenschaften festlegen:

Hinweis

Bei Eigenschaftennamen wird zwischen Groß- und Kleinschreibung unterschieden.

Eigenschaft Beschreibung
Datenbank Der Name der Zieldatenbank unter Berücksichtigung der Groß-/Kleinschreibung. Standardmäßig werden Daten in der Zieldatenbank erfasst, die der Datenverbindung zugeordnet ist. Verwenden Sie diese Eigenschaft, um die Standarddatenbank zu überschreiben und Daten an eine andere Datenbank zu senden. Hierzu müssen Sie zuerst die Verbindung als Verbindung mit mehreren Datenbanken einrichten.
Tabelle Der Name der vorhandenen Zieltabelle unter Berücksichtigung der Groß-/Kleinschreibung. Überschreibt das Table-Element, das im Bereich Data Connection festgelegt ist.
Format Datenformat. Überschreibt das Data format-Element, das im Bereich Data Connection festgelegt ist.
IngestionMappingReference Name der zu verwendenden vorhandenen Erfassungszuordnung. Überschreibt das Column mapping-Element, das im Bereich Data Connection festgelegt ist.
Komprimierung Datenkomprimierung: None (Standard) oder gzip.
Codieren Datencodierung. Die Standardeinstellung ist UTF8. Alle von .NET unterstützten Codierungen können verwendet werden.
Tags Eine Liste der Tags, die den erfassten Daten zugeordnet werden sollen (formatiert als JSON-Arrayzeichenfolge). Die Verwendung von Tags hat Auswirkungen auf die Leistung.
RawHeaders Gibt an, dass die Ereignisquelle Kafka ist und Azure Data Explorer Byte-Array-Deserialisierung verwenden muss, um andere Routingeigenschaften zu lesen. Der Wert wird ignoriert.

Hinweis

Nur Ereignisse, die nach dem Erstellen der Datenverbindung abgefragt wurden, werden aufgenommen, es sei denn, ein benutzerdefiniertes Abrufanfangsdatum wird bereitgestellt. In jedem Fall kann der Lookbackzeitraum den tatsächlichen Aufbewahrungszeitraum für den Event Hub nicht überschreiten.

Ereignisrouting

Wenn Sie eine Datenverbindung mit Ihrem Cluster herstellen, können Sie das Routing für die Übermittlung der erfassten Daten angeben. Das Standardrouting gilt für die Zieltabelle, die in der Verbindungszeichenfolge angegeben ist, die der Zieldatenbank zugeordnet ist. Das Standardrouting für Ihre Daten wird auch als statisches Routing bezeichnet. Sie können eine alternative Routing- und Verarbeitungsoptionen für Ihre Daten angeben, indem Sie eine oder mehrere der im vorherigen Absatz erwähnten Ereignisdateneigenschaften festlegen.

Hinweis

Die Event Hubs-Datenverbindung versucht, alle Ereignisse zu verarbeiten, die sie aus dem Event Hub liest, und jedes Ereignis, das aus irgendeinem Grund nicht verarbeitet werden kann, wird als Erfassungsfehler gemeldet. Lesen Sie hier, wie Sie die Aufnahme von Azure Data Explorer überwachen.

Routen von Ereignisdaten an eine alternative Datenbank

Das Routing von Daten an eine alternative Datenbank ist standardmäßig deaktiviert. Um die Daten an eine andere Datenbank zu senden, müssen Sie zuerst die Verbindung als Verbindung mit mehreren Datenbanken festlegen. Dieses Feature kann im Azure-Portal Azure-Portal, mit C#- oder Python-Verwaltungs-SDKs oder mit einer ARM-Vorlage aktiviert werden. Der Benutzer, die Gruppe, der Dienstprinzipal oder die verwaltete Identität, der bzw. die zum Zulassen des Datenbankroutings verwendet wird, muss mindestens über die Rolle Mitwirkender und Schreibberechtigungen für den Cluster verfügen.

Um eine alternative Datenbank anzugeben, legen Sie die Database Erfassungseigenschaft fest.

Warnung

Wenn Sie eine alternative Datenbank angeben, ohne die Verbindung als Datenverbindung mit mehreren Datenbanken festzulegen, kann die Erfassung fehlschlagen.

Routen von Ereignisdaten an eine alternative Tabelle

Um eine alternative Tabelle für jedes Ereignis anzugeben, legen Sie die Erfassungseigenschaften Table, Format, Compression sowie die Erfassungseigenschaft für die Zuordnung fest. Die Verbindung leitet die erfassten Daten wie in EventData.Properties festgelegt dynamisch weiter und setzt dabei die statischen Eigenschaften für dieses Ereignis außer Kraft.

Im folgenden Beispiel wird gezeigt, wie Sie die Event Hub-Details festlegen und Wettermetrikdaten an eine alternative Datenbank (MetricsDB) und Tabelle (WeatherMetrics) senden. Die Daten liegen im JSON-Format vor, und mapping1 ist für die Tabelle WeatherMetrics vordefiniert.

// This sample uses Azure.Messaging.EventHubs which is a .Net Framework library.
await using var producerClient = new EventHubProducerClient("<eventHubConnectionString>");
// Create the event and add optional "dynamic routing" properties
var eventData = new EventData(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(
    new { TimeStamp = DateTime.UtcNow, MetricName = "Temperature", Value = 32 }
)));
eventData.Properties.Add("Database", "MetricsDB");
eventData.Properties.Add("Table", "WeatherMetrics");
eventData.Properties.Add("Format", "json");
eventData.Properties.Add("IngestionMappingReference", "mapping1");
eventData.Properties.Add("Tags", "['myDataTag']");
var events = new[] { eventData };
// Send events
await producerClient.SendAsync(events);

Zuordnung von Event Hubs-Systemeigenschaften

Systemeigenschaften sind Felder, die vom Event Hubs-Dienst festgelegt werden, zum Zeitpunkt der Enqueuierung des Ereignisses. Azuer Data Explorer Event Hubs-Datenverbindung kann einen vordefinierten Satz von Systemeigenschaften in die daten einbetten, die in eine Tabelle aufgenommen werden, basierend auf einer bestimmten Zuordnung.

Hinweis

  • Das Einbetten von Systemeigenschaften wird für JSON-Formate und tabellarische Formate (d. h. JSON, MultiJSON, CSV, TSV, PSV, SCsv, SOHsv, TSVE) unterstützt.
  • Bei Verwendung eines nicht unterstützten Formats (z. B. TXT oder komprimierte Formate wie Parquet, Avro usw.) werden die Daten zwar erfasst, die Eigenschaften werden jedoch ignoriert.
  • Das Einbetten von Systemeigenschaften wird nicht unterstützt, wenn eine Komprimierung von Event Hub-Nachrichten festgelegt ist. In solchen Szenarien wird ein entsprechender Fehler ausgegeben, und die Daten werden nicht erfasst.
  • Bei Tabellendaten werden Systemeigenschaften nur für Ereignismeldungen mit einem Datensatz unterstützt.
  • Bei JSON-Daten werden Systemeigenschaften auch für Ereignismeldungen mit mehreren Datensätzen unterstützt. In solchen Fällen werden die Systemeigenschaften nur dem ersten Datensatz der Ereignismeldung hinzugefügt.
  • Für die CSV-Zuordnung werden Eigenschaften am Anfang des Datensatzes in der Reihenfolge hinzugefügt, die in der Erstellung der Datenverbindung aufgeführt ist. Verlassen Sie sich nicht auf die Reihenfolge dieser Eigenschaften, da sie sich in Zukunft ändern kann.
  • Für die JSON-Zuordnung werden Eigenschaften entsprechend den Eigenschaftsnamen in der Tabelle Systemeigenschaften hinzugefügt.

Der Event Hubs-Dienst macht die folgenden Systemeigenschaften verfügbar:

Eigenschaft Datentyp Beschreibung
x-opt-enqueued-time datetime UTC-Zeit, zu der das Ereignis in die Warteschlange eingereiht wurde.
x-opt-sequence-number long Die logische Folgenummer des Ereignisses innerhalb des Partitionsdatenstroms des Event Hubs
x-opt-offset string Der Offset des Ereignisses vom Event Hub-Partitionsdatenstrom. Der Offsetbezeichner ist innerhalb einer Partition des Event Hub-Datenstroms eindeutig.
x-opt-publisher string Der Name des Herausgebers, wenn die Nachricht an einen Herausgeberendpunkt gesendet wurde.
x-opt-partition-key string Der Partitionsschlüssel der entsprechenden Partition, in der das Ereignis gespeichert wurde.

Wenn Sie mit Event Hubs für IoT Central arbeiten, können Sie auch IoT Hub-Systemeigenschaften in die Nutzdaten einbetten. Eine vollständige Liste finden Sie unter Zuordnung von Ereignissystemeigenschaften.

Wenn Sie Ereignissystemeigenschaften im Abschnitt Datenquelle der Tabelle ausgewählt haben, müssen Sie die Eigenschaften in das Tabellenschema und die Zuordnung einschließen.

Beispiele für die Schemazuordnung

Beispiel für die Tabellenschemazuordnung

Wenn Ihre Daten drei Spalten (TimeStamp, MetricName und Value) enthalten und die Eigenschaften, die Sie einschließen, x-opt-enqueued-time und x-opt-offset lauten, erstellen oder ändern Sie das Tabellenschema mit dem folgenden Befehl:

    .create-merge table TestTable (TimeStamp: datetime, MetricName: string, Value: int, EventHubEnqueuedTime:datetime, EventHubOffset:string)

Beispiel für eine CSV-Zuordnung

Führen Sie die folgenden Befehle aus, um am Anfang des Datensatzes Daten hinzuzufügen. Beachten Sie die Ordinalwerte.

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "MetricName", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "EventHubEnqueuedTime", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "EventHubOffset", "Properties":{"Ordinal":"1"}}'
    ']'

Beispiel für eine JSON-Zuordnung

Daten werden mithilfe der Systemeigenschaftenzuordnung hinzugefügt. Führen Sie diese Befehle aus:

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "TimeStamp", "Properties":{"Path":"$.TimeStamp"}},'
    '    { "column" : "MetricName", "Properties":{"Path":"$.MetricName"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.Value"}},'
    '    { "column" : "EventHubEnqueuedTime", "Properties":{"Path":"$.x-opt-enqueued-time"}},'
    '    { "column" : "EventHubOffset", "Properties":{"Path":"$.x-opt-offset"}}'
    ']'

Schemazuordnung für Event Hubs Capture Avro-Dateien

Eine Möglichkeit zum Nutzen von Event Hubs-Daten besteht darin, Ereignisse über Azure Event Hubs in Azure Blob Storage oder Azure Data Lake Storage aufzuzeichnen. Sie können dann die Aufzeichnungsdateien erfassen, während sie geschrieben werden, mithilfe einer Event Grid-Datenverbindung in Azure Data Explorer.

Das Schema der Aufzeichnungsdateien unterscheidet sich von dem Schema des Originalereignisses, das an Event Hubs gesendet wird. Sie sollten diesen Unterschied beim Entwerfen des Zieltabellenschemas berücksichtigen. Insbesondere wird die Ereignisnutzlast in der Aufzeichnungsdateien als Bytearray dargestellt, und dieses Array wird nicht automatisch von der Event Grid Azure Data Explorer-Datenverbindung decodiert. Weitere Informationen zum Dateischema für Event Hubs Avro-Erfassungsdaten finden Sie unter Untersuchen erfasster Avro-Dateien in Azure Event Hubs.

So decodieren Sie die Ereignisnutzlast ordnungsgemäß

  1. Ordnen Sie das Feld Body des aufgezeichneten Ereignisses einer Spalte des Typs dynamic in der Zieltabelle zu.
  2. Wenden Sie eine Aktualisierungsrichtlinie an, die das Bytearray mithilfe der unicode_codepoints_to_string()-Funktion in eine lesbare Zeichenfolge konvertiert.

Erfassen benutzerdefinierter Eigenschaften

Bei der Erfassung von Ereignissen aus Event Hubs werden Daten aus dem Abschnitt body des Ereignisdatenobjekts übernommen. Benutzerdefinierte Eigenschaften von Event Hubs werden jedoch im Abschnitt properties des Objekts definiert und nicht erfasst. Um benutzerdefinierte Eigenschaften zu erfassen, müssen Sie sie in die Daten im Abschnitt body des Objekts einbetten.

Im folgenden Beispiel wird das Ereignisdatenobjekt, das die benutzerdefinierte Eigenschaft customProperty wie von Event Hubs (links) definiert enthält, mit der eingebetteten Eigenschaft verglichen, die für die Erfassung erforderlich ist (rechts).

{
"body":{
"value": 42
},
"properties":{
"customProperty": "123456789"
}
}

{
"body":{
"value": 42,
"customProperty": "123456789"
}
}

Sie können eine der folgenden Methoden verwenden, um benutzerdefinierte Eigenschaften im Abschnitt body des Ereignisdatenobjekts in die Daten einzubetten:

Regionsübergreifende Event Hubs-Datenverbindung

Die beste Leistung erzielen Sie, wenn Sie alle folgenden Ressourcen in der gleichen Region wie den Cluster erstellen. Wenn es keine andere Alternative gibt, sollten Sie die Premium oder Dedizierten Event Hubs-Ebenen verwenden. Vergleich der Event Hubs-Ebenen finden Sie hier.

Erstellen eines Ereignis-Hubs

Erstellen Sie einen Event Hub, sofern Sie noch keinen haben. Die Verbindungsherstellung mit Event Hub kann über das Azure-Portal, programmgesteuert mit C# oder Python oder mit der Azure Resource Manager-Vorlage verwaltet werden.

Hinweis

  • Die Möglichkeit, Partitionen nach dem Erstellen eines Event Hubs dynamisch hinzuzufügen, ist nur mit Event Hubs Premium und Dedicated-Ebenen verfügbar. Berücksichtigen Sie beim Festlegen der Partitionsanzahl die langfristigen Skalierungsanforderungen.
  • Die Consumergruppe muss pro Consumer eindeutig sein. Erstellen Sie eine dedizierte Consumergruppe für die Azure Data Explorer-Verbindung.

Senden von Ereignissen

Sehen Sie sich die Beispiel-App an, die Daten generiert und an einen Event Hub sendet.

Einrichten einer Lösung für die georedundante Notfallwiederherstellung

Event Hub bietet eine Lösung für die georedundante Notfallwiederherstellung. Azure Data Explorer unterstützt keine Event Hub-Namespaces vom Typ Alias. Erstellen Sie zum Implementieren der georedundanten Notfallwiederherstellung in Ihrer Lösung zwei Event Hub-Datenverbindungen: eine für den primären Namespace und eine für den sekundären Namespace. Azure Data Explorer lauscht auf beide Event Hub-Verbindungen.

Hinweis

Es liegt in der Verantwortung des Benutzers, ein Failover vom primären Namespace auf den sekundären Namespace zu implementieren.

Zugehöriger Inhalt