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. Creare prima un hub eventi nella 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 a 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 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.

Meccanismi di autenticazione della connessione dati Esplora dati di Azure

  • 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

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

  • Vedere i formati supportati.

    Nota

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

    Nota

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

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

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

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 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 multi-database. È possibile eseguire questa operazione nel portale di Azure portale di Azure, C#, Python o in 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à 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

  • 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 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 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 (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 i comandi seguenti:

    .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 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 connessione dati di Griglia di eventi di Azure Esplora dati. Per informazioni più specifiche 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 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:

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

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, è consigliabile usare i livelli Premium o Hub eventi dedicati . Il confronto dei 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 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.

Inviare gli 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 ascolterà 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