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.
- LightIngest. Hay dos maneras de obtener LightIngest:
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
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 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
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.
Argument | Type | Descripción | Obligatorio |
---|---|---|---|
string |
Kusto cadena de conexión que especifica 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 |
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. Se recomienda incluir 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). | ✔️ |
-managedIdentity, -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 identificador 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 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 ingerir grandes cantidades de archivos o blobs. |
|
-compression, -cr | doble | 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 primero 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 manera predeterminada, RollingLogs en el directorio actual o se pueden modificar estableciendo el valor del modificador). |
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. |
En los ejemplos siguientes se supone que ha instalado archivos binarios de LightIngest para el sistema operativo. Si ha instalado LightIngest como una herramienta .NET, sustituya LightIngest
por LightIngest
en los ejemplos.
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
- Realice la ingesta de 10 blobs en la cuenta de almacenamiento especificada
ACCOUNT
, en la carpetaDIR
, dentro del contenedorCONT
, y que coincidan con el patrón*.csv.gz
- El destino es la base de datos
DB
, tablaTABLE
y la asignación de ingestaMAPPING
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
- Realice la ingesta de todos los blobs de la cuenta de almacenamiento especificada
ACCOUNT
, en la carpetaDIR1/DIR2
, dentro del contenedorCONT
, y que coincidan con el patrón*.csv.gz
. - El destino es la base de datos
DB
, tablaTABLE
y la asignación de ingestaMAPPING
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
- 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
, tablaTABLE
, y la asignación de ingesta ya se ha creado con anterioridad en el destino. - 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"
- 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
, tablaTABLE
, y la asignación de ingesta ya se ha creado con anterioridad en el destino. - 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"
Hay tres acciones que LightIngest realiza 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 pasará un token al servicio Kusto que se usará para la ingesta. Por lo tanto, se recomienda establecer los tres argumentos.