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. Zunächst erstellen Sie im Azure-Portal einen Event Hub. Anschließend erstellen Sie eine Zieltabelle in Azure Data Explorer, in der die Daten in einem bestimmten Format anhand der Erfassungseigenschaften erfasst werden. Die Event Hubs-Verbindung muss über Informationen zum Ereignisrouting verfügen. 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.

Authentifizierungsmechanismen für Azure Data Explorer-Datenverbindungen

Achtung

Wenn die Berechtigungen der verwalteten Identität aus der Datenquelle entfernt werden, wird die Datenverbindung deaktiviert, und es können keine Daten mehr aus der Datenquelle abgerufen werden.

  • Schlüsselbasierte Datenverbindung: Wenn in der Datenverbindung keine verwaltete Identität 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 generiert die Ressourcenverbindungszeichenfolge für die angegebene Ressource und speichert sie sicher in der Datenverbindung. Die Verbindungszeichenfolge wird dann verwendet, um Daten aus der Datenquelle abzurufen.

Achtung

Wenn der Schlüssel rotiert wird, wird die Datenverbindung deaktiviert, und es können keine Daten mehr aus der Datenquelle abgerufen werden. Um das Problem zu beheben, aktualisieren oder erstellen Sie die Datenverbindung neu.

Datenformat

  • Daten werden in Form von EventData-Objekten aus dem Event Hub gelesen.

  • Siehe Unterstützte Formate.

    Hinweis

  • Daten können mit dem GZip-Komprimierungsalgorithmus komprimiert werden. Sie können Compression dynamisch mithilfe von Compression oder in den statischen Datenverbindungseinstellungen angeben.

    Hinweis

    Für komprimierte Formate (Avro, Parquet, ORC, ApacheAvro und W3CLOGFILE) wird die Datenkomprimierung nicht unterstützt. Eine benutzerdefinierte Codierung und eingebettete Systemeigenschaften werden für komprimierte Daten nicht unterstützt.

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 (Standardeinstellung) oder GZip-Komprimierung.
Codierung 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 die Bytearray-Deserialisierung verwenden muss, um andere Routingeigenschaften zu lesen. Der Wert wird ignoriert.

Hinweis

Nur Ereignisse, die nach dem Erstellen der Datenverbindung in die Warteschlange eingereiht werden, werden erfasst.

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 ein alternatives Routing für Ihre Daten angeben, indem Sie die oben erwähnten Ereignisdateneigenschaften festlegen.

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. Diesen Schritt können Sie im Azure-Portal Azure-Portal, in C#, Python oder über eine ARM-Vorlage ausführen. 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.

Legen Sie zum Angeben einer alternativen Datenbank die ErfassungseigenschaftDatabase 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 ErfassungseigenschaftenTable, 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 Ereignissystemeigenschaften

Systemeigenschaften speichern vom Event Hubs-Dienst festgelegte Eigenschaften, wenn das Ereignis in die Warteschlange eingereiht wird. Die Datenverbindung mit dem Event Hub kann ausgewählte Systemeigenschaften basierend auf einer bestimmten Zuordnung in die in einer Tabelle erfassten Daten einbetten.

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 CSV die Zuordnung werden Eigenschaften am Anfang des Datensatzes in der Reihenfolge hinzugefügt, die bei 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 JSON 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 (Timespan, Metric 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, Metric: 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" : "Timespan", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "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" : "Timespan", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.value"}},'
    '    { "column" : "EventHubEnqueuedTime", "Properties":{"Path":"$.x-opt-enqueued-time"}},'
    '    { "column" : "EventHubOffset", "Properties":{"Path":"$.x-opt-offset"}}'
    ']'

Schemazuordnung für Event Hub Capture Avro-Dateien

Eine Möglichkeit zum Nutzen von Event Hub-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 den Event Hub 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 spezifische Informationen zum Dateischema für Event Hub Avro-Aufzeichnungsdaten finden Sie unter Erkunden aufgezeichneter 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 Updaterichtlinie an , die das Bytearray mithilfe der funktion unicode_codepoints_to_string() 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 Hub-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 Tarife Premium oder Dedicated Event Hub verwenden. Vergleich der Event Hub-Tarife 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 Ereignisse

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

Ein Beispiel zum Generieren von Beispieldaten finden Sie unter Erfassen von Daten aus Event Hub in Azure Data Explorer.

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.

Verwandte Inhalte