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

Article
07/23/2024

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

LightIngest. Il existe deux façons d’obtenir LightIngest :
- Téléchargez les fichiers binaires de LightIngest pour votre système d’exploitation. Veillez à décompresser les fichiers binaires après le téléchargement.
- Installez LightIngest en tant qu’outil .NET. Cette méthode nécessite que le Kit de développement logiciel (SDK) .NET version 6.0 ou ultérieure soit installé sur votre ordinateur. Ensuite, exécutez la commande suivante :
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

Exécuter LightIngest

Pour exécuter LightIngest :

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

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.

Partager via