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

  • Artículo

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 bucket 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

Ejecución de LightIngest

Para ejecutar LightIngest:

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

    Sugerencia

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

  2. Escriba ingest- seguido de la cadena de conexión al clúster de Azure Data Explorer que administrará 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 en la ingesta, se necesita conocer el tamaño de los datos sin procesar, por lo que LightIngest puede 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

Argumento Tipo Descripción Requerido
string Kusto cadena de conexión especificando el punto de conexión de Kusto que controla la ingesta. Este valor debe ir entre comillas dobles. ✔️
-database, -db string Nombre de la base de datos de Azure Data Explorer de destino.
-table string El nombre de la tabla de Azure Data Explorer de destino. ✔️
-sourcePath, -source string La 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 bucket 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. Se recomienda incluir este valor entre comillas dobles. Para más información, consulte Cadenas de conexión de almacenamiento. Pass -sourcePath:; suplantar para enumerar los elementos de Almacenamiento de Azure con permisos de usuario (autorización de petición de usuario). ✔️
-managedIdentity, -mi string Identificador 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.
-ingestWithManagedIdentity, -imgestmi string Identificador 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.
-connectToStorageWithUserAuth, -storageUserAuth string Autentíquese en el servicio de almacenamiento de origen de datos con credenciales de usuario. Las opciones de este valor son PROMPT o DEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string Si -connectToStorageWithUserAuth se establece, opcionalmente puede proporcionar un URI de inicio de sesión de Microsoft Entra ID.
-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. Se recomienda incluir este valor entre comillas dobles.
-pattern string Patrón que se sigue para seleccionar los archivos o blobs de origen. Admite caracteres comodín. Por ejemplo, "*.csv". Se recomienda incluir 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 omitirán los restantes archivos del archivo. Por ejemplo, "*.csv". Se recomienda incluir este valor entre comillas dobles.
-format, -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 Nombre de una asignación de columnas de ingesta que se 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 Ingesta de 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 trueen , no espera la finalización de la ingesta. Resulta útil al ingerir grandes cantidades de archivos o blobs.
-compression, -cr double Sugerencia de razón de compresión. Resulta útil cuando se realiza la ingesta de archivos o blobs comprimidos para ayudar a Azure Data Explorer a evaluar el tamaño de los datos sin procesar. Se calcula como tamaño original dividido por tamaño comprimido.
-limit, -l integer Si se establece, limita la ingesta a los primeros archivos N .
-listOnly, -list bool Si se establece, solo muestra los elementos que se habrían seleccionado 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 o 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 forma predeterminada, RollingLogs en el directorio actual o se pueden modificar estableciendo el valor del modificador).

Funcionalidades específicas de blobs de Azure

Cuando se usa con blobs de Azure, LightIngest usa determinadas propiedades de metadatos de blob para aumentar el proceso de ingesta.

Propiedad de metadatos Uso
rawSizeBytes, kustoUncompressedSizeBytes Si se establece, se interpretará como el tamaño de los datos sin comprimir
kustoCreationTime, kustoCreationTimeUtc Se interpreta como una marca de tiempo en formato UTC. Si se establece, se usará para invalidar la hora de creación en Kusto. Útil para escenarios de reposición

Ejemplos de uso

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

Ingesta de datos históricos con la propiedad CreationTime

Al cargar datos históricos del sistema existente en Azure Data Explorer, todos los registros reciben la misma fecha de ingesta. Para habilitar la creación de particiones de los datos según la hora de creación y no según la hora de ingesta, puede usar el argumento -creationTimePattern. El argumento -creationTimePattern extrae la propiedad CreationTime de la ruta de acceso del archivo o del blob. No es necesario que el patrón refleje la ruta de acceso completa del elemento, basta con la sección que contiene la marca de tiempo que se quiere usar.

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 propiedad Lookback de la directiva de combinación de extensiones vigente de la tabla de destino esté en línea con los valores de las rutas de acceso del archivo o del 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 con 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 una 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

  • Realice la ingesta de todos los archivos de la ruta de acceso PATH, que coinciden con el patrón *.json
  • El destino es la base de datos DB, tabla TABLE y la asignación de ingesta está definida 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"

Ingesta de archivos y escritura de archivos de seguimiento de diagnóstico

  • Realice la ingesta de todos los archivos de la ruta de acceso PATH, que coinciden con el patrón *.json
  • El destino es la base de datos DB, tabla TABLE y la asignación de ingesta está definida 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.
  • Los archivos de seguimiento de diagnóstico se escriben 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"