Condividi tramite

Connessione dati di Hub eventi di Azure

Hub eventi di Azure è una piattaforma di streaming di Big Data e un servizio di inserimento di eventi. Azure Data Explorer offre l'ingestione continua da Event Hubs gestiti dal cliente.

La pipeline di acquisizione di Event Hubs trasferisce gli eventi ad Azure Data Explorer in diversi passaggi. Prima di tutto si crea un hub eventi nel portale di Azure. Creare quindi una tabella di destinazione in Azure Esplora dati in cui i dati in un formato specifico vengono inseriti usando le proprietà di inserimento fornite. La connessione di Event Hubs deve tenere conto dell'instradamento degli eventi. I dati possono essere incorporati con proprietà selezionate in base alle proprietà del sistema eventi. Creare una connessione a Hub eventi per creare un hub eventi e inviare eventi. Questo processo può essere gestito tramite il portale di Azure, a livello di codice con C# o Python oppure con il modello di Azure Resource Manager.

Per informazioni generali sull'inserimento dati in Azure Esplora dati, vedere Panoramica dell'inserimento di dati in Azure Esplora dati.

Opzioni di autenticazione della connessione dati di Azure Data Explorer

  • Connessione dati basata su identità gestita (scelta consigliata): l'uso di una connessione dati basata sull'identità gestita è il modo più sicuro per connettersi alle origini dati. Offre il controllo completo sulla possibilità di recuperare i dati da un'origine dati. L'installazione di una connessione dati tramite l'identità gestita richiede i passaggi seguenti:

    1. Aggiungere un'identità gestita al cluster.
    2. Concedere le autorizzazioni all'identità gestita nell'origine dati. Per recuperare i dati da Hub eventi di Azure, l'identità gestita deve disporre delle autorizzazioni di Hub eventi di Azure Ricevitore di dati.
    3. Impostare criteri di identità gestiti nei database di destinazione.
    4. Creare una connessione dati usando l'autenticazione di identità gestita per recuperare i dati.

    Attenzione

    Se le autorizzazioni dell'identità gestita vengono rimosse dall'origine dati, la connessione dati non funzionerà più e non sarà più in grado di recuperare i dati dall'origine dati.

  • Connessione dati basata su chiave: se non viene specificata un'autenticazione basata su identità gestita per la connessione dati, per impostazione predefinita la connessione viene automaticamente eseguita con l'autenticazione basata su chiave. Le connessioni basate su chiave recuperano i dati usando una stringa di connessione della risorsa, come la stringa di connessione di Azure Event Hubs. Azure Data Explorer ottiene la stringa di connessione della risorsa per la risorsa specificata e la salva in modo sicuro. La stringa di connessione viene quindi usata per recuperare i dati dall'origine dati.

    Attenzione

    Se la chiave viene ruotata, la connessione dati non funzionerà più e non sarà in grado di recuperare i dati dall'origine dati. Per risolvere il problema, aggiornare o ricreare la connessione dati.

Formato dati

Nota

  • L'inserimento da Hub eventi non supporta il formato RAW.
  • Registro degli schemi di Azure Event Hubs e Avro senza schema non sono supportati.
  • I dati possono essere compressi usando l'gzipalgoritmo di compressione. È possibile specificare Compression in modo dinamico usando le proprietà di inserimento o nelle impostazioni di connessione dati statica.
  • La compressione dei dati non è supportata per i formati binari (Avro, ApacheAvro, Parquet, ORC e W3CLOGFILE).
  • La codifica personalizzata e le proprietà di sistema incorporate non sono supportate con formati binari e dati compressi.
  • Quando si usano formati binari (Avro, ApacheAvro, Parquet, ORC e W3CLOGFILE) e mapping di inserimento, l'ordine dei campi nella definizione del mapping di inserimento deve corrispondere all'ordine delle colonne corrispondenti nella tabella.

Proprietà degli Event Hubs

Azure Data Explorer supporta le proprietà seguenti di Event Hubs:

  • Set chiuso di proprietà di inserimento, che consente di instradare l'evento alla tabella pertinente.
  • Set chiuso di proprietà del sistema eventi, che possono essere incorporate nei dati in base a un determinato mapping.

Nota

L'inserimento di proprietà personalizzate degli Hub eventi, usate per associare i metadati agli eventi, non è supportato. Se è necessario inserire proprietà personalizzate, inviarle nel corpo dei dati dell'evento. Per altre informazioni, vedere Inserire proprietà personalizzate.

Proprietà di acquisizione

Le proprietà di inserimento indicano al processo di inserimento dove indirizzare i dati e come elaborarli. È possibile specificare le proprietà di inserimento degli eventi usando EventData.Properties. È possibile impostare le proprietà seguenti:

Nota

I nomi delle proprietà sono sensibili alle maiuscole.

Proprietà Descrizione
Base di dati Il nome "case-sensitive" del database di destinazione. Per impostazione predefinita, i dati vengono inseriti nel database di destinazione associato alla connessione dati. Utilizzare questa proprietà per eseguire l'override del database predefinito e inviare dati a un database diverso. A tale scopo, è prima necessario configurare la connessione come connessione multi-database.
Tabella Nome con distinzione tra maiuscole e minuscole della tabella di destinazione esistente. Esegue l'override del set Table nel riquadro Data Connection.
Formato Formato dati. Esegue l'override del set Data format nel riquadro Data Connection.
Riferimento alla Mappatura dell'Ingestione Nome del mapping di inserimento esistente da utilizzare. Esegue l'override del set Column mapping nel riquadro Data Connection.
Compressione Compressione dei dati, None (impostazione predefinita) o gzip.
Codifica Codifica dei dati, l'impostazione predefinita è UTF8. Può essere una delle codifiche supportate da .NET.
Tag Elenco di tag da associare ai dati inseriti, formattati come stringa di matrici JSON. Esistono implicazioni per le prestazioni quando si usano i tag.
Intestazioni non elaborate Indica che la sorgente dell'evento è Kafka e Azure Data Explorer deve usare la deserializzazione dell'array di byte per leggere altre proprietà di instradamento. Il valore viene ignorato.

Nota

Solo gli eventi accodati dopo aver creato la connessione dati vengono inseriti, a meno che non venga specificata una data di inizio personalizzata per il recupero. In ogni caso, l'intervallo di revisione non può superare il periodo di conservazione effettivo dell'Hub Eventi.

Routing degli eventi

Quando si crea una connessione dati al cluster, è possibile specificare il routing dove inviare i dati acquisiti. Il routing predefinito è verso la tabella di destinazione specificata nella stringa di connessione associata al database di destinazione. Il routing predefinito per i dati viene anche chiamato routing statico. È possibile specificare opzioni di routing ed elaborazione alternative per i dati impostando una o più proprietà dei dati dell'evento indicate nel paragrafo precedente.

Nota

La connessione dati di Hub eventi tenterà di elaborare tutti gli eventi letti dall'hub eventi e ogni evento che non può elaborare per qualsiasi motivo verrà segnalato come errore di inserimento. Per informazioni su come monitorare l'inserimento in Azure Data Explorer, clicca qui.

Instradare i dati degli eventi a un database alternativo

Il routing dei dati a un database alternativo è disattivato per impostazione predefinita. Per inviare i dati a un database diverso, è prima necessario impostare la connessione come connessione multi-database. Questa funzionalità può essere abilitata nel portale di Azure, con gli SDK di gestione C# o Python o con un modello ARM. L'utente, il gruppo, l'entità servizio o l'identità gestita utilizzata per consentire il routing del database deve avere almeno il ruolo collaboratore e le autorizzazioni di scrittura nel cluster.

Per specificare un database alternativo, impostare la proprietà Inserimento database.

Avviso

Se si specifica un database alternativo senza impostare la connessione come connessione dati multi-database, l'inserimento avrà esito negativo.

Instradare i dati degli eventi a una tabella alternativa

Per specificare una tabella alternativa per ogni evento, impostare le proprietà di Table, Format, Compression e il mapping delle proprietà di inserimento. La connessione instrada dinamicamente i dati inseriti come specificato in EventData.Properties, ignorando le proprietà statiche per questo evento.

L'esempio seguente illustra come impostare i dettagli dell'hub eventi e inviare i dati delle metriche meteo al database alternativo (MetricsDB) e alla tabella (WeatherMetrics). I dati sono in formato JSON e mapping1 è predefinito nella tabella 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);

Mapping delle proprietà di sistema di Event Hubs

Le proprietà di sistema sono campi impostati dal servizio Event Hubs al momento dell'accodamento dell'evento. La connessione dati di Esplora dati di Azure Hub eventi può integrare un set predefinito di proprietà di sistema nei dati inseriti in una tabella in base a una mappatura specifica.

Nota

  • Le proprietà di sistema di incorporamento sono supportate per i formati json e tabulari ( ad esempio JSON, MultiJSONCSVTSVPSV, SCsv, ). SOHsvTSVE
  • Quando si usa un formato non supportato (i.e. TXT o formati compressi come Parquete Avro così via), i dati verranno comunque inseriti, ma le proprietà verranno ignorate.
  • L'incorporamento delle proprietà di sistema non è supportato quando è impostata una compressione dei messaggi dell'hub eventi. In questi scenari, verrà generato un errore appropriato e i dati non verranno inseriti.
  • Per i dati tabulari le proprietà di sistema sono supportate solo per i messaggi di evento a record singolo.
  • Per i dati JSON, le proprietà di sistema sono supportate anche per i messaggi di evento a più record. In questi casi, le proprietà di sistema vengono aggiunte solo al primo record del messaggio di evento.
  • Per CSV mapping, le proprietà vengono aggiunte all'inizio del record nell'ordine elencato durante la creazione della connessione dati. Non fare affidamento sull'ordine di queste proprietà, perché potrebbe cambiare in futuro.
  • Per il mapping JSON le proprietà vengono aggiunte in base ai nomi delle proprietà nella tabella Proprietà di sistema.

Il servizio Hub eventi espone le proprietà di sistema seguenti:

Proprietà Tipo di dati Descrizione
x-opt-tempo-di-codainserimento datetime Ora UTC in cui l'evento è stato accodato
x-opt-numero-sequenza long Numero di sequenza logica dell'evento all'interno del flusso di partizione dell'hub eventi
x-opt-offset string Scarto dell'evento dal flusso di partizione dell'hub eventi. L'identificatore di offset è univoco all'interno di una partizione del flusso dell'hub degli eventi
x-opt-editore string Nome del server di pubblicazione, se il messaggio è stato inviato a un endpoint del server di pubblicazione
x-opt-partition-key string Chiave di partizione della partizione corrispondente che ha archiviato l'evento

Quando si lavora con gli hub eventi di IoT Central, è anche possibile incorporare le proprietà di sistema di IoT Hub nel payload. Per l'elenco completo, vedere proprietà del sistema dell'IoT Hub.

Se si seleziona Proprietà del sistema per gli eventi nella sezione Origine dati della tabella, è necessario includere le proprietà del sistema nello schema e nel mapping della tabella.

Esempi di mappatura dello schema

Esempio di mapping dello schema di tabella

Se i dati includono tre colonne (TimeStamp, MetricNamee Value) e le proprietà incluse sono x-opt-enqueued-time e x-opt-offset, creare o modificare lo schema della tabella usando questo comando:

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

Esempio di mapping CSV

Eseguire i comandi seguenti per aggiungere dati all'inizio del record. Prendere nota dei valori ordinali.

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

Esempio di mapping JSON

I dati verranno aggiunti usando il mapping delle proprietà di sistema. Eseguire i comandi seguenti:

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

Mapping dello schema per i file Avro di Event Hubs Capture

Un modo per usare i dati di Event Hubs consiste nel memorizzare eventi tramite Azure Event Hubs in Archiviazione di BLOB di Azure o Azure Data Lake Storage. È quindi possibile inserire i file di acquisizione mentre vengono scritti usando una connessione dati di Event Grid in Azure Data Explorer.

Lo schema dei file di acquisizione è diverso dallo schema dell'evento originale inviato a Hub eventi. È consigliabile progettare lo schema della tabella di destinazione tenendo presente questa differenza. In particolare, il payload dell'evento è rappresentato nel file di acquisizione come un array di byte e questo array non viene decodificato automaticamente dalla connessione di dati di Esplora dati di Azure tramite Event Grid. Per ulteriori informazioni sullo schema del file per i dati di acquisizione Avro di gli Hub Eventi, vedere Esplorazione dei file Avro acquisiti in Hub Eventi di Azure.

Per decodificare correttamente il payload dell'evento:

  1. Mappa il campo del Body evento acquisito a una colonna di tipo dynamic nella tabella di destinazione.
  2. Applicare un criterio di aggiornamento che converte la matrice di byte in una stringa leggibile usando la funzione unicode_codepoints_to_string().

Inserire proprietà personalizzate

Quando si inseriscono eventi da Event Hubs, i dati vengono acquisiti dalla sezione body dell'oggetto dati dell'evento. Tuttavia, le proprietà personalizzate di Hub eventi vengono definite nella properties sezione dell'oggetto e non vengono inserite. Per inserire le proprietà dei clienti, è necessario incorporarle nei dati nella sezione dell'oggetto body.

Nell'esempio seguente viene confrontato l'oggetto dati degli eventi contenente la proprietà customProperty personalizzata definitada Hub eventi (a sinistra) con la proprietà incorporata necessaria per l'inserimento (a destra).

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

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

È possibile usare uno dei metodi seguenti per incorporare proprietà personalizzate nei dati nella body sezione dell'oggetto dati dell'evento:

Creare Hub eventi

Se non ne hai già uno, crea un hub eventi. La connessione all'hub eventi può essere gestita tramite il portale di Azure, a livello di codice con C# o Python o con il modello di Azure Resource Manager.

Nota

  • La possibilità di aggiungere partizioni in modo dinamico dopo la creazione di un hub eventi è disponibile solo con i livelli Premium e Dedicato di Hub eventi. Prendere in considerazione la scalabilità a lungo termine quando si imposta il numero di partizioni.
  • Il gruppo di consumer deve essere univoco per ogni consumer. Creare un gruppo di consumatori dedicato per ogni connessione dati di Azure Data Explorer.

Connessione dati di Hub eventi tra aree

Per ottenere prestazioni ottimali, creare l'hub eventi nella stessa area del cluster. Se non è possibile, è consigliabile usare i livelli Premium o Hub eventi dedicati . Per un confronto dei livelli, vedere Confrontare i livelli Hub eventi di Azure.

Inviare gli eventi

Vedere l'app di esempio che genera i dati e li invia a un hub eventi.

Nota

Per consentire un'elaborazione efficiente degli eventi da Event Hubs ad Azure Data Explorer, evitare una distribuzione sbilanciata degli eventi fra le partizioni. Il mapping non uniforme può causare una latenza di individuazione elevata. Per ulteriori informazioni, vedere Mappatura degli eventi alle partizioni.

Configurare la soluzione di ripristino di emergenza geografica

Hub eventi offre una soluzione di ripristino in caso di disastri geografici. Azure Esplora Dati non supporta Alias spazi dei nomi degli hub eventi. Per implementare il ripristino di emergenza geografico nella soluzione, creare due connessioni dati dell'hub eventi: una per lo spazio dei nomi primario e una per lo spazio dei nomi secondario. Azure Data Explorer è in ascolto di entrambe le connessioni di Event Hub.

Nota

È responsabilità dell'utente implementare un failover dallo spazio dei nomi primario allo spazio dei nomi secondario.

Contenuto correlato