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

Article
02/29/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.

Notes

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 à l’aide des kits SDK Kusto, consultez Créer une connexion de données Event Grid avec des SDK.

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

Notes

Pour obtenir les meilleures performances avec la connexion Event Grid, définissez la propriété d’ingestion rawSizeBytes via les métadonnées d’objet 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.
Table de destination. Créez une table ou utilisez une table existante.
Mappage d’ingestion pour la table.
Un compte de stockage. Un abonnement de notification Event Grid peut être défini sur des comptes stockage Azure pour BlobStorage, StorageV2ou Data Lake Storage Gen2.
Inscrivez 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>TestBase de données.
Sous Paramètres, sélectionnez Connexions de données, puis Ajouter une connexion> de donnéesEvent 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, tirets et points, et comporter jusqu’à 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 objet blob, accédez à l’objet blob dans Portail Azure, cliquez avec le bouton droit sur l’objet blob 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	L’activation de la création automatique des ressources signifie qu’Azure Data Explorer crée un abonnement Event Grid, un espace de noms Event Hubs et un Event Hubs pour vous. Sinon, vous devez créer ces ressources manuellement pour garantir la création de la connexion de données. Consultez Créer manuellement des ressources pour l’ingestion d’Event Grid.

Si vous le souhaitez, vous pouvez 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. Lorsque le modèle appliqué commence par, il peut s’étendre sur plusieurs conteneurs, dossiers ou objets blob. 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 : .
  - 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 : .
- 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 des événements, consultez Événements de stockage Blob.

Si vous le souhaitez, vous pouvez 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 souhaitez 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 la 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	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.

Notes

Les noms de table et de mappage respectent la casse.

Si vous le souhaitez, sous Paramètres avancés, vous pouvez spécifier le type d’identité managée utilisé 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é par l’utilisateur, vous devez affecter 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 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.
Sous 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 les é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 objet blob, accédez à l’objet blob dans Portail Azure, cliquez avec le bouton droit sur l’objet blob 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 rempli automatiquement.
Création de ressources	Automatique	L’activation de la création automatique des ressources signifie qu’Azure Data Explorer crée un abonnement Event Grid, un espace de noms Event Hubs et un Event Hubs pour vous. Sinon, vous devez créer ces ressources manuellement pour garantir la création de la connexion de données. Consultez Créer manuellement des ressources pour l’ingestion d’Event Grid.

Si vous le souhaitez, vous pouvez 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. Lorsque le modèle appliqué commence par, il peut s’étendre sur plusieurs conteneurs, dossiers ou objets blob. 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 : .
  - 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 : .
- 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 des é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 souhaitez 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 la 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	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.

Notes

Les noms de table et de mappage respectent la casse.

Si vous le souhaitez, sous Paramètres avancés, vous pouvez spécifier le type d’identité managée utilisé 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é par l’utilisateur, vous devez affecter 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 Event Hub sont authentifiés via des chaînes de connexion. Cette méthode n’est pas recommandée.

Sélectionnez Create (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 la connexion de données Event Grid

Cette section montre comment déclencher l’ingestion de Stockage Blob Azure ou d’Azure Data Lake Gen 2 vers votre cluster après la création d’objets blob ou le renommage d’objets blob.

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

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 sur 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);

Notes

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);

Notes

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 correcte, définissez le paramètre sur Closetrue. Ce paramètre entraîne le déclenchement par la méthode upload d’un événement FlushAndClose , indiquant 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 des événements dans Azure Data Explorer, nous vous recommandons de filtrer la clé data.api pour exclure les événements CreateFile. Cela garantit que les événements de création de fichier de taille 0 sont filtrés, ce qui empêche les erreurs d’ingestion d’un 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. Toutefois, il est important de noter que le changement de nom d’un répertoire ne déclenche pas les événements renommés d’objet blob ou ne déclenche pas l’ingestion d’objets blob contenus dans le répertoire. Si vous souhaitez vous assurer de l’ingestion d’objets blob après avoir renommé un répertoire, vous devez renommer directement les objets blob individuels dans le répertoire.

L’exemple de code suivant montre comment renommer un objet 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);

Notes

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.

Notes

Le déclenchement de l’ingestion à la suite d’une CopyBlob opération n’est pas pris en charge pour les comptes de stockage dont la fonctionnalité d’espace de noms hiérarchique est activée.

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. Sélectionnez ensuite 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 appropriée.
Dans la barre de menus supérieure, sélectionnez Supprimer.

Traiter les données de votre hub d’événements à l’aide d’Azure Stream Analytics

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 les événements

Créer une connexion de données

Utiliser la connexion de données Event Grid

Renommer des objets blob

Supprimer une connexion de données Event Grid

Commentaires

Commentaires

Ressources supplémentaires

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 la connexion de données Event Grid

Supprimer une connexion de données Event Grid

Contenu connexe

Commentaires

Commentaires

Ressources supplémentaires