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 eventhubbar.

Event Hubs-inmatningspipelinen överför händelser till Azure Data Explorer i flera steg. Först skapar du en händelsehubb i Azure Portal. Sedan skapar du 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 känna till händelsedirigering. Data kan bäddas in med valda egenskaper enligt egenskaperna för händelsesystemet. 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.

Autentiseringsmekanismer för Azure Data Explorer-dataanslutning

Varning

Om behörigheterna för den hanterade identiteten tas bort från datakällan inaktiveras dataanslutningen och kan inte hämta data från datakällan.

  • Nyckelbaserad dataanslutning: Om en hanterad identitet inte anges i dataanslutningen används nyckelbaserad autentisering automatiskt som standard. Nyckelbaserade anslutningar hämtar data med hjälp av en resurs anslutningssträng, till exempel Azure Event Hubs anslutningssträng. Azure Data Explorer genererar resursen anslutningssträng för den angivna resursen och sparar den säkert i dataanslutningen. Den anslutningssträng används sedan för att hämta data från datakällan.

Varning

Om nyckeln roteras inaktiveras 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.

    Anteckning

  • 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.

    Anteckning

    Datakomprimering stöds inte för komprimerade format (Avro, Parquet, ORC, ApacheAvro och W3CLOGFILE). Anpassade kodnings- och inbäddade systemegenskaper stöds inte på komprimerade data.

Event Hubs-egenskaper

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

Anteckning

Inmatning av anpassade event hubs-egenskaper, 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:

Anteckning

Egenskapsnamn är skiftlägeskänsliga.

Egenskap 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 om du vill å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 uppsättningen Table i fönstret Data Connection .
Format Dataformat. Åsidosätter uppsättningen Data format i fönstret Data Connection .
IngestionMappingReference Namnet på den befintliga inmatningsmappningen som ska användas. Åsidosätter uppsättningen Column mapping i fönstret Data Connection .
Komprimering Datakomprimering ( None standard) eller GZip komprimering.
Kodning Datakodning, standardvärdet är UTF8. Kan vara någon av .NET-kodningar som stöds.
Taggar En lista med taggar som ska associeras med inmatade data, formaterade 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 deserialisering av bytematris för att läsa andra routningsegenskaper. Värdet ignoreras.

Anteckning

Endast händelser som placeras i kö när du har skapat dataanslutningen matas in.

Händelsedirigering

När du skapar en dataanslutning till klustret kan du ange routningen för vart inmatade data ska skickas. Standardroutningen är till måltabellen som anges i anslutningssträng som är associerad med måldatabasen. Standardroutningen för dina data kallas även statisk routning. Du kan ange en alternativ routning för dina data genom att ange egenskaperna för händelsedata som nämns ovan.

Dirigera händelsedata till en alternativ databas

Att dirigera data till en alternativ databas är inaktiverat som standard. Om du vill skicka data till en annan databas måste du först ange anslutningen som en anslutning med flera databaser. Du kan göra detta i Azure Portal Azure Portal, C#, Python eller 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 egenskapen Databasinmatning 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 kommer inmatningen att misslyckas.

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 information om händelsehubben och skickar vädermåttdata till en alternativ databas (MetricsDB) och en 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 egenskaper för händelsesystem

Systemegenskaper lagrar egenskaper som anges av Event Hubs-tjänsten när händelsen placeras i kö. Dataanslutningen till händelsehubben kan bädda in en vald uppsättning systemegenskaper i de data som matas in i en tabell baserat på en viss mappning.

Anteckning

  • 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 har angetts. I sådana scenarier genereras ett lämpligt fel och data matas inte in.
  • För tabelldata stöds systemegenskaper endast för händelsemeddelanden med en 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å de här egenskaperna eftersom den 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:

Egenskap Datatyp Beskrivning
x-opt-enqueued-time datetime UTC-tid när händelsen köades
x-opt-sequence-number 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 partitionsström. Förskjutningsidentifieraren är unik inom en partition i 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. En fullständig lista finns i IoT Hub systemegenskaper.

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å mappning av tabellscheman

Om dina data innehåller tre kolumner (Timespan, Metricoch 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, Metric: 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" : "Timespan", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "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 dessa kommandon:

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

Schemamappning för Event Hub Capture Avro-filer

Ett sätt att använda Event Hub-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 Händelsehubb. 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 Event Grid Azure Data Explorer dataanslutning. Mer specifik information om filschemat för Event Hub Avro-avbildningsdata finns i Utforska avbildade Avro-filer i Azure Event Hubs.

Så här avkodar du händelsenyttolasten korrekt:

  1. Mappa fältet för Body den avbildade 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().

Mata in 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 egenskapen 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:

Händelsehubbdataanslutning mellan regioner

För bästa prestanda skapar du alla följande resurser i samma region som klustret. Om det inte finns något annat alternativ kan du överväga att använda premium - eller dedikerade eventhubbsnivåer. Jämförelse av Event Hub-nivåer finns här.

Skapa en händelsehubb

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

Anteckning

  • 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 Dedicated-nivåer. Överväg den långsiktiga skalningen när du anger antal partitioner.
  • Konsumentgruppen måste vara unik per konsument. Skapa en konsumentgrupp som är dedikerad till Azure Data Explorer-anslutning.

Skicka händelser

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

Ett exempel på hur du genererar exempeldata finns i Mata in data från händelsehubben till Azure Data Explorer

Konfigurera en lösning för geo-haveriberedskap

Händelsehubben erbjuder en lösning för geo-haveriberedskap . Azure Data Explorer stöder Alias inte namnrymder för händelsehubben. Om du vill implementera geo-haveriberedskap i din lösning skapar du två dataanslutningar för händelsehubben: 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.

Anteckning

Det är användarens ansvar att implementera en redundansväxling från det primära namnområdet till det sekundära namnområdet.

Relaterat innehåll