Créer une connexion de données Event Grid pour Azure Data Explorer

Article
09/04/2024

Cet article vous montre comment ingérer des objets blob de votre compte de stockage vers Azure Data Explorer en utilisant une connexion de données Event Grid. Vous allez créer une connexion de données Event Grid qui définit un abonnement Azure Event Grid. L’abonnement Event Grid route les événements de votre compte de stockage vers Azure Data Explorer via un hub d’événements Azure.

Remarque

L’ingestion prend en charge une taille de fichier maximale de 6 Go. Nous vous recommandons d’ingérer des fichiers entre 100 Mo et 1 Go.

Pour savoir comment créer la connexion en utilisant des kits de développement logiciel (SDK) Kusto, consultez Créer une connexion de données Event Grid avec des kits de développement logiciel (SDK).

Pour obtenir des informations générales sur l’ingestion dans Azure Data Explorer à partir d’Event Grid, consultez Se connecter à Event Grid.

Remarque

Pour obtenir des performances optimales avec la connexion Event Grid, définissez la propriété d’ingestion rawSizeBytes via les métadonnées du blob. Pour plus d’informations, consultez Propriétés d’ingestion.

Prérequis

Un abonnement Azure. Créez un compte Azure gratuit.
Un cluster et une base de données Azure Data Explorer. Créez un cluster et une base de données.
Une table de destination. Créez une table ou utilisez une table existante.
Un mappage d’ingestion pour la table.
Un compte de stockage. Un abonnement aux notifications Event Grid peut être défini sur des comptes de stockage Azure pour BlobStorage, StorageV2 ou Data Lake Storage Gen2.
Enregistrez le fournisseur de ressources Event Grid.

Créer une connexion de données à Event Grid

Dans cette section, vous établissez une connexion entre Event Grid et votre table Azure Data Explorer.

Accédez à votre cluster Azure Data Explorer dans le Portail Azure.
Sous Données, sélectionnez Bases de données>TestDatabase.
Sous Paramètres, sélectionnez Connexions de données, puis sélectionnez Ajouter une connexion de données>Event Grid (Stockage Blob).

Remplissez le formulaire de connexion de données Event Grid avec les informations suivantes :

Paramètre	Valeur suggérée	Description du champ
Nom de la connexion de données	test-grid-connection	Nom de la connexion que vous souhaitez créer dans Azure Data Explorer. Les noms de connexion de données ne peuvent contenir que des caractères alphanumériques, des tirets et des points. Ils ne peuvent dépasser 40 caractères.
Abonnement du compte de stockage	Votre ID d’abonnement	ID d’abonnement où se trouve votre compte de stockage.
Type d'événement	Objet blob créé ou Objet blob renommé	Type d’événement qui déclenche l’ingestion. Le renommage d’objets blob est pris en charge uniquement pour le stockage ADLSv2. Pour renommer un blob, accédez au blob dans le Portail Azure, cliquez dessus avec le bouton droit et sélectionnez Renommer. Types pris en charge : Microsoft.Storage.BlobCreated ou Microsoft.Storage.BlobRenamed.
Compte de stockage	gridteststorage1	Nom du compte de stockage que vous avez créé précédemment.
Création de ressources	Automatique	Activer la création automatique de ressource signifie qu’Azure Data Explorer vous crée un abonnement Event Grid, un espace de noms Event Hubs et un Event Hubs. Sinon, vous devez créer manuellement ces ressources pour garantir la création de la connexion de données. Consulter Créer manuellement des ressources pour l’ingestion Event Grid

Vous pouvez éventuellement suivre des sujets Event Grid spécifiques. Définissez les filtres pour les notifications comme suit :
- Le champ Préfixe est le préfixe littéral du sujet. Comme le modèle appliqué est un modèle commence par, il peut englober plusieurs conteneurs, dossiers ou blobs. Les caractères génériques ne sont pas autorisés.
  - Pour définir un filtre sur le conteneur d’objets blob, le champ doit être défini comme suit : /blobServices/default/containers/[container prefix].
  - Pour définir un filtre sur un préfixe d’objet blob (ou un dossier dans Azure Data Lake Gen2), le champ doit être défini comme suit : /blobServices/default/containers/[container name]/blobs/[folder/blob prefix].
- Le champ Suffixe est le suffixe littéral de l’objet blob. Les caractères génériques ne sont pas autorisés.
- Le champ Sensible à la casse indique si les filtres de préfixe et de suffixe respectent la casse.
Pour plus d’informations sur le filtrage d’événements, consultez Événements de Stockage Blob.

Vous pouvez éventuellement spécifier les Paramètres de routage des données en fonction des informations suivantes. Vous n’avez pas à spécifier tous les paramètres de routage des données. Des paramètres partiels sont également acceptés.

Paramètre	Valeur suggérée	Description du champ
Autoriser le routage des données vers d’autres bases de données (connexion de données à plusieurs bases de données)	Ne pas autoriser	Activez cette option si vous voulez remplacer la base de données cible par défaut associée à la connexion de données. Pour plus d’informations sur le routage de base de données, consultez Routage des événements.
Nom de table	TestTable	Table que vous avez créée dans TestDatabase.
Format de données	JSON	Les formats pris en charge sont APACHEAVRO, Avro, CSV, JSON, ORC, PARQUET, PSV, RAW, SCSV, SOHSV, TSV, TSVE, TXT et W3CLOG. Les options de compression prises en charge sont zip et gzip.
Nom du mappage	TestTable_mapping	Le mappage que vous avez créé dans TestDatabase, qui mappe les données entrantes aux noms de colonnes et aux types de données de TestTable. S’il n’est pas spécifié, un mappage de données d’identité dérivé du schéma de la table est généré automatiquement.
Ignorer les erreurs de format	Ignorer	Activez cette option si vous souhaitez ignorer les erreurs de format pour le format de données JSON.

Remarque

Les noms de table et de mappage sont sensibles à la casse.

Éventuellement, sous Paramètres avancés, vous pouvez spécifier le Type d’identité managée utilisée par votre connexion de données. Par défaut, l’option Affectée par le système est sélectionnée.

Si vous sélectionnez Affectée par l’utilisateur, vous devez attribuer manuellement une identité managée. Si vous sélectionnez un utilisateur qui n’est pas encore affecté à votre cluster, il sera automatiquement affecté. Pour plus d’informations, consultez Configurer des identités managées pour votre cluster Azure Data Explorer.

Si vous sélectionnez Aucun, le compte de stockage et l’Event Hub sont authentifiés via des chaînes de connexion. Cette méthode n'est pas recommandée.

Sélectionnez Créer

Accédez à votre compte de stockage dans le Portail Azure.
Sélectionnez Événements.
Dans l’onglet Prise en main, sélectionnez l’onglet Azure Data Explorer.
Dans la vignette Créer une ingestion de données continue, sélectionnez Créer.

Choisir la destination vers laquelle acheminer des événements

Sélectionnez un cluster dans lequel vous souhaitez ingérer des données.
Sélectionnez une base de données cible.
Sélectionnez Sélectionner.

Créer une connexion de données

Renseignez le formulaire avec les informations suivantes :

Paramètre	Valeur suggérée	Description du champ
Nom de la connexion de données	test-grid-connection	Nom de la connexion que vous souhaitez créer dans Azure Data Explorer.
Abonnement du compte de stockage	Votre ID d’abonnement	ID d’abonnement où se trouve votre compte de stockage.
Type d'événement	Objet blob créé ou Objet blob renommé	Type d’événement qui déclenche l’ingestion. Le renommage d’objets blob est pris en charge uniquement pour le stockage ADLSv2. Pour renommer un blob, accédez au blob dans le Portail Azure, cliquez dessus avec le bouton droit et sélectionnez Renommer. Types pris en charge : Microsoft.Storage.BlobCreated ou Microsoft.Storage.BlobRenamed.
Compte de stockage	gridteststorage1	Le compte de stockage à partir duquel vous avez accédé à cet assistant est automatiquement renseigné.
Création de ressources	Automatique	Activer la création automatique de ressource signifie qu’Azure Data Explorer vous crée un abonnement Event Grid, un espace de noms Event Hubs et un Event Hubs. Sinon, vous devez créer manuellement ces ressources pour garantir la création de la connexion de données. Consulter Créer manuellement des ressources pour l’ingestion Event Grid

Vous pouvez éventuellement suivre des sujets Event Grid spécifiques. Définissez les filtres pour les notifications comme suit :
- Le champ Préfixe est le préfixe littéral du sujet. Comme le modèle appliqué est un modèle commence par, il peut englober plusieurs conteneurs, dossiers ou blobs. Les caractères génériques ne sont pas autorisés.
  - Pour définir un filtre sur le conteneur d’objets blob, le champ doit être défini comme suit : /blobServices/default/containers/[container prefix].
  - Pour définir un filtre sur un préfixe d’objet blob (ou un dossier dans Azure Data Lake Gen2), le champ doit être défini comme suit : /blobServices/default/containers/[container name]/blobs/[folder/blob prefix].
- Le champ Suffixe est le suffixe littéral de l’objet blob. Les caractères génériques ne sont pas autorisés.
- Le champ Sensible à la casse indique si les filtres de préfixe et de suffixe respectent la casse.
Pour plus d’informations sur le filtrage d’événements, consultez Événements de Stockage Blob.

Paramètre	Valeur suggérée	Description du champ
Autoriser le routage des données vers d’autres bases de données (connexion de données à plusieurs bases de données)	Ne pas autoriser	Activez cette option si vous voulez remplacer la base de données cible par défaut associée à la connexion de données. Pour plus d’informations sur le routage de base de données, consultez Routage des événements.
Nom de table	TestTable	Table que vous avez créée dans TestDatabase.
Format de données	JSON	Les formats pris en charge sont APACHEAVRO, Avro, CSV, JSON, ORC, PARQUET, PSV, RAW, SCSV, SOHSV, TSV, TSVE, TXT et W3CLOG. Les options de compression prises en charge sont zip et gzip.
Nom du mappage	TestTable_mapping	Le mappage que vous avez créé dans TestDatabase, qui mappe les données entrantes aux noms de colonnes et aux types de données de TestTable. S’il n’est pas spécifié, un mappage de données d’identité dérivé du schéma de la table est généré automatiquement.
Ignorer les erreurs de format	Ignorer	Activez cette option si vous souhaitez ignorer les erreurs de format pour le format de données JSON.

Remarque

Les noms de table et de mappage sont sensibles à la casse.

Éventuellement, sous Paramètres avancés, vous pouvez spécifier le Type d’identité managée utilisée par votre connexion de données. Par défaut, l’option Affectée par le système est sélectionnée.

Si vous sélectionnez Affectée par l’utilisateur, vous devez attribuer manuellement une identité managée. Si vous sélectionnez un utilisateur qui n’est pas encore affecté à votre cluster, il sera automatiquement affecté. Pour plus d’informations, consultez Configurer des identités managées pour votre cluster Azure Data Explorer.

Si vous sélectionnez Aucun, le compte de stockage et l’Event Hub sont authentifiés via des chaînes de connexion. Cette méthode n'est pas recommandée.

Sélectionnez Créer.

L’exemple suivant montre un modèle Azure Resource Manager pour l’ajout d’une connexion de données Event Grid. Vous pouvez modifier et déployer le modèle dans le portail Azure en utilisant le formulaire.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "namespaces_eventhubns_name": {
            "type": "string",
            "defaultValue": "eventhubns",
            "metadata": {
                "description": "Specifies the event hub namespace name."
            }
        },
        "EventHubs_eventhubdemo_name": {
            "type": "string",
            "defaultValue": "eventhubdemo",
            "metadata": {
                "description": "Specifies the event hub name."
            }
        },
        "consumergroup_default_name": {
            "type": "string",
            "defaultValue": "$Default",
            "metadata": {
                "description": "Specifies the consumer group of the event hub."
            }
        },
        "StorageAccounts_storagedemo_name": {
            "type": "string",
            "defaultValue": "storagedemo",
            "metadata": {
                "description": "Specifies the storage account name"
            }
        },
        "Clusters_kustocluster_name": {
            "type": "string",
            "defaultValue": "kustocluster",
            "metadata": {
                "description": "Specifies the name of the cluster"
            }
        },
        "databases_kustodb_name": {
            "type": "string",
            "defaultValue": "kustodb",
            "metadata": {
                "description": "Specifies the name of the database"
            }
        },
        "tables_kustotable_name": {
            "type": "string",
            "defaultValue": "kustotable",
            "metadata": {
                "description": "Specifies the name of the table"
            }
        },
        "mapping_kustomapping_name": {
            "type": "string",
            "defaultValue": "kustomapping",
            "metadata": {
                "description": "Specifies the name of the mapping rule"
            }
        },
        "dataformat_type": {
            "type": "string",
            "defaultValue": "csv",
            "metadata": {
                "description": "Specifies the data format"
            }
        },
             "databaseRouting_type": {
            "type": "string",
            "defaultValue": "Single",
            "metadata": {
                "description": "The database routing for the connection. If you set the value to **Single**, the data connection will be routed to a single database in the cluster as specified in the *databaseName* setting. If you set the value to **Multi**, you can override the default target database using the *Database* EventData property."
            }
        },
        "dataconnections_kustodc_name": {
            "type": "string",
            "defaultValue": "kustodc",
            "metadata": {
                "description": "Name of the data connection to create"
            }
        },
        "subscriptionId": {
            "type": "string",
            "defaultValue": "[subscription().subscriptionId]",
            "metadata": {
                "description": "Specifies the subscriptionId of the resources"
            }
        },
        "resourceGroup": {
            "type": "string",
            "defaultValue": "[resourceGroup().name]",
            "metadata": {
                "description": "Specifies the resourceGroup of the resources"
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]",
            "metadata": {
                "description": "Location for all resources."
            }
        }
    },
    "variables": {
    },
    "resources": [{
            "type": "Microsoft.Kusto/Clusters/Databases/DataConnections",
            "apiVersion": "2022-02-01",
            "name": "[concat(parameters('Clusters_kustocluster_name'), '/', parameters('databases_kustodb_name'), '/', parameters('dataconnections_kustodc_name'))]",
            "location": "[parameters('location')]",
            "kind": "EventGrid",
            "properties": {
                "managedIdentityResourceId": "[resourceId('Microsoft.Kusto/clusters', parameters('clusters_kustocluster_name'))]",
                "storageAccountResourceId": "[resourceId(parameters('subscriptionId'), parameters('resourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('StorageAccounts_storagedemo_name'))]",
                "eventHubResourceId": "[resourceId(parameters('subscriptionId'), parameters('resourceGroup'), 'Microsoft.EventHub/namespaces/eventhubs', parameters('namespaces_eventhubns_name'), parameters('EventHubs_eventhubdemo_name'))]",
                "consumerGroup": "[parameters('consumergroup_default_name')]",
                "tableName": "[parameters('tables_kustotable_name')]",
                "mappingRuleName": "[parameters('mapping_kustomapping_name')]",
                "dataFormat": "[parameters('dataformat_type')]",
                "databaseRouting": "[parameters('databaseRouting_type')]"
            }
        }
    ]
}

Utiliser une connexion de données Event Grid

Dans cette section, vous allez découvrir comment déclencher l’ingestion à partir de Stockage Blob Azure ou d’Azure Data Lake Gen 2 vers votre cluster après la création d’un blob ou le changement de nom d’un blob.

Sélectionnez l’onglet approprié en fonction du type de Kit de développement logiciel (SDK) de stockage utilisé pour charger des blobs.

Stockage Blob Azure
Azure Data Lake

L’exemple de code suivant utilise le Kit de développement logiciel (SDK) Stockage Blob Azure pour charger un fichier dans Stockage Blob Azure. Le chargement déclenche la connexion de données Event Grid, qui ingère les données dans Azure Data Explorer.

var azureStorageAccountConnectionString = <storage_account_connection_string>;
var containerName = <container_name>;
var blobName = <blob_name>;
var localFileName = <file_to_upload>;
var uncompressedSizeInBytes = <uncompressed_size_in_bytes>;
var mapping = <mapping_reference>;
// Create a new container if it not already exists.
var azureStorageAccount = new BlobServiceClient(azureStorageAccountConnectionString);
var container = azureStorageAccount.GetBlobContainerClient(containerName);
container.CreateIfNotExists();
// Define blob metadata and uploading options.
IDictionary<String, String> metadata = new Dictionary<string, string>();
metadata.Add("rawSizeBytes", uncompressedSizeInBytes);
metadata.Add("kustoIngestionMappingReference", mapping);
var uploadOptions = new BlobUploadOptions
{
    Metadata = metadata,
};
// Upload the file.
var blob = container.GetBlobClient(blobName);
blob.Upload(localFileName, uploadOptions);

Remarque

Azure Data Explorer ne supprimera pas les objets blob après l’ingestion. Conservez les blobs pendant trois à cinq jours en utilisant le cycle de vie du Stockage Blob Azure pour gérer la suppression des blobs.

L’exemple de code suivant utilise le Kit de développement logiciel (SDK) Azure Data Lake pour charger un fichier dans Data Lake Storage Gen2. Le chargement déclenche la connexion de données Event Grid, qui ingère les données dans Azure Data Explorer.

var accountName = <storage_account_name>;
var accountKey = <storage_account_key>;
var fileSystemName = <file_system_name>;
var fileName = <file_name>;
var localFileName = <file_to_upload>;
var uncompressedSizeInBytes = <uncompressed_size_in_bytes>;
var mapping = <mapping_reference>;
var sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
var dfsUri = "https://" + accountName + ".dfs.core.windows.net";
var dataLakeServiceClient = new DataLakeServiceClient(new Uri(dfsUri), sharedKeyCredential);
// Create the filesystem.
var dataLakeFileSystemClient = dataLakeServiceClient.CreateFileSystem(fileSystemName).Value;
// Define file metadata and uploading options.
IDictionary<String, String> metadata = new Dictionary<string, string>();
metadata.Add("rawSizeBytes", uncompressedSizeInBytes);
metadata.Add("kustoIngestionMappingReference", mapping);
var uploadOptions = new DataLakeFileUploadOptions
{
    Metadata = metadata,
    Close = true // Note: The close option triggers the event being processed by the data connection.
};
// Upload the file.
var dataLakeFileClient = dataLakeFileSystemClient.GetFileClient(fileName);
dataLakeFileClient.Upload(localFileName, uploadOptions);

Remarque

Lors du chargement d’un fichier avec le Kit de développement logiciel (SDK) Azure Data Lake, l’événement de création de fichier initial a une taille de 0, qui est ignorée par Azure Data Explorer pendant l’ingestion des données. Pour garantir une ingestion appropriée, définissez le paramètre Close sur true. Ce paramètre entraîne le déclenchement d’un événement FlushAndClose par la méthode de chargement. Cet événement indique que la mise à jour finale a été effectuée et que le flux de fichiers est fermé.
Pour réduire le trafic provenant d’Event Grid et optimiser l’ingestion d’événements dans Azure Data Explorer, nous vous recommandons de filtrer la clé data.api pour exclure les événements CreateFile. Cela garantit l’exclusion d’événements de création de fichiers avec une taille de 0, empêchant ainsi les erreurs d’ingestion de fichier vide. Pour plus d’informations sur le vidage, consultez Méthode de vidage Azure Data Lake.

Renommer des objets blob

Dans ADLSv2, il est possible de renommer des répertoires. Cependant, il est important de noter que renommer un répertoire ne déclenche pas d’événements de renommage des blobs ni ne lance l’ingestion des blobs contenus dans ce répertoire. Si vous souhaitez garantir l’ingestion de blobs après avoir renommé un répertoire, vous devez renommer directement les blob individuels dans le répertoire.

L’extrait de code suivant utilise le Kit de développement logiciel (SDK) Azure Data Lake pour renommer un blob dans un compte de stockage ADLSv2.

var accountName = <storage_account_name>;
var accountKey = <storage_account_key>;
var fileSystemName = <file_system_name>;
var sourceFilePath = <source_file_path>;
var destinationFilePath = <destination_file_path>;
var sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
var dfsUri = "https://" + accountName + ".dfs.core.windows.net";
var dataLakeServiceClient = new DataLakeServiceClient(new Uri(dfsUri), sharedKeyCredential);
// Get a client to the the filesystem

var dataLakeFileSystemClient = dataLakeServiceClient.GetFileSystemClient(fileSystemName);
// Rename a file in the file system
var dataLakeFileClient = dataLakeFileSystemClient.GetFileClient(sourceFilePath);
dataLakeFileClient.Rename(destinationFilePath);

Remarque

Si vous avez défini des filtres pour suivre des sujets spécifiques pendant la création de la connexion de données ou lors de la création manuelle des ressources Event Grid, ces filtres sont appliqués sur le chemin du fichier de destination.

Remarque

Le déclenchement de l’ingestion après une opération CopyBlob n’est pas pris en charge pour les comptes de stockage sur lesquels la fonctionnalité d’espace de noms hiérarchique est activée.

Important

Nous déconseillons vivement de générer des événements de stockage à partir de code personnalisé et de les envoyer à Event Hubs. Si vous choisissez de le faire, assurez-vous que les événements produits respectent strictement le schéma approprié des événements de stockage et les spécifications de format JSON.

Supprimer une connexion de données Event Grid

Pour supprimer la connexion Event Grid du Portail Azure, procédez comme suit :

Accédez à votre cluster. Dans le menu de gauche, sélectionnez Bases de données. Ensuite, sélectionnez la base de données qui contient la table cible.
Dans le menu de gauche, sélectionnez Connexions de données. Ensuite, cochez la case en regard de la connexion de données Event Grid pertinente.
Dans la barre de menus du haut, sélectionnez Supprimer.

Traiter les données de votre instance Event Hub avec Azure Stream Analytics

Partage via

Créer une connexion de données Event Grid pour Azure Data Explorer

Prérequis

Créer une connexion de données à Event Grid

Choisir la destination vers laquelle acheminer des événements

Créer une connexion de données

Utiliser une connexion de données Event Grid

Renommer des objets blob

Supprimer une connexion de données Event Grid

Commentaires

Ressources supplémentaires

Partage via

Créer une connexion de données Event Grid pour Azure Data Explorer

Prérequis

Créer une connexion de données à Event Grid

Utiliser une connexion de données Event Grid

Supprimer une connexion de données Event Grid

Contenu connexe

Commentaires

Ressources supplémentaires