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 o de un contenedor de almacenamiento de blobs de Azure. LightIngest resulta más útil cuando 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 generar automáticamente un comando LightIngest, consulte Uso del asistente para la ingesta única de datos históricos con LightIngest.

Prerrequisitos

• LightIngest: descárguelo como parte del paquete NuGet Microsoft.Azure.Kusto.Tools

  

• WinRAR: descárguelo de www.win-rar.com/download.html

Instalación de LightIngest

1. Vaya a la ubicación del equipo en donde descargó LightIngest.
2. Con WinRAR, extraiga el directorio tools en el equipo.

Ejecución de LightIngest

1. Vaya al directorio tools que ha extraído en el equipo.

2. En la barra de ubicación elimine la información de ubicación existente.

   

3. Escriba cmd y presione cmd.

4. En el símbolo del sistema, escriba LightIngest.exe 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.exe /help.

   

5. 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:

   ingest-{Cluster name and region}.kusto.windows.net;AAD Federated Security=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

• El método recomendado permite que LightIngest funcione con el punto de conexión de ingesta en https://ingest-{yourClusterNameAndRegion}.kusto.windows.net. De esta manera, el servicio Azure Data Explorer puede administrar la carga de ingesta, y usted puede recuperarse fácilmente de los errores transitorios. De todas formas, también puede configurar LightIngest para que trabaje directamente con el punto de conexión del motor (https://{yourClusterNameAndRegion}.kusto.windows.net).

  Nota

  Si va a realizar la ingesta directamente con el punto de conexión del motor, no es necesario que incluya ingest-. No obstante, no habrá una característica DM para proteger el motor y mejorar la tasa de éxito de la ingesta.

• 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

Funcionalidades específicas de blobs de Azure

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

Ejemplos de uso

Ingesta de datos mediante CreationTime

Cuando se cargan datos históricos de un 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).

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: -creationTimePattern

  ingest-{Cluster name and region}.kusto.windows.net;AAD Federated Security=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/container/folder/2002/12/01/blobname.extension,

  El valor del argumento -creationTimePattern forma parte de la estructura de carpetas: -creationTimePattern

    ingest-{Cluster name and region}.kusto.windows.net;AAD Federated Security=True -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'folder/'yyyy/MM/dd'/blob'"
     -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 esperará 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.exe "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.exe "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 publicará los datos de la ingesta y no esperará a que se completen las operaciones de esta

LightIngest.exe "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 publicará los datos de la ingesta y no esperará a que se completen las operaciones de esta

LightIngest.exe "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 publicará los datos de la ingesta y no esperará a que se completen las operaciones de esta
• Los archivos de seguimiento de diagnóstico se escribirán localmente en la carpeta LOGS_PATH

LightIngest.exe "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"