Partager via

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. Tout d’abord, vous créez un hub d’événements dans le Portail Azure. Créez ensuite une table cible dans Azure Data Explorer dans laquelle les données dans un format particulier sont ingérées à l’aide des propriétés d’ingestion fournies. La connexion Event Hubs doit être consciente du 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.

Options d’authentification de connexion de données Azure Data Explorer

  • Connexion de données basée sur une identité managée (recommandée) : l’utilisation d’une connexion de données basée sur une identité managée est le moyen le plus sécurisé de se connecter à des sources de données. Elle offre un contrôle total sur la possibilité d’extraire des données à partir d’une source de données. La configuration d’une connexion de données avec une identité managée nécessite les étapes suivantes :

    1. Ajouter une identité managée à votre cluster.
    2. Accorder des autorisations à l’identité managée sur la source de données. Pour extraire des données à partir d’Azure Event Hubs, l’identité managée doit disposer des autorisations du récepteur de données Azure Event Hubs.
    3. Définissez une stratégie d’identité managée sur les bases de données cibles.
    4. Créez une connexion de données à l’aide de l’authentification par identité managée pour extraire les données.

    Attention

    Si les autorisations d’identité managée sont supprimées de la source de données, la connexion de données ne fonctionnera plus et ne pourra plus extraire de données de la source de données.

  • Connexion de données basée sur des clés : si une authentification par identité managée n’est pas spécifiée pour 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 obtient la chaîne de connexion de ressource pour la ressource spécifiée et l’enregistre de façon sécurisée. La chaîne de connexion est ensuite utilisée pour extraire des données de la source de données.

    Attention

    Si la clé fait l’objet d’une rotation, la connexion de données ne fonctionnera plus et ne pourra plus extraire les 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

Remarque

  • L’ingestion à partir d’Event Hubs ne prend pas en charge le format RAW.
  • Le registre de schémas Azure Event Hubs et Avro sans schéma ne sont pas pris en charge.
  • 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.
  • La compression des données n’est pas prise en charge pour les formats binaires (ApacheAvro, Parquet, ORC 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 et les formats binaires.
  • Lors de l’utilisation de formats binaires (Avro, ApacheAvro, Parquet, ORC et W3CLOGFILE) et de routages d’ingestion, l’ordre des champs dans la définition du routage d’ingestion doit correspondre à l’ordre des colonnes correspondantes dans la table.

Propriétés d’Event Hubs

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

Remarque

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 :

Remarque

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 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 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 d’événement est Kafka et qu’Azure Data Explorer doit utiliser la désérialisation du tableau d’octets pour lire d’autres propriétés de routage. La valeur est ignorée.

Remarque

Seuls les événements mis en file d’attente après la création de la connexion de données sont ingérés, sauf si une date de début de récupération personnalisée est fournie. Dans tous les cas, la période de recherche ne peut pas dépasser la période de rétention event Hub réelle.

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 une autre option de routage et de traitement pour vos données en définissant une ou plusieurs propriétés de données d’événement mentionnées dans le paragraphe précédent.

Remarque

La connexion de données Event Hubs tente de traiter tous les événements qu’il lit à partir d’Event Hub, et chaque événement qu’il ne peut pas traiter pour une raison quelconque sera signalé comme une défaillance d’ingestion. Découvrez comment surveiller l’ingestion d’Azure Data Explorer ici.

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. Cette fonctionnalité peut être activée dans le Portail Azure Portail Azure, avec des kits SDK de gestion C# ou Python, ou avec 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 base de données de la propriété d’ingestion.

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 système Event Hubs

Les propriétés système sont des champs définis par le service Event Hubs, au moment où l’événement est mis en file d’attente. La connexion de données Event Hubs d’Azuer Data Explorer peut incorporer un ensemble prédéfini de propriétés système dans les données ingérées dans une table en fonction d’un mappage donné.

Remarque

  • 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 un mappage CSV, des propriétés sont ajoutées au début de l’enregistrement dans l'ordre indiqué lors de la création de la connexion de données. Ne vous fiez pas à l’ordre de ces propriétés, car elles peuvent 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 (TimeStamp, MetricNameet 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, MetricName: 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" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "MetricName", "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" : "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"}}'
    ']'

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

Une façon de consommer des données Event Hubs 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 Hubs. 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 Hubs Avro, consultez Exploration des 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 :

Créer des hubs 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.

Remarque

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

Connexion de données Event Hubs inter-régions

Pour optimiser les performances, créez le hub d’événements dans la même région que le cluster. Si ce n’est pas possible, envisagez d’utiliser des niveaux Premium ou Dédié Event Hubs. Pour obtenir une comparaison de niveaux, consultez Comparer les niveaux Azure Event Hubs.

Envoyer des événements

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

Remarque

Pour permettre un traitement efficace des événements d’Event Hubs vers Azure Data Explorer, évitez une distribution déséquilibré des événements entre les partitions. Un mappage irrégulier peut entraîner une latence de découverte élevée. Pour plus d’informations, consultez Mappage d’événements aux partitions.

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 écoute les deux connexions event Hub.

Remarque

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