Partager via

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

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

Remarque

Envisagez d’utiliser les commandes d’ingestion mises en file d’attente , car elles ne nécessitent pas l’installation de logiciels.

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. Entrez ingest- suivi par la chaîne de connexion au cluster Azure Data Explorer qui effectue 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, LightIngest a besoin de la taille des données brutes afin qu’elle 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. Placez cette valeur entre guillemets doubles. ✔️
-base de données, -bd 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. Placez 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 (identité gérée), -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 (connexion au stockage avec authentification utilisateur), -storageUserAuth (authentification utilisateur du stockage) 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éfinie, vous pouvez éventuellement fournir un URI de connexion de 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. Placez cette valeur entre guillemets doubles.
-pattern string Modèle selon lequel les fichiers sources et les objets blob sont sélectionnés. Prend en charge les caractères génériques. Par exemple : "*.csv". Placez 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". Placez 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.
-ingestionMappingRéf, -mappingRéf string Nom d'un mappage de colonne d'ingestion que vous avez créé précédemment dans 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 elle est définie, le premier enregistrement de chaque fichier ou 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 et de blobs.
-compression, -cr double Indicateur de taux de compression. Utile lors de l’ingestion de fichiers compressés et d’objets blob 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 S’il est défini, affiche uniquement les éléments qui seraient 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 et de blobs 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

Lorsque vous utilisez LightIngest avec les blobs Azure, il utilise certaines métadonnées de blob pour améliorer le processus d'ingestion.

Propriété de métadonnées Utilisation
rawSizeBytes, kustoUncompressedSizeBytes Si la valeur est définie, LightIngest interprète ces propriétés comme la taille de données non compressée
kustoCreationTime, kustoCreationTimeUtc LightIngest interprète ces propriétés comme horodatage UTC. Si elle est définie, elle utilise ces propriétés pour remplacer l’heure de création dans Kusto. Cette fonctionnalité est utile pour les scénarios de remplissage rétroactif

Exemples d'utilisation

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

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

Lorsque vous chargez des données historiques d’un système existant vers Azure Data Explorer, tous les enregistrements obtiennent la même date d’ingestion. Pour partitionner vos données par heure de création au lieu du temps d’ingestion, utilisez 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 l’intégralité du chemin d’accès de l’élément, juste la section qui entoure l’horodatage 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 remplacée, assurez-vous que la propriété Lookback de la politique de fusion des étendues effective de la table cible s’aligne sur les valeurs dans vos chemins d’accès de fichier ou de 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

Ingestion d’objets blob à l’aide d’une clé de compte de stockage ou d’un jeton SAP

  • 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

  • Ingérer tous les fichiers sous le chemin d’accès PATH qui correspondent au modèle *.json
  • Définissez la destination sur la base de données DB, la table TABLEet définissez le mappage d’ingestion 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"

Ingérer des fichiers et écrire des fichiers de trace de diagnostic

  • Ingérer tous les fichiers sous le chemin d’accès PATH qui correspondent au modèle *.json
  • Définissez la destination sur la base de données DB, la table TABLEet définissez le mappage d’ingestion 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
  • Écrire des fichiers de trace de diagnostic localement sous 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

LightIngest effectue trois actions qui peuvent utiliser l’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 (connectez-vous 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 est transmis au service Kusto à utiliser pour l’ingestion. Définissez les trois arguments.

  • Last updated on