Uso de LightIngest para la ingesta de datos en Azure Data Explorer

LightIngest es una utilidad de línea de comandos para la ingesta de datos ad hoc en Azure Data Explorer. La utilidad puede extraer datos de origen de una carpeta local, un contenedor de Azure Blob Storage o un cubo de Amazon S3.

LightIngest es más útil cuando se desea ingerir una gran cantidad de datos, ya que no hay ninguna restricción de tiempo en la duración de la ingesta. También resulta útil si desea consultar posteriormente registros según la hora a la que se crearon y no según la hora a la que se ingirieron.

Para obtener un ejemplo de cómo generar automáticamente un comando LightIngest, consulte ingesta de datos históricos.

Nota:

La ingesta admite un tamaño de archivo máximo de 6 GB. Se recomienda ingerir archivos de entre 100 MB y 1 GB.

Requisitos previos

LightIngest. Obtenga LightIngest de una de estas dos maneras:
- Descargar archivos binarios de LightIngest para el sistema operativo. Asegúrese de descomprimir los archivos binarios después de la descarga.
- Instalar LightIngest como herramienta .NET. Este método requiere que tenga instalada la versión 6.0 o posterior del SDK de .NET en el equipo. Ejecute el siguiente comando:
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

Nota:

Considere la posibilidad de usar los comandos de ingesta en cola, ya que no requieren la instalación de software.

Ejecución de LightIngest

Para ejecutar LightIngest:

En el símbolo del sistema, escriba LightIngest seguido del argumento de la línea de comandos apropiado.

Sugerencia

Para obtener una lista de los argumentos de línea de comandos admitidos, escriba LightIngest /help.

Escriba ingest- seguido de la cadena de conexión al clúster de Azure Data Explorer que administra la ingesta. Ponga la cadena de conexión entre comillas dobles y siga la especificación de las cadenas de conexión de Kusto.

Por ejemplo:

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

Recomendaciones de rendimiento

Para administrar mejor la carga de ingesta y recuperarse de errores transitorios, use el punto de conexión de ingesta en https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.
Para obtener un rendimiento óptimo de ingesta, LightIngest necesita el tamaño de datos sin procesar para que pueda calcular el tamaño sin comprimir de los archivos locales. De todos modos es posible que LightIngest no pueda calcular correctamente el tamaño sin procesar de los blobs comprimidos sin descargarlos primero. Por lo tanto, cuando realice la ingesta de blobs comprimidos, establezca la propiedad rawSizeBytes de los metadatos de blob en el tamaño de los datos sin comprimir en bytes.

Argumentos de la línea de comandos

Argument	Type	Descripción	Obligatorio
	`string`	Kusto cadena de conexión que especifica el punto de conexión de Kusto que controla la ingesta. Incluya este valor entre comillas dobles.	✔️
-base de datos, -db	`string`	Nombre de la base de datos de Azure Data Explorer de destino.
-table	`string`	Nombre de la tabla de Azure Data Explorer de destino.	✔️
-sourcePath, -source	`string`	Ubicación de los datos de origen, que puede ser una ruta de acceso de archivo local, el URI raíz de un contenedor de blobs de Azure o el URI de un cubo de Amazon S3. Si los datos se almacenan en blobs de Azure, el URI debe incluir la clave de la cuenta de almacenamiento o la firma de acceso compartido (SAS). Si los datos están en un cubo de S3, el URI debe incluir la clave de credencial. Incluya este valor entre comillas dobles. Para obtener más información, consulte Cadenas de conexión de Storage. Pasar -sourcePath:; suplantar para enumerar elementos de Almacenamiento de Azure con permisos de usuario (autorización de petición de usuario).	✔️
-identidad administrada, -mi	`string`	Id. de cliente de la identidad administrada (asignada por el usuario o asignada por el sistema) que se va a usar para conectarse. Use "system" para la identidad asignada por el sistema.
-azCli	`bool`	Si se establece, usa la CLI de Azure para autenticarse en el servicio Kusto. La CLI de Azure debe instalarse e iniciar sesión.
-ingestWithManagedIdentity, -ingestmi	`string`	Identificador de cliente de la identidad administrada (asignada por el usuario o asignada por el sistema) instalada en el servicio Kusto para descargar desde el almacenamiento. Use "system" para la identidad asignada por el sistema.
-connectToStorageWithManagedIdentity, -storageMi	`string`	Id. de cliente de la identidad administrada (asignada por el usuario o asignada por el sistema) instalada en el lado cliente para enumerar desde el almacenamiento.
-connectToStorageWithUserAuth, -storageUserAuth	`string`	Autentíquese en el servicio de almacenamiento del origen de datos con credenciales de usuario. Las opciones de este valor son `PROMPT` o `DEVICE_CODE`.
-connectToStorageLoginUri, -storageLoginUri	`string`	Si `-connectToStorageWithUserAuth` se establece, puede proporcionar opcionalmente un URI de inicio de sesión de ID de Microsoft Entra.
-prefix	`string`	Cuando los datos de origen para la ingesta residen en un almacenamiento de blobs, todos los blobs comparten este prefijo de dirección URL, excepto el nombre del contenedor. Por ejemplo, si los datos están en `MyContainer/Dir1/Dir2`, el prefijo debe ser `Dir1/Dir2`. Incluya este valor entre comillas dobles.
-pattern	`string`	Patrón por el que se seleccionan los archivos de origen y los blobs. Admite caracteres comodín. Por ejemplo, `"*.csv"`. Incluya este valor entre comillas dobles.
-zipPattern	`string`	Expresión regular que se usa al seleccionar cuáles son los archivos de un archivo ZIP que se van a ingerir. Se omiten todos los demás archivos del archivo. Por ejemplo, `"*.csv"`. Incluya este valor entre comillas dobles.
-formato, -f	`string`	Formato de datos de origen. Tiene que ser uno de los formatos admitidos
-ingestionMappingPath, -mappingPath	`string`	Ruta de acceso a un archivo local para la asignación de columnas de ingesta. Vea Asignaciones de datos.
-ingestionMappingRef, -mappingRef	`string`	El nombre de un mapeo de columnas de ingesta que creó anteriormente en la tabla. Vea Asignaciones de datos.
-creationTimePattern	`string`	Cuando se establece, se usa para extraer la propiedad CreationTime de la ruta de acceso del archivo o del blob. Consulte Cómo ingerir datos mediante `CreationTime`.
-ignoreFirstRow, -ignoreFirst	`bool`	Si se establece, se omite el primer registro de cada archivo o blob. Por ejemplo, si los datos de origen tienen encabezados.
-tag	`string`	Etiquetas para asociar con los datos ingeridos. Se permiten repeticiones.
-dontWait	`bool`	Si se establece en `true`, no espera la finalización de la ingesta. Útil al procesar grandes cantidades de archivos y blobs.
-compression, -cr	doble	Sugerencia de razón de compresión. Es útil al ingerir archivos comprimidos y blobs, ya que facilita que Azure Data Explorer evalúe el tamaño de los datos sin procesar. Se calcula como tamaño original dividido por tamaño comprimido.
-límite, -l	integer	Si se establece, limita la ingesta a primero archivos N.
-listOnly, -list	`bool`	Si se establece, solo muestra los elementos que se seleccionarían para la ingesta.
-ingestTimeout	integer	Tiempo de expiración en minutos para la finalización de todas las operaciones de ingesta. Tiene como valor predeterminado `60`.
-forceSync	`bool`	Si se establece, fuerza la ingesta sincrónica. Tiene como valor predeterminado `false`.
-interactivo	`bool`	Si se establece en `false`, no solicita confirmación de argumentos. Para flujos desatendidos y entornos no interactivos. El valor predeterminado es `true`.
-dataBatchSize	integer	Establece el límite de tamaño total (MB, sin comprimir) de cada operación de ingesta.
-filesInBatch	integer	Establece el límite de recuento de archivos y blobs de cada operación de ingesta.
-devTracing, -trace	`string`	Si se establece, los registros de diagnóstico se escriben en un directorio local (de manera predeterminada, `RollingLogs` en el directorio actual o se pueden modificar estableciendo el valor del modificador).

Funcionalidades específicas de blobs de Azure

Cuando usas LightIngest con blobs de Azure, el uso de ciertas propiedades de metadatos de blob optimiza el proceso de ingesta.

Propiedad de metadatos	Uso
`rawSizeBytes`, `kustoUncompressedSizeBytes`	Si se establece, LightIngest interpreta estas propiedades como el tamaño de datos sin comprimir.
`kustoCreationTime`, `kustoCreationTimeUtc`	LightIngest interpreta estas propiedades como marca de tiempo UTC. Si se establece, usa estas propiedades para invalidar la hora de creación en Kusto. Esta característica es útil para escenarios de reposición

Ejemplos de uso

En los ejemplos siguientes se supone que instaló archivos binarios de LightIngest para el sistema operativo. Si instaló LightIngest como una herramienta .NET, sustituya LightIngest por LightIngest en los ejemplos.

Ingesta de datos históricos con la propiedad CreationTime

Al cargar datos históricos de un sistema existente en Azure Data Explorer, todos los registros obtienen la misma fecha de ingesta. Para particionar los datos por hora de creación en lugar de tiempo de ingesta, use el -creationTimePattern argumento . El argumento -creationTimePattern extrae la propiedad CreationTime de la ruta de acceso del archivo o del blob. El patrón no necesita representar toda la ruta de acceso del elemento, solo la sección que incluye la marca de tiempo que quiera utilizar.

Entre los valores de argumento se debe incluir lo siguiente:

Texto de constantes inmediatamente antes del formato de marca de tiempo, entre comillas simples (prefijo).
El formato de marca de tiempo, en notación DateTime de .NET estándar.
Texto de constantes que sigue inmediatamente a la marca de tiempo (sufijo).

Importante

Al especificar que se debe invalidar la hora de creación, asegúrese de que la Lookback propiedad de la directiva de combinación extensiones efectivas de la tabla de destino se alinea con los valores de las rutas de acceso de archivo o blob.

Ejemplos

Un nombre de blob que contiene la fecha y hora de la siguiente manera: historicalvalues19840101.parquet (la marca de tiempo tiene cuatro dígitos para el año, dos dígitos para el mes y dos dígitos para el día del mes).

El valor del argumento -creationTimePattern forma parte del nombre de archivo: "'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
```

Para un identificador URI de blob que hace referencia a una estructura de carpetas jerárquica, como https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

El valor del argumento -creationTimePattern forma parte de la estructura de carpetas: "'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

Ingesta de blobs mediante una clave de cuenta de almacenamiento o un token de SAS

Realice la ingesta de 10 blobs en la cuenta de almacenamiento especificada ACCOUNT, en la carpeta DIR, dentro del contenedor CONT, y que coincidan con el patrón *.csv.gz
El destino es la base de datos DB, tabla TABLE y la asignación de ingesta MAPPING ya se ha creado con anterioridad en el destino
La herramienta espera hasta que se completen las operaciones de ingesta.
Tenga en cuenta las diferentes opciones para especificar la base de datos de destino y la clave de la cuenta de almacenamiento frente al Token de 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

Ingesta de todos los blobs de un contenedor, sin incluir las filas de encabezado

Realice la ingesta de todos los blobs de la cuenta de almacenamiento especificada ACCOUNT, en la carpeta DIR1/DIR2, dentro del contenedor CONT, y que coincidan con el patrón *.csv.gz.
El destino es la base de datos DB, tabla TABLE y la asignación de ingesta MAPPING ya se ha creado con anterioridad en el destino
Los blobs de origen contienen una línea de encabezado, por lo que se indica a la herramienta que anule el primer registro de cada blob.
La herramienta publica los datos para la ingesta y no espera a que se completen las operaciones de ingesta

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

Ingesta de todos los archivos JSON de una ruta de acceso

Ingerir todos los archivos en la ruta PATH que coincidan con el patrón *.json
Establezca el destino en la base de datos DB, tabla TABLE, y defina la asignación de ingesta en el archivo local MAPPING_FILE_PATH.
La herramienta publica los datos para la ingesta y no espera a que se completen las operaciones de ingesta

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

** Procesamiento de archivos y generación de archivos de seguimiento de diagnóstico

Ingerir todos los archivos en la ruta PATH que coincidan con el patrón *.json
Establezca el destino en la base de datos DB, tabla TABLE, y defina la asignación de ingesta en el archivo local MAPPING_FILE_PATH.
La herramienta publica los datos para la ingesta y no espera a que se completen las operaciones de ingesta
Escribir archivos de seguimiento de diagnóstico localmente en la carpeta 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"

Autenticación con una identidad administrada

LightIngest realiza tres acciones que pueden usar la identidad administrada para la autenticación. El uso de identidad administrada en cada paso no requiere el uso de identidad administrada en otros pasos. Para cada acción, se da el argumento de la línea de comandos relacionado.

Conectar al clúster de Kusto: para poner en cola la ingesta, la herramienta usa una cadena de conexión. Use el argumento "-mi" para especificar una identidad administrada instalada en la máquina virtual cliente que tiene privilegios de ingesta en la base de datos de destino.
Conectarse a Azure Storage para descargar blobs: use "-ingestmi" para especificar una identidad administrada instalada en el servicio Kusto que tenga privilegios de lectura en el contenedor de almacenamiento.
Conectar a Azure Storage para enumerar blobs de contenedor: use el argumento "-storageMi" para especificar una identidad administrada instalada en la máquina virtual cliente que tenga privilegios de lista en el contenedor de almacenamiento. Si usa este método pero no el anterior (conéctese a Azure Storage para descargar blobs), la identidad administrada también debe tener privilegios de lectura y se pasa un token al servicio Kusto que se usará para la ingesta. Establezca los tres argumentos.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-18