Dela via

Azure Event Hubs-dataanslutning

  • Artikel

Azure Event Hubs är en stordataströmningsplattform och händelseinmatningstjänst. Azure Data Explorer erbjuder kontinuerlig inmatning från kundhanterade händelsehubbar.

Event Hubs-inmatningspipelinen överför händelser till Azure Data Explorer i flera steg. Först skapar du en händelsehubb i Azure-portalen. Skapa sedan en måltabell i Azure Data Explorer där data i ett visst format matas in med hjälp av de angivna inmatningsegenskaperna. Event Hubs-anslutningen måste ta hänsyn till händelsedirigering. Data kan bäddas in med valda egenskaper enligt händelsesystemegenskaperna. Skapa en anslutning till Event Hubs för att skapa en händelsehubb och skicka händelser. Den här processen kan hanteras via Azure Portal, programmatiskt med C# eller Python eller med Azure Resource Manager-mallen.

Allmän information om datainmatning i Azure Data Explorer finns i översikt över datainmatning i Azure Data Explorer.

Autentiseringsalternativ för Azure Data Explorer-dataanslutning

  • Hanterad identitetsbaserad dataanslutning (rekommenderas): Att använda en hanterad identitetsbaserad dataanslutning är det säkraste sättet att ansluta till datakällor. Det ger fullständig kontroll över möjligheten att hämta data från en datakälla. Konfiguration av en dataanslutning med hanterad identitet kräver följande steg:

    1. Lägg till en hanterad identitet i klustret.
    2. Bevilja behörigheter till den hanterade identiteten på datakällan. Om du vill hämta data från Azure Event Hubs måste den hanterade identiteten ha behörigheter för Azure Event Hubs Data Receiver .
    3. Ange en princip för hanterad identitet på måldatabaserna.
    4. Skapa en dataanslutning med hjälp av den hanterade identitetsautentiseringen för att hämta data.

    Försiktighet

    Om behörigheterna för hanterad identitet tas bort från datakällan fungerar inte längre dataanslutningen och kan inte hämta data från datakällan.

  • Nyckelbaserad dataanslutning: Om en hanterad identitetsautentisering inte har angetts för dataanslutningen är anslutningen automatiskt standard för nyckelbaserad autentisering. Nyckelbaserade anslutningar hämtar data med hjälp av en resursanslutningssträng, till exempel Azure Event Hubs-anslutningssträngen. Azure Data Explorer hämtar resursanslutningssträngen för den angivna resursen och sparar den på ett säkert sätt. Anslutningssträngen används sedan för att hämta data från datakällan.

    Försiktighet

    Om nyckeln roteras fungerar inte längre dataanslutningen och kan inte hämta data från datakällan. Åtgärda problemet genom att uppdatera eller återskapa dataanslutningen.

Dataformat

  • Data läss från händelsehubben i form av EventData objekt.
  • Se format som stöds.

Anmärkning

  • Inmatning från Event Hubs stöder inte RAW-format.
  • Azure Event Hubs Schema Registry och schemalösa Avro stöds inte.
  • Data kan komprimeras med hjälp av komprimeringsalgoritmen gzip . Du kan ange Compression dynamiskt med hjälp av inmatningsegenskaper eller i inställningarna för statisk dataanslutning.
  • Datakomprimering stöds inte för binära format (Avro, ApacheAvro, Parquet, ORC och W3CLOGFILE).
  • Anpassade kodnings- och inbäddade systemegenskaper stöds inte med binära format och komprimerade data.
  • När du använder binära format (Avro, ApacheAvro, Parquet, ORC och W3CLOGFILE) och inmatningsmappningar måste ordningen på fälten i inmatningsmappningsdefinitionen matcha ordningen för motsvarande kolumner i tabellen.

Egenskaper för Event Hubs

Azure Data Explorer stöder följande Event Hubs-egenskaper:

Anmärkning

Inmatning av anpassade egenskaper för Event Hubs, som används för att associera metadata med händelser, stöds inte. Om du behöver mata in anpassade egenskaper skickar du dem i brödtexten för händelsedata. Mer information finns i Mata in anpassade egenskaper.

Inmatningsegenskaper

Inmatningsegenskaper instruerar inmatningsprocessen, var data ska dirigeras och hur de ska bearbetas. Du kan ange inmatningsegenskaper för händelseinmatningen med hjälp av EventData.Properties. Du kan ange följande egenskaper:

Anmärkning

Egenskapsnamn är skiftlägeskänsliga.

Fastighet Beskrivning
Databas Måldatabasens skiftlägeskänsliga namn. Som standard matas data in i måldatabasen som är associerad med dataanslutningen. Använd den här egenskapen för att åsidosätta standarddatabasen och skicka data till en annan databas. För att göra det måste du först konfigurera anslutningen som en anslutning med flera databaser.
Tabell Det skiftlägeskänsliga namnet på den befintliga måltabellen. Åsidosätter Table som är inställd på rutan Data Connection.
Format Dataformat. Åsidosätter uppsättningen Data format på panelen Data Connection.
IngestionMappingReference Namnet på den befintliga inmatningsmappning som ska användas. Åsidosätter Column mapping inställt på Data Connection-panelen.
Komprimering Datakomprimering, None (standard) eller gzip.
Kodning Datakodning, standardvärdet är UTF8. Kan vara någon av .NET-kodningar som stöds.
Taggar En lista över taggar som ska associeras med inmatade data, formaterad som en JSON-matrissträng. Det finns prestandakonsekvenser när du använder taggar.
RawHeaders Anger att händelsekällan är Kafka och Att Azure Data Explorer måste använda bytematrisens deserialisering för att läsa andra routningsegenskaper. Värdet ignoreras.

Anmärkning

Endast händelser som anges när du har skapat dataanslutningen matas in, såvida inte ett anpassat startdatum för hämtning anges. I vilket fall som helst får tillbakablicksperioden inte överskrida den faktiska lagringsperioden för Event Hub.

Händelsedirigering

När du skapar en dataanslutning till klustret kan du ange routning för var inmatade data ska skickas. Standarddirigeringen är till måltabellen som anges i anslutningssträngen som är associerad med måldatabasen. Standardroutningen för dina data kallas även för statisk routning. Du kan ange alternativa routnings- och bearbetningsalternativ för dina data genom att ange en eller flera egenskaper för händelsedata som nämns i föregående stycke.

Anmärkning

Event Hubs-dataanslutningen försöker bearbeta alla händelser som den läser från händelsehubben, och varje händelse som den inte kan bearbeta av någon anledning rapporteras som ett inmatningsfel. Läs mer om hur du övervakar inmatning i Azure Data Explorer här.

Dirigera händelsedata till en alternativ databas

Routning av data till en alternativ databas är inaktiverad som standard. Om du vill skicka data till en annan databas måste du först ange anslutningen som en anslutning med flera databaser. Den här funktionen kan aktiveras i Azure-portalen i Azure-portalen, med SDK:er för C# eller Python-hantering eller med en ARM-mall. Användaren, gruppen, tjänstens huvudnamn eller hanterade identitet som används för att tillåta databasroutning måste minst ha deltagarrollen och skrivbehörigheterna i klustret.

Ange ingesteringsegenskapen Database för att ange en alternativ databas.

Varning

Om du anger en alternativ databas utan att ställa in anslutningen som en dataanslutning med flera databaser misslyckas inmatningen.

Dirigera händelsedata till en alternativ tabell

Om du vill ange en alternativ tabell för varje händelse anger du egenskaperna Tabell, Format, Komprimering och mappning av inmatning. Anslutningen dirigerar dynamiskt inmatade data enligt vad som anges i EventData.Properties, vilket åsidosätter de statiska egenskaperna för den här händelsen.

I följande exempel visas hur du anger händelsehubbens information och skickar vädermåttdata till en alternativ databas (MetricsDB) och tabell (WeatherMetrics). Data är i JSON-format och mapping1 är fördefinierad i tabellen WeatherMetrics.

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

Mappning av systemegenskaper för Event Hubs

Systemegenskaper är fält som anges av Event Hubs-tjänsten när händelsen anges. Azure Data Explorer Event Hubs-dataanslutning kan bädda in en fördefinierad uppsättning systemegenskaper i data som matas in i en tabell baserat på en viss mappning.

Anmärkning

  • Inbäddning av systemegenskaper stöds för json- och tabellformat (t.ex. JSON, , MultiJSONCSV, TSV, PSV, SCsv, SOHsv, ). TSVE
  • När du använder ett format som inte stöds (i.e. TXT eller komprimerade format som Parquetosv Avro .) matas data fortfarande in, men egenskaperna ignoreras.
  • Inbäddning av systemegenskaper stöds inte när en komprimering av Event Hub-meddelanden anges. I sådana scenarier genereras ett lämpligt fel och datan tas inte emot.
  • För tabelldata stöds systemegenskaper endast för händelsemeddelanden med en enda post.
  • För json-data stöds även systemegenskaper för händelsemeddelanden med flera poster. I sådana fall läggs systemegenskaperna bara till i den första posten i händelsemeddelandet.
  • För CSV mappning läggs egenskaper till i början av posten i den ordning som anges när dataanslutningen skapas. Förlita dig inte på ordningen på dessa egenskaper, eftersom det kan ändras i framtiden.
  • För JSON mappning läggs egenskaper till enligt egenskapsnamn i tabellen Systemegenskaper .

Event Hubs-tjänsten exponerar följande systemegenskaper:

Fastighet Datatyp Beskrivning
x-opt-enqueued-time datetime UTC-tid när händelsen kördes
x-opt-sequensnummer long Det logiska sekvensnumret för händelsen i partitionsströmmen för händelsehubben
x-opt-offset string Förskjutningen av händelsen från händelsehubbens partitionström. Förskjutningsidentifieraren är unik inom en partition av händelsehubbens dataström
x-opt-publisher string Utgivarens namn, om meddelandet skickades till en utgivarslutpunkt
x-opt-partition-key string Partitionsnyckeln för motsvarande partition som lagrade händelsen

När du arbetar med IoT Central-händelsehubbar kan du även bädda in IoT Hub-systemegenskaper i nyttolasten. Den fullständiga listan finns i Systemegenskaper för IoT Hub.

Om du har valt Egenskaper för händelsesystem i avsnittet Datakälla i tabellen måste du inkludera egenskaperna i tabellschemat och mappningen.

Exempel på schemamappning

Exempel på tabellschemamappning

Om dina data innehåller tre kolumner (TimeStamp, MetricName, och Value) och de egenskaper som du inkluderar är x-opt-enqueued-time och x-opt-offset, skapar eller ändrar du tabellschemat med hjälp av det här kommandot:

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

EXEMPEL på CSV-mappning

Kör följande kommandon för att lägga till data i början av posten. Anteckna ordningstalsvärden.

    .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"}}'
    ']'

JSON-mappningsexempel

Data läggs till med hjälp av mappningen av systemegenskaper. Kör följande kommandon:

    .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"}}'
    ']'

Schemamappning för Event Hubs Capture Avro-filer

Ett sätt att använda Event Hubs-data är att samla in händelser via Azure Event Hubs i Azure Blob Storage eller Azure Data Lake Storage. Du kan sedan mata in avbildningsfilerna när de skrivs med en Event Grid-dataanslutning i Azure Data Explorer.

Schemat för avbildningsfilerna skiljer sig från schemat för den ursprungliga händelsen som skickades till Event Hubs. Du bör utforma måltabellschemat med den här skillnaden i åtanke. Mer specifikt representeras händelsenyttolasten i avbildningsfilen som en bytematris, och den här matrisen avkodas inte automatiskt av Dataanslutningen till Event Grid Azure Data Explorer. Mer information om filschemat för Event Hubs Avro-insamlingsdata finns i Utforska insamlade Avro-filer i Azure Event Hubs.

För att korrekt avkoda händelsenyttolasten:

  1. Mappa fältet för Body den insamlade händelsen till en kolumn av typen dynamic i måltabellen.
  2. Tillämpa en uppdateringsprincip som konverterar bytematrisen till en läsbar sträng med hjälp av funktionen unicode_codepoints_to_string().

Importera anpassade egenskaper

Vid inmatning av händelser från Event Hubs hämtas data från body avsnittet i händelsedataobjektet. Anpassade egenskaper för Event Hubs definieras dock i properties avsnittet i objektet och matas inte in. Om du vill mata in kundegenskaper måste du bädda in dem i data i body avsnittet i objektet.

I följande exempel jämförs händelsedataobjektet som innehåller anpassad egenskap customPropertyenligt definitionen i Event Hubs (vänster) med den inbäddade egenskap som krävs för inmatning (höger).

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

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

Du kan använda någon av följande metoder för att bädda in anpassade egenskaper i data i body avsnittet för händelsedataobjektet:

Skapa händelsehubbar

Om du inte redan har en skapar du en händelsehubb. Anslutning till händelsehubben kan hanteras via Azure-portalen, programmatiskt med C# eller Python eller med Azure Resource Manager-mallen.

Anmärkning

  • Möjligheten att dynamiskt lägga till partitioner när du har skapat en händelsehubb är endast tillgänglig med Event Hubs Premium- och Dedikerade nivåer. Tänk på den långsiktiga skalan när du anger partitionsantal.
  • Konsumentgruppen måste vara unik per konsument. Skapa en konsumentgrupp som är dedikerad till Azure Data Explorer-anslutning.

Dataanslutning mellan regioner i Event Hubs

För bästa prestanda skapar du händelsehubben i samma region som klustret. Om detta inte är möjligt kan du överväga att använda premium - eller dedikerade Event Hubs-nivåer. En jämförelse av nivåerna finns i Jämför Azure Event Hubs-nivåer.

Skicka händelser

Se exempelappen som genererar data och skickar dem till en händelsehubb.

Anmärkning

Undvik en obalanserad distribution av händelser mellan partitioner för att möjliggöra effektiv bearbetning av händelser från Event Hubs till Azure Data Explorer. Ojämn mappning kan orsaka en hög identifieringsfördröjning. Mer information finns i Mappning av händelser till partitioner.

Konfigurera geo-katastrofåterställningslösning

Event-hubb erbjuder en lösning för geografisk katastrofåterställning. Azure Data Explorer stöder Alias inte händelsehubbens namnområden. Om du vill implementera geo-återställning vid katastrofer i din lösning, bör du skapa två dataanslutningar för event hub: en för det primära namnområdet och en för det sekundära namnområdet. Azure Data Explorer lyssnar på båda event hub-anslutningarna.

Anmärkning

Det är användarens ansvar att åtgärda en failover från det primära namnområdet till det sekundära namnområdet.

Relaterat innehåll