Utiliser LightIngest pour ingérer des données dans Azure Data Explorer

  • Article

LightIngest est un utilitaire de ligne de commande pour l’ingestion de données ad hoc dans Azure Data Explorer. L’utilitaire peut extraire les données sources à partir d’un dossier local, d’un conteneur Stockage Blob Azure ou d’un compartiment Amazon S3.

LightIngest est particulièrement utile quand vous souhaitez ingérer une grande quantité de données, car la durée d’ingestion n’est soumise à aucune contrainte de temps. Il permet également d’interroger les enregistrements en fonction de l’heure à laquelle ils ont été créés, et non de l’heure à laquelle ils ont été ingérés.

Pour obtenir un exemple de génération automatique d’une commande LightIngest, veuillez consulter Ingestion de données historiques.

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.

Prérequis

Exécuter LightIngest

Pour exécuter LightIngest :

  1. À l’invite de commandes, saisissez LightIngest suivi de l’argument de ligne de commande approprié.

    Conseil

    Pour obtenir la liste des arguments de ligne de commande pris en charge, saisissez LightIngest /help.

  2. Saisissez ingest- suivi de la chaîne de connexion au cluster Azure Data Explorer qui gérera l’ingestion. Mettez la chaîne de connexion entre guillemets doubles et suivez la Spécification des chaînes de connexion Kusto.

    Par exemple :

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Recommandations en matière de performances

  • Pour mieux gérer la charge d’ingestion et récupérer à partir d’erreurs temporaires, utilisez le point de terminaison d’ingestion à l’adresse https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.

  • Pour optimiser les performances d’ingestion, la taille des données brutes est nécessaire pour que LightIngest puisse estimer la taille non compressée des fichiers locaux. Toutefois, LightIngest peut ne pas être en mesure d’estimer correctement la taille brute des blobs compressés sans les télécharger au préalable. Par conséquent, lors de la réception d’objets BLOB compressés, définissez la propriété rawSizeBytes sur les métadonnées de l’objet BLOB sur la taille des données non compressées en octets.

Arguments de ligne de commande

Argument Type Description Obligatoire
string Une chaîne de connexion Kusto spécifiant le point de terminaison Kusto qui gère l’ingestion. Cette valeur doit être placée entre guillemets doubles. ✔️
-database, -db string Le nom de la base de données cible Azure Data Explorer.
-table string Le nom de la table cible Azure Data Explorer. ✔️
-sourcePath, -source string L’emplacement des données source, qui peut être un chemin de fichier local, l’URI racine d’un conteneur d’objet blob Azure ou l’URI d’un compartiment Amazon S3. Si les données sont stockées dans des objets blob Azure, l’URI doit inclure la clé du compte de stockage ou la signature d’accès partagé (SAP). Si les données se trouvent dans un compartiment S3, l’URI doit inclure la clé des informations d’identification. Nous vous recommandons de placer cette valeur entre guillemets doubles. Pour plus d’informations, veuillez consulter la page Chaînes de connexion de stockage. Passez -sourcePath:;impersonate pour répertorier les éléments de stockage Azure avec des autorisations utilisateur (autorisation de prompt utilisateur). ✔️
-managedIdentity, -mi string ID client de l’identité managée (affectée par l’utilisateur ou affectée par le système) à utiliser pour la connexion. Utilisez « système » pour l’identité affectée par le système.
-azCli bool Si elle est définie, utilise Azure CLI pour s’authentifier auprès du service Kusto. Azure CLI doit être installé et connecté.
-ingestWithManagedIdentity, -ingestmi string ID client de l’identité managée (affectée par l’utilisateur ou affectée par le système) installée sur le service Kusto à télécharger à partir du stockage. Utilisez « système » pour l’identité affectée par le système.
-connectToStorageWithManagedIdentity, -storageMi string ID client de l’identité managée (affectée par l’utilisateur ou affectée par le système) installée côté client pour répertorier à partir du stockage.
-connectToStorageWithUserAuth, -storageUserAuth string Authentifiez-vous auprès du service de stockage de la source de données avec les informations d’identification de l’utilisateur. Les options pour cette valeur sont PROMPT ou DEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string Si -connectToStorageWithUserAuth est défini, vous pouvez éventuellement fournir un URI de connexion Microsoft Entra ID.
-prefix string Lorsque les données sources à ingérer résident dans le stockage d’objets BLOB, ce préfixe d’URL est partagé par tous les objets BLOB, à l’exclusion du nom du conteneur.
Par exemple, si les données sont dans MyContainer/Dir1/Dir2, le préfixe doit être Dir1/Dir2. Nous vous recommandons de placer cette valeur entre guillemets doubles.
-pattern string Modèle suivant lequel les fichiers sources/objets BLOB sont choisis. Prend en charge les caractères génériques. Par exemple : "*.csv". Nous vous recommandons de placer cette valeur entre guillemets doubles.
-zipPattern string Expression régulière à utiliser lors de la sélection des fichiers d’une archive ZIP à ingérer. Tous les autres fichiers de l’archive sont ignorés. Par exemple : "*.csv". Nous vous recommandons de placer cette valeur entre guillemets doubles.
-format, -f string Format des données sources. Doit être dans l'un des formats pris en charge
-ingestionMappingPath, -mappingPath string Un chemin vers un fichier local pour le mappage des colonnes d’ingestion. Consultez Mappages de données.
-ingestionMappingRef, -mappingRef string Le nom d’un mappage de colonnes d’ingestion précédemment créé sur la table. Consultez Mappages de données.
-creationTimePattern string Lorsque cette option est définie, elle est utilisée pour extraire la propriété CreationTime du chemin d’accès du fichier ou de l’objet BLOB. Veuillez consulter Comment ingérer des données à l’aide de CreationTime.
-ignoreFirstRow, -ignoreFirst bool Si cette valeur est définie, le premier enregistrement de chaque fichier/objet blob est ignoré. Par exemple, si les données sources ont des en-têtes.
-tag string Balises à associer aux données ingérées. Plusieurs occurrences sont autorisées
-dontWait bool Si cette valeur est définie sur true, le processus n’attend pas la fin de l’ingestion. Utile lors de l’ingestion de grandes quantités de fichiers/objets blob.
-compression, -cr double Indicateur de taux de compression. Utile lors de la réception de fichiers ou d’objets BLOB compressés pour aider Azure Data Explorer à évaluer la taille des données brutes. Calculé comme la taille d’origine divisée par la taille compressée.
-limit, -l entier Si cette valeur est définie, elle limite l’ingestion aux N premiers fichiers.
-listOnly, -list bool Si cette option est définie, elle affiche uniquement les éléments qui auraient été sélectionnés pour l’ingestion.
-ingestTimeout entier Délai d’expiration en minutes pour l’exécution de toutes les opérations de réception. La valeur par défaut est 60.
-forceSync bool Si cette option est définie, force l’ingestion synchrone. La valeur par défaut est false.
-interactive bool Si la valeur est définie sur false, elle n’invite pas à confirmer les arguments. Pour les flux sans assistance et les environnements non interactifs. La valeur par défaut est true.
-dataBatchSize entier Définit la limite de taille totale (Mo, non compressée) de chaque opération d’ingestion.
-filesInBatch entier Définit la limite du nombre de fichiers/objets blob pour chaque opération d’ingestion.
-devTracing, -trace string Si cette option est définie, les journaux de diagnostic sont écrits dans un répertoire local (par défaut, RollingLogs dans le répertoire à jour ou peuvent être modifiés en définissant la valeur du commutateur).

Fonctionnalités spécifiques aux objets blob Azure

Lorsqu’il est utilisé avec des blobs Azure, LightIngest utilise certaines propriétés de métadonnées de blob pour améliorer le processus d’ingestion.

Propriété de métadonnées Utilisation
rawSizeBytes, kustoUncompressedSizeBytes Si cette valeur est définie, elle est interprétée comme la taille des données non compressées
kustoCreationTime, kustoCreationTimeUtc Interprété comme un horodatage UTC. Si cette valeur est définie, elle est utilisée pour remplacer l’heure de création dans Kusto. Utile pour les scénarios de renvoi

Exemples d'utilisation

Les exemples suivants supposent que vous avez installé des fichiers binaires de LightIngest pour votre système d’exploitation. Si vous avez installé LightIngest en tant qu’outil .NET, remplacez LightIngest par LightIngest dans les exemples.

Ingestion des données historiques avec la propriété CreationTime

Lorsque vous chargez des données historiques à partir d’un système existant vers Azure Data Explorer, tous les enregistrements reçoivent la même date d’ingestion. Pour permettre le partitionnement de vos données par heure création, et non par heure d’ingestion, vous pouvez utiliser l’argument -creationTimePattern. L’argument -creationTimePattern extrait la propriété CreationTime du chemin du fichier ou de l’objet blob. Le modèle n’a pas besoin de refléter le chemin d’accès complet de l’élément, mais uniquement la section entourant le timestamp que vous souhaitez utiliser.

Les valeurs d’argument doivent inclure :

  • Texte fixe précédant immédiatement le format de l’horodatage, placé entre guillemets simples (préfixe).
  • Format d’horodatage, en notation .NET DateTime standard
  • Texte fixe qui suit immédiatement l’horodatage (suffixe).

Important

Lorsque vous spécifiez que l’heure de création doit être substituée, assurez-vous que la propriété Lookback de la stratégie de fusion d’étendues effectives de la table cible est alignée sur les valeurs de vos chemins d’accès de fichier ou d’objet blob.

Exemples

  • Nom de l’objet blob qui contient le DateHeure, comme suit : historicalvalues19840101.parquet (l’horodatage comprend quatre chiffres pour l’année, deux chiffres pour le mois et deux chiffres pour le jour du mois).

    La valeur de l’argument -creationTimePattern fait partie du nom de fichier : "'historicalvalues'yyyyMMdd'.parquet'"

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'historicalvalues'yyyyMMdd'.parquet'"
 -pattern:"*.parquet" -format:parquet -limit:2 -cr:10.0 -dontWait:true

  • URI d’objet blob qui fait référence à une structure hiérarchique de dossiers, comme https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension.

    La valeur de l’argument -creationTimePattern fait partie de la structure de dossiers : "'folder/'yyyy/MM/dd'/blob'"

      LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'mycontainer/myfolder/'yyyy/MM/dd'/'"
   -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Réception d’objets BLOB à l’aide d’une clé de compte de stockage ou d’un jeton SAS

  • Ingérez 10 objets BLOB dans le compte de stockage spécifié ACCOUNT, dans le dossier DIR, sous le conteneur CONT et correspondant au modèle *.csv.gz
  • La destination est la base de données DB, table TABLE, et le mappage d’ingestion MAPPING est précréé sur la destination
  • L’outil attend que les opérations d’ingestion soient terminées
  • Notez les différentes options pour spécifier la base de données cible et la clé de compte de stockage par rapport au Jeton SAS
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True;Initial Catalog=DB"
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

Réception de tous les objets BLOB dans un conteneur, à l’exclusion des lignes d’en-tête

  • Ingérez tous les objets BLOB sous le compte de stockage spécifié ACCOUNT, dans le dossier DIR1/DIR2, sous le conteneur CONT et en correspondant au modèle *.csv.gz
  • La destination est la base de données DB, table TABLE, et le mappage d’ingestion MAPPING est précréé sur la destination
  • Les objets BLOB sources contiennent une ligne d’en-tête. L’outil est donc invité à supprimer le premier enregistrement de chaque objet BLOB
  • L’outil publie les données pour l’ingestion et n’attend pas la fin des opérations d’ingestion
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR1/DIR2"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -ignoreFirstRow:true

Réception de tous les fichiers JSON à partir d’un chemin d’accès

  • Recevoir tous les fichiers sous le chemin d’accès PATH correspondant au modèle *.json
  • La destination est la base de données DB, table TABLE, et le mappage d’ingestion est défini dans le fichier local MAPPING_FILE_PATH
  • L’outil publie les données pour l’ingestion et n’attend pas la fin des opérations d’ingestion
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Ingestion de fichiers et écriture de fichiers de trace de diagnostic

  • Recevoir tous les fichiers sous le chemin d’accès PATH correspondant au modèle *.json
  • La destination est la base de données DB, table TABLE, et le mappage d’ingestion est défini dans le fichier local MAPPING_FILE_PATH
  • L’outil publie les données pour l’ingestion et n’attend pas la fin des opérations d’ingestion
  • Les fichiers de trace de diagnostic sont écrits localement dans le dossier LOGS_PATH
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"
  -trace:"LOGS_PATH"

S’authentifier avec l’identité managée

Il existe trois actions que LightIngest effectue qui peuvent utiliser une identité managée pour l’authentification. L’utilisation de l’identité managée dans chaque étape ne nécessite pas l’utilisation de l’identité managée dans d’autres étapes. Pour chaque action, l’argument de ligne de commande associé est donné.

  • Se connecter au cluster Kusto : pour mettre en file d’attente l’ingestion, l’outil utilise une chaîne de connexion. Utilisez l’argument « -mi » pour spécifier une identité managée installée sur la machine virtuelle cliente qui dispose de privilèges d’ingestion dans la base de données cible.

  • Connectez-vous au Stockage Azure pour télécharger des objets blob : utilisez « -ingestmi » pour spécifier une identité managée installée sur le service Kusto disposant de privilèges de lecture sur le conteneur de stockage.

  • Connectez-vous au Stockage Azure pour répertorier les objets blob de conteneurs : utilisez l’argument « -storageMi » pour spécifier une identité managée installée sur la machine virtuelle cliente disposant de privilèges de liste sur le conteneur de stockage. Si vous utilisez cette méthode, mais pas la précédente (se connecter au Stockage Azure pour télécharger des objets blob), l’identité managée doit également disposer de privilèges de lecture et un jeton sera transmis au service Kusto pour être utilisé pour l’ingestion. Il est donc recommandé de définir les trois arguments.