Condividi tramite

Connessione dati di Hub eventi di Azure

  • Articolo

Hub eventi di Azure è una piattaforma di streaming di Big Data e un servizio di inserimento di 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. 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 Hub eventi deve essere a conoscenza del 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 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 Esplora dati

  • 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 Hub eventi di Azure Ricevitore dati.
    3. Impostare criteri di identità gestiti nei database di destinazione.
    4. Creare una connessione dati usando l'autenticazione dell'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 risorsa stringa di connessione, ad esempio il Hub eventi di Azure stringa di connessione. Azure Esplora dati ottiene il stringa di connessione della risorsa per la risorsa specificata e lo salva in modo sicuro. Il stringa di connessione viene quindi usato 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.
  • Hub eventi di Azure Registro schemi 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à di Hub eventi

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

  • 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 di Hub eventi, usato 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 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à distinguono tra maiuscole e minuscole.

Proprietà Descrizione
Database Il nome che è sensibile alle maiuscole 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.
IngestionMappingReference Nome del mapping di inserimento esistente da usare. 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.
RawHeaders Indica che l'origine evento è Kafka e Azure Esplora dati devono usare la deserializzazione della matrice di byte per leggere altre proprietà di routing. 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, il periodo di ricerca 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 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 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 Esplora dati di Azure, vedere 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 portale di Azure, con GLI SDK di gestione C# o Python o con 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à 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à Table, Format, Compression e mapping 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 Hub eventi

Le proprietà di sistema sono campi impostati dal servizio Hub eventi, al momento dell'accodamento dell'evento. Azuer Esplora dati connessione dati di Hub eventi può incorporare un set predefinito di proprietà di sistema nei dati inseriti in una tabella in base a un determinato mapping.

Nota

  • Le proprietà di sistema di incorporamento sono supportate per i formati json e tabulari ( ad esempio JSON, CSVTSVPSVMultiJSON, SCsv, ). TSVESOHsv
  • 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 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 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-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 Scarto 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 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 hub IoT proprietà di sistema nel payload. Per l'elenco completo, vedere hub IoT proprietà di sistema.

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 mapping 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 Acquisizione di Hub eventi

Un modo per usare i dati di 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 a Hub eventi. È consigliabile progettare lo schema della tabella di destinazione tenendo presente questa differenza. In particolare, il payload dell'evento viene rappresentato nel file di acquisizione come matrice di byte e questa matrice non viene decodificata automaticamente dalla Griglia di eventi Connessione dati di Esplora dati di Azure. Per altre informazioni sullo schema di file per i dati di acquisizione avro di 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 usare uno dei metodi seguenti per incorporare proprietà personalizzate nei dati nella body sezione dell'oggetto dati dell'evento:

  • In Hub eventi, quando si crea l'oggetto dati dell'evento, incorporare le proprietà personalizzate come parte dei dati nella body sezione dell'oggetto .
  • Usare Analisi di flusso di Azure per elaborare gli eventi dall'hub eventi e incorporare le proprietà personalizzate nei dati dell'evento. Da Analisi di flusso di Azure è possibile inserire i dati in modo nativo usando il connettore di output di Azure Esplora dati oppure instradare i dati in un altro hub eventi e da lì nel cluster.
  • Usare Funzioni di Azure per aggiungere le proprietà personalizzate e quindi inserire i dati.

Creare 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 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 consumer dedicato alla connessione Esplora dati di Azure.

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 Hub eventi ad Azure Esplora dati, evitare una distribuzione sbilanciata degli eventi tra partizioni. Il mapping non uniforme può causare una latenza di individuazione elevata. Per altre informazioni, vedere Mapping degli eventi alle partizioni.

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

Contenuto correlato