Connessione dati di Hub eventi di Azure

  • Articolo

Hub eventi di Azure è una piattaforma di streaming Big Data e un servizio di inserimento eventi. Azure Esplora dati offre l'inserimento continuo da Hub eventi gestiti dal cliente.

La pipeline di inserimento di Hub eventi trasferisce gli eventi ad Azure Esplora dati in diversi passaggi. Per prima cosa si crea un hub eventi nel portale di Azure. Si crea quindi una tabella di destinazione in Azure Esplora dati in cui i dati in un formato specifico verranno inseriti usando le proprietà di inserimento indicate. La connessione di Hub eventi deve conoscere il routing 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 o con il modello di Resource Manager di Azure.

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

Meccanismi di autenticazione della connessione dati di Azure Esplora dati

Attenzione

Se le autorizzazioni di identità gestite vengono rimosse dall'origine dati, la connessione dati è disabilitata e non può recuperare i dati dall'origine dati.

  • Connessione dati basata su chiavi: se un'identità gestita non è specificata nella connessione dati, la connessione viene automaticamente predefinita per l'autenticazione basata su chiavi. Le connessioni basate sulle chiavi recuperano i dati usando una risorsa stringa di connessione, ad esempio la Hub eventi di Azure stringa di connessione. Azure Esplora dati genera la risorsa stringa di connessione per la risorsa specificata e la salva in modo sicuro nella connessione dati. Il stringa di connessione viene quindi usato per recuperare i dati dall'origine dati.

Attenzione

Se la chiave viene ruotata, la connessione dati è disabilitata e non può recuperare i dati dall'origine dati. Per risolvere il problema, aggiornare o ricreare la connessione dati.

Formato dati

  • I dati sono letti dall'hub eventi sotto forma di oggetti EventData .

  • Vedere formati supportati.

    Nota

  • I dati possono essere compressi usando l'algoritmo GZip di compressione. È possibile specificare Compression in modo dinamico usando le proprietà di inserimento o nelle impostazioni di connessione dati statiche.

    Nota

    La compressione dei dati non è supportata per i formati compressi (Avro, Parquet, ORC, ApacheAvro e W3CLOGFILE). La codifica personalizzata e le proprietà del sistema incorporato non sono supportate nei dati compressi.

Proprietà di Hub eventi

Azure Esplora dati supporta le proprietà di Hub eventi seguenti:

Nota

L'inserimento di proprietà personalizzate di 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 inserimento

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

Nota

I nomi delle proprietà distinguono tra maiuscole e minuscole.

Proprietà Descrizione
Database Nome con distinzione tra maiuscole e minuscole del database di destinazione. Per impostazione predefinita, i dati vengono inseriti nel database di destinazione associato alla connessione dati. Usare 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 a più database.
Tabella Nome con distinzione tra maiuscole e minuscole della tabella di destinazione esistente. Esegue l'override del Table set nel Data Connection riquadro.
Formato Formato dati. Esegue l'override del Data format set nel Data Connection riquadro.
InserimentoMappingReference Nome del mapping di inserimento esistente da usare. Esegue l'override del Column mapping set nel Data Connection riquadro.
Compressione Compressione dei dati, None (impostazione predefinita) o GZip compressione.
Codifica La codifica dei dati, il valore predefinito è UTF8. Può essere una delle codifiche supportate da .NET.
Tag Elenco di tag da associare ai dati inseriti, formattati come stringa di matrice JSON. Esistono implicazioni sulle prestazioni quando si usano i tag.
RawHeaders Indica che l'origine eventi è Kafka e Azure Esplora dati deve usare la deserializzazione della matrice byte per leggere altre proprietà di routing. Il valore viene ignorato.

Nota

Vengono inseriti solo gli eventi accodati dopo aver creato la connessione dati.

Routing eventi

Quando si crea una connessione dati al cluster, è possibile specificare il routing per dove inviare dati inseriti. Il routing predefinito è la tabella di destinazione specificata nella stringa di connessione associata al database di destinazione. Il routing predefinito per i dati viene definito anche routing statico. È possibile specificare un routing alternativo per i dati impostando le proprietà dei dati dell'evento indicate in precedenza.

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 a più database. È possibile eseguire questa operazione nel portale di Azure portale di Azure, C#, Python o un modello di Resource Manager. L'utente, il gruppo, l'entità servizio o l'identità gestita usata 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à Inserimentodatabase.

Avviso

Se si specifica un database alternativo senza impostare la connessione come connessione a più database, l'inserimento avrà esito negativo.

Instradare i dati dell'evento a una tabella alternativa

Per specificare una tabella alternativa per ogni evento, impostare le proprietàTable, Format, Compression e mapping. 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 a un database alternativo (MetricsDB) e a una 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à del sistema per gli eventi

Le proprietà di sistema archiviano le proprietà impostate dal servizio Hub eventi, al momento dell'accodamento dell'evento. La connessione dati all'hub eventi può incorporare un set selezionato di proprietà di sistema nei dati inseriti in una tabella in base a un determinato mapping.

Nota

  • L'incorporamento delle proprietà di sistema è supportato per i formati json e tabulari ( ad esempio JSON, , MultiJSONCSV, SOHsvTSVPSVSCsvTSVE).
  • 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 viene 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 il mapping, le proprietà vengono aggiunte all'inizio del record nell'ordine elencato nella creazione della connessione dati. Non basarsi sull'ordine di queste proprietà, perché potrebbe cambiare in futuro.
  • Per JSON il mapping, le proprietà vengono aggiunte in base ai nomi delle proprietà nella tabella Delle proprietà di sistema .

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

Proprietà Tipo di dati Descrizione
x-opt-enqueued-time datetime Ora UTC in cui l'evento è stato accodato
x-opt-sequence-number long Numero di sequenza logica dell'evento all'interno del flusso di partizione dell'hub eventi
x-opt-offset string Offset dell'evento dal flusso di partizione dell'hub eventi. L'identificatore di offset è univoco all'interno di una partizione del flusso dell'hub eventi
x-opt-publisher string Nome dell'editore, 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 hub eventi di IoT Central, è anche possibile incorporare hub IoT proprietà di sistema nel payload. Per l'elenco completo, vedere hub IoT proprietà di sistema.

Se nella sezione Origine dati della tabella sono state selezionate le proprietà del sistema eventi, è necessario includere le proprietà nello schema della tabella e nel mapping.

Esempi di mapping dello schema

Esempio di mapping dello schema di tabella

Se i dati includono tre colonne (Timespan, Metrice 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, Metric: 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" : "Timespan", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "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 questi comandi:

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

Mapping dello schema per i file Avro dell'acquisizione di Hub eventi

Un modo per usare i dati dell'hub eventi consiste nell'acquisire eventi tramite Hub eventi di Azure in Archiviazione BLOB di Azure o Azure Data Lake Storage. È quindi possibile inserire i file di acquisizione mentre vengono scritti usando una connessione dati di Griglia di eventi in Azure Esplora dati.

Lo schema dei file di acquisizione è diverso dallo schema dell'evento originale inviato all'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 matrice di byte e questa matrice non viene decodificata automaticamente dalla connessione dati di Griglia di eventi di Azure Esplora dati. Per informazioni più specifiche sullo schema di file per i dati di acquisizione avro dell'hub eventi, vedere Esplorazione dei file Avro acquisiti in Hub eventi di Azure.

Per decodificare correttamente il payload dell'evento:

  1. Eseguire il mapping del Body campo dell'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 Hub eventi, i dati vengono acquisiti dalla body sezione 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 body sezione dell'oggetto .

Nell'esempio seguente viene confrontato l'oggetto dati degli eventi contenente la proprietà customProperty personalizzata definita da 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 utilizzare uno dei metodi seguenti per incorporare proprietà personalizzate nei dati nella body sezione dell'oggetto dati dell'evento:

Connessione dati di Hub eventi tra aree

Per ottenere prestazioni ottimali, creare tutte le risorse seguenti nella stessa area del cluster. Se non esiste un'altra alternativa, prendere in considerazione l'uso di livelli Di Hub eventi Premium o Dedicato . Il confronto tra i livelli di Hub eventi è disponibile qui.

Creare un hub eventi

Se non è già disponibile, creare 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 Resource Manager di Azure.

Nota

  • La possibilità di aggiungere partizioni in modo dinamico dopo la creazione di un hub eventi è disponibile solo con i livelli Premium e Dedicati di Hub eventi. Quando si imposta il numero di partizioni, considerare la scalabilità a lungo termine.
  • Il gruppo di consumer deve essere univoco per ogni consumer. Creare un gruppo di consumer dedicato alla connessione Esplora dati di Azure.

Inviare eventi

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

Per un esempio di come generare dati di esempio, vedere Inserire dati dall'hub eventi in Azure Esplora dati

Configurare la soluzione di ripristino di emergenza geografico

Hub eventi offre una soluzione di ripristino di emergenza geografico . Azure Esplora dati non supporta Alias gli spazi dei nomi dell'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 Esplora dati sarà in ascolto di entrambe le connessioni dell'hub eventi.

Nota

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

Contenuti correlati