Connexion de données Azure Event Hubs

  • Article

Azure Event Hubs est une plateforme de streaming de Big Data et un service d’ingestion d’événements. Azure Data Explorer offre une ingestion continue à partir des hubs d’événements gérés par le client.

Le pipeline d’ingestion Event Hubs transfère les événements à Azure Data Explorer en plusieurs étapes. Commencez par créer un hub d’événements dans le portail Azure. Vous créez ensuite une table cible dans Azure Data Explorer, dans laquelle les données d’un format particulier sont ingérées à l’aide des propriétés d’ingestion indiquées. La connexion Event Hubs doit connaître le routage des événements. Les données peuvent être incorporées avec des propriétés sélectionnées en fonction des propriétés du système d’événements. Créez une connexion à Event Hubs pour créer un hub d’événements et envoyer des événements. Ce processus peut être géré par le biais du portail Azure, programmatiquement avec C# ou Python, ou avec le modèle Azure Resource Manager.

Pour obtenir des informations générales sur l’ingestion de données dans Azure Data Explorer, consultez Vue d’ensemble de l’ingestion des données dans Azure Data Explorer.

Mécanismes d’authentification de connexion de données Azure Data Explorer

Attention

Si les autorisations d’identité managée sont supprimées de la source de données, la connexion de données est désactivée et ne peut pas extraire de données de la source de données.

  • Connexion de données basée sur des clés : si une identité managée n’est pas spécifiée dans la connexion de données, la connexion est automatiquement définie par défaut sur l’authentification basée sur des clés. Les connexions basées sur des clés extraient des données à l’aide d’une chaîne de connexion de ressource, telle que la chaîne de connexion Azure Event Hubs. Azure Data Explorer génère la chaîne de connexion de ressource pour la ressource spécifiée et l’enregistre en toute sécurité dans la connexion de données. La chaîne de connexion est ensuite utilisée pour extraire des données de la source de données.

Attention

Si la clé est pivotée, la connexion de données est désactivée et ne peut pas extraire de données de la source de données. Pour résoudre le problème, mettez à jour ou recréez la connexion de données.

Format de données

  • Les données sont lues à partir du hub d’événements sous forme d’objets EventData.

  • Examinez les formats pris en charge.

    Notes

  • Les données peuvent être compressées en utilisant l’algorithme de compression GZip. Vous pouvez spécifier Compression de manière dynamique avec des propriétés d’ingestion ou dans les paramètres de connexion de données statiques.

    Notes

    La compression des données n’est pas prise en charge pour les formats compressés (Avro, Parquet, ORC, ApacheAvro et W3CLOGFILE). L’encodage personnalisé et les propriétés système incorporées ne sont pas pris en charge sur les données compressées.

Propriétés d’Event Hubs

Azure Data Explorer prend en charge les propriétés d’Event Hubs suivantes :

Notes

L’ingestion de propriétés personnalisées d’Event Hubs, utilisées pour associer des métadonnées à des événements, n’est pas prise en charge. Si vous devez ingérer des propriétés personnalisées, envoyez-les dans le corps des données d’événement. Pour plus d’informations, consultez Ingérer des propriétés personnalisées.

Propriétés d’ingestion

Les propriétés d’ingestion déterminent le processus d’ingestion, où router les données et comment les traiter. Vous pouvez spécifier les propriétés d’ingestion de l’ingestion des événements avec EventData.Properties. Vous pouvez définir les propriétés suivantes :

Notes

Les noms de propriété respectent la casse.

Propriété Description
Base de données Nom de la base de données cible, respectant la casse. Par défaut, les données sont ingérées dans la base de données cible associée à la connexion de données. Utilisez cette propriété pour remplacer la base de données par défaut et envoyer les données à une autre base de données. Pour ce faire, vous devez d’abord configurer la connexion en tant que connexion à plusieurs bases de données.
Table de charge de travail Nom de la table cible existante, respectant la casse. Remplace le paramètre Table défini dans le volet Data Connection.
Format Format de données. Remplace le paramètre Data format défini dans le volet Data Connection.
IngestionMappingReference Nom du mappage d’ingestion existant à utiliser. Remplace le paramètre Column mapping défini dans le volet Data Connection.
Compression Compression de données, None (par défaut) ou compression GZip.
Encodage Encodage des données, la valeur par défaut est UTF8. Il peut s’agir de l’un des encodages pris en charge par .NET.
Étiquettes Liste d’étiquettes à associer aux données ingérées, sous forme de chaîne de tableau JSON. L’utilisation d’étiquettes a des répercussions sur les performances.
RawHeaders Indique que la source de l’événement est Kafka et Azure Data Explorer doivent utiliser la désérialisation du tableau d’octets pour lire d’autres propriétés de routage. La valeur est ignorée.

Notes

Seuls les événements mis en file d’attente après que vous avez créé la connexion de données sont ingérés.

Routage d’événements

Quand vous créez une connexion de données à votre cluster, vous pouvez spécifier le routage pour l’emplacement où les données ingérées doivent être envoyées. Le routage par défaut se fait vers la table cible spécifiée dans la chaîne de connexion associée à la base de données cible. Le routage par défaut de vos données est également appelé routage statique. Vous pouvez spécifier un autre routage pour vos données en définissant les propriétés des données d’événement mentionnées ci-dessus.

Router les données d’événement vers une autre base de données

Par défaut, le routage des données vers une autre base de données est désactivé. Pour envoyer les données vers une autre base de données, vous devez d’abord définir la connexion en tant que connexion à plusieurs bases de données. Vous pouvez le faire en utilisant le portail Azure, C#, Python ou un modèle ARM. L’utilisateur, le groupe, le principal de service ou l’identité managée utilisé pour autoriser le routage de la base de données doit disposer au minimum du rôle Contributeur et d’autorisations d’écriture sur le cluster.

Pour spécifier une autre base de données, définissez la propriété d’ingestion de la base de données.

Avertissement

Spécifier une autre base de données sans définir la connexion en tant que connexion de données à plusieurs bases de données entraîne l’échec de l’ingestion.

Router les données d’événement vers une autre table

Pour spécifier une autre table pour chaque événement, définissez la Table, le Format, la Compression et le mappage des propriétés d’ingestion. La connexion route dynamiquement les données ingérées comme spécifié dans EventData.Properties, remplaçant les propriétés statiques pour cet événement.

L’exemple suivant montre comment définir les détails du hub d’événements et envoyer des données de métriques météorologiques à une autre base de données (MetricsDB) et à une autre table (WeatherMetrics). Les données sont au format JSON et mapping1 est prédéfini sur la table 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);

Mappage des propriétés du système d’événements

Les propriétés système stockent les propriétés définies par le service Event Hubs, au moment de la mise en file d’attente de l’événement. La connexion de données au hub d’événements peut incorporer un ensemble sélectionné de propriétés système dans les données ingérées dans une table en fonction d’un mappage donné.

Notes

  • L’incorporation des propriétés système est prise en charge pour les formats JSON et tabulaires (c’est-à-dire JSON, MultiJSON, CSV, TSV, PSV, SCsv, SOHsv, TSVE).
  • Lorsque vous utilisez un format non pris en charge (par exemple, TXT ou des formats compressés comme Parquet, Avro, etc.), les données sont quand même ingérées, mais les propriétés sont ignorées.
  • L’incorporation de propriétés système n’est pas prise en charge quand une compression de messages Event Hub est définie. Dans de tels scénarios, une erreur appropriée est émise et les données ne sont pas ingérées.
  • Pour les données tabulaires, les propriétés système sont prises en charge uniquement pour les messages d’événements à enregistrement unique.
  • Pour les données JSON, les propriétés système sont également prises en charge pour les messages d’événements à enregistrements multiples. Dans ce cas, les propriétés système sont ajoutées uniquement au premier enregistrement du message d’événement.
  • Pour CSV le mappage, les propriétés sont ajoutées au début de l’enregistrement dans l’ordre indiqué dans la création de la connexion de données. Ne vous fiez pas à l’ordre de ces propriétés, car il peut changer à l’avenir.
  • Pour un mappage JSON, des propriétés sont ajoutées en fonction des noms de propriété dans la table Propriétés système.

Le service Event Hubs expose les propriétés système suivantes :

Propriété Type de données Description
x-opt-enqueued-time datetime Heure UTC à laquelle l’événement a été mis en file d’attente
x-opt-sequence-number long Numéro de séquence logique de l’événement dans le flux de partition du hub d’événements
x-opt-offset string Décalage de l’événement par rapport au flux de partition du hub d’événements. L’identificateur de décalage est unique au sein d’une partition du flux du hub d’événements
x-opt-publisher string Nom de l’éditeur, si le message a été envoyé à un point de terminaison d’éditeur
x-opt-partition-key string Clé de partition de la partition correspondante qui a stocké l’événement

Quand vous utilisez les hubs d’événements IoT Central, vous pouvez également incorporer les propriétés système IoT Hub dans la charge utile. Pour obtenir la liste complète, consultez Propriétés système d’IoT Hub.

Si vous avez sélectionné Propriétés du système d’événements dans la section Source de données de la table, vous devez inclure les propriétés dans le schéma et le mappage de table.

Exemples de mappage de schéma

Exemple de mappage de schéma de table

Si vos données comprennent trois colonnes (Timespan, Metricet Value) et que les propriétés que vous incluez sont x-opt-enqueued-time et x-opt-offset, créez ou modifiez le schéma de table à l’aide de la commande suivante :

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

Exemple de mappage CSV

Exécutez les commandes suivantes pour ajouter des données au début de l’enregistrement. Notez les valeurs ordinales.

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

Exemple de mappage JSON

Les données sont ajoutées à l’aide du mappage des propriétés système. Exécutez les commandes suivantes :

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

Mise en correspondance du schéma pour les fichiers Event Hub Capture Avro

Une façon de consommer des données Event Hub consiste à capturer des événements via Azure Event Hubs dans Stockage Blob Azure ou Azure Data Lake Storage. Vous pouvez ensuite ingérer les fichiers de capture au fur et à mesure qu’ils sont écrits à l’aide d’une connexion de données Event Grid dans Azure Data Explorer.

Le schéma des fichiers de capture est différent du schéma de l’événement d’origine envoyé à Event Hub. Vous devez concevoir le schéma de table de destination en gardant à l’esprit cette différence. Plus précisément, la charge utile d’événement est représentée dans le fichier de capture en tant que tableau d’octets et ce tableau n’est pas décodé automatiquement par la connexion de données Azure Data Explorer Event Grid. Pour plus d’informations sur le schéma de fichier pour les données de capture Event Hub Avro, consultez Explorer les fichiers Avro capturés dans Azure Event Hubs.

Pour décoder correctement la charge utile de l’événement :

  1. Mappez le champ Body de l’événement capturé à une colonne de type dynamic dans la table de destination.
  2. Appliquez une stratégie de mise à jour qui convertit le tableau d’octets en chaîne lisible à l’aide de la fonction unicode_codepoints_to_string().

Ingérer des propriétés personnalisées

Lors de l’ingestion d’événements provenant d’Event Hubs, les données sont extraites de la section body de l’objet de données d’événement. Cependant, les propriétés personnalisées d’Event Hubs sont définies dans la section properties de l’objet et ne sont pas ingérées. Pour ingérer des propriétés personnalisées, vous devez les incorporer dans les données de la section body de l’objet.

L’exemple suivant compare l’objet de données d’événements contenant la propriété personnalisée customProperty telle qu’elle est définie par Event Hubs (à gauche) à la propriété incorporée nécessaire pour l’ingestion (à droite).

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

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

Vous pouvez utiliser une des méthodes suivantes pour incorporer des propriétés personnalisées dans les données, dans la section body de l’objet de données d’événement :

Connexion de données Event Hub entre régions

Pour des performances optimales, créez toutes les ressources suivantes dans la même région que le cluster. S’il n’existe aucune autre alternative, envisagez d’utiliser les niveaux Premium ou Hub d’événements dédiés . La comparaison des niveaux Event Hub est disponible ici.

Créer un hub d’événements

Créez un hub d’événements si vous n’en avez pas déjà un. La connexion au hub d’événements peut être gérée via le portail Azure, par programmation avec C# ou Python, ou avec le modèle Azure Resource Manager.

Notes

  • La possibilité d’ajouter dynamiquement des partitions après la création d’un hub d’événements est disponible uniquement avec les niveaux Event Hubs Premium et Dédié. Quand vous définissez le nombre de partitions, tenez compte de la mise à l’échelle à long terme.
  • Le groupe de consommateurs doit être unique par consommateur. Créez un groupe de consommateurs dédié à la connexion Azure Data Explorer.

Envoyer des événements

Consultez l’exemple d’application qui génère des données et les envoie à un hub d’événements.

Pour obtenir un exemple illustrant la façon de générer des exemples de données, consultez Ingérer des données de hub d’événements dans Azure Data Explorer.

Configurer une solution de géo-reprise d’activité après sinistre

Event Hubs offre une solution de géoreprise d’activité après sinistre. Azure Data Explorer ne prend pas en charge les espaces de noms de hub d’événements de type Alias. Pour implémenter la géoreprise d’activité dans votre solution, créez deux connexions de données de hub d’événements : une pour l’espace de noms principal et une pour l’espace de noms secondaire. Azure Data Explorer écoutera les deux connexions de hub d’événements.

Notes

Il est de la responsabilité de l’utilisateur d’implémenter un basculement entre l’espace de noms principal et l’espace de noms secondaire.

Contenu connexe