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

Article
12/27/2023

LightIngest est un utilitaire de ligne de commande pour l’ingestion de données ad hoc dans Azure Data Explorer. L’utilitaire peut extraire des données sources d’un dossier local, d’un conteneur de stockage d’objets blob Azure ou d’un compartiment Amazon S3.

LightIngest est particulièrement utile lorsque vous souhaitez ingérer une grande quantité de données, car il n’y a aucune contrainte de temps sur la durée d’ingestion. 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, consultez Ingérer des données historiques.

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.

Prérequis

LightIngest. Il existe deux façons d’obtenir LightIngest :
- Téléchargez les fichiers binaires 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 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 gérer au mieux 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`	Kusto chaîne de connexion spécifiant le point de terminaison Kusto qui gère l’ingestion. Cette valeur doit être placée entre guillemets doubles.	✔️
-database, -db	`string`	Nom de la base de données Azure Data Explorer cible.
-table	`string`	Nom de la table azure Data Explorer cible.	✔️
-sourcePath, -source	`string`	Emplacement des données sources, qui peut être un chemin de fichier local, l’URI racine d’un conteneur d’objets 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é de compte de stockage ou la signature d’accès partagé (SAP). Si les données se situent dans un compartiment S3, l’URI doit inclure la clé d’informations d’identification. Nous vous recommandons de placer cette valeur entre guillemets doubles. Pour plus d’informations, consultez Chaînes de connexion de stockage. Pass -sourcePath :; emprunt d’identité pour répertorier les éléments de stockage Azure avec des autorisations utilisateur (autorisation d’invite de l’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 « system » pour l’identité affectée par le système.
-ingestWithManagedIdentity, -imgestmi	`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 « system » pour l’identité affectée par le système.
-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 de 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`	Chemin d’accès à un fichier local pour le mappage de colonnes d’ingestion. Consultez Mappages de données.
-ingestionMappingRef, -mappingRef	`string`	Nom d’un mappage de colonne d’ingestion créé précédemment 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. Consultez Comment ingérer des données à l’aide de `CreationTime`.
-ignoreFirstRow, -ignoreFirst	`bool`	S’il est défini, 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 la valeur `true`est définie sur , 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 taille d’origine divisée par taille compressée.
-limit, -l	entier	Si cette option est définie, limite l’ingestion aux premiers fichiers N .
-listOnly, -list	`bool`	Si cette option est définie, 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 `false`sur , 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é) de chaque opération d’ingestion.
-filesInBatch	entier	Définit la limite de nombre de fichiers/d’objets blob de chaque opération d’ingestion.
-devTracing, -trace	`string`	S’ils sont définis, les journaux de diagnostic sont écrits dans un répertoire local (par défaut, `RollingLogs` dans le répertoire actif, 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 objets blob Azure, LightIngest utilise certaines propriétés de métadonnées d’objet blob pour augmenter le processus d’ingestion.

Propriété de métadonnées	Usage
`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 LightIngest pour votre système d’exploitation. Si vous avez installé LightIngest en tant qu’outil .NET, remplacez par LightIngestLightIngest dans les exemples.

Ingérer des données historiques avec la propriété CreationTime

Lorsque vous chargez des données historiques du 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 se terminent
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 que les opérations d’ingestion se terminent

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 que les opérations d’ingestion se terminent

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 que les opérations d’ingestion se terminent
Les fichiers de trace de diagnostic sont écrits localement sous 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"