Ingesta desde almacenamiento

El comando .ingest into ingiere datos en una tabla mediante la "extracción" de los datos de uno o varios archivos de almacenamiento en la nube. Por ejemplo, el comando puede recuperar 1000 blobs con formato CSV de Azure Blob Storage, analizarlos e ingerirlos juntos en una sola tabla de destino. Los datos se anexan a la tabla sin afectar a los registros existentes y sin modificar el esquema de la tabla.

Nota:

Este método de ingesta está diseñado para la exploración y la creación de prototipos. No lo use en escenarios de producción o de gran volumen.

Permisos

Debe tener al menos permisos de Ingeror de tabla para ejecutar este comando.

Sintaxis

.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

Más información sobre las convenciones de sintaxis.

Parámetros

Nombre	Tipo	Requerido	Descripción
async	string		Si se especifica, el comando devuelve inmediatamente y continúa la ingesta en segundo plano. Los resultados del comando incluyen un OperationId valor que se puede usar con el .show operation comando para recuperar el estado de finalización de la ingesta y los resultados.
TableName	string	✔️	Nombre de la tabla en la que se van a ingerir datos. El nombre de la tabla siempre es relativo a la base de datos en contexto. Si no se proporciona ningún objeto de asignación de esquemas, se usa el esquema de la base de datos en contexto.
SourceDataLocator	string	✔️	Una lista única o separada por comas de cadenas de conexión de almacenamiento. Una sola cadena de conexión debe hacer referencia a un único archivo hospedado por una cuenta de almacenamiento. La ingesta de varios archivos se puede realizar mediante la especificación de varias cadenas de conexión o la ingesta desde una consulta de una tabla externa.

Nota:

Se recomienda usar literales de cadena ofuscados para SourceDataPointer. El servicio limpiará las credenciales en seguimientos internos y mensajes de error.

Propiedades de la ingesta

Importante

• En los datos de ingesta en cola se procesan por lotes mediante propiedades de ingesta. Las propiedades de asignación de ingesta más distintas usadas, como los distintos valores de ConstValue, más fragmentados se convierten en la ingesta, lo que puede provocar una degradación del rendimiento.

En la tabla siguiente se enumeran las propiedades compatibles con Azure Data Explorer, se las describen y se proporcionan ejemplos:

Propiedad	Descripción	Ejemplo
ingestionMapping	valor de cadena que indica cómo se asignan los datos del archivo de origen a las columnas reales de la tabla. Defina el valor format con el tipo de asignación pertinente. Vea Asignaciones de datos.	with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]") (en desuso: avroMapping, csvMapping y jsonMapping)
ingestionMappingReference	valor de cadena que indica cómo se asignan los datos del archivo de origen a las columnas reales de la tabla mediante un objeto de directiva de asignación con nombre. Defina el valor format con el tipo de asignación pertinente. Vea Asignaciones de datos.	with (format="csv", ingestionMappingReference = "Mapping1") (en desuso: avroMappingReference, csvMappingReference y jsonMappingReference)
creationTime	El valor de fecha y hora (con formato de cadena ISO8601) que se usa en el momento de la creación de las extensiones de los datos ingeridos. Si no se especifica, se utilizará el valor actual (now()). Cuando se ingieren datos antiguos, es útil reemplazar el valor predeterminado para que la directiva de retención se aplique correctamente. Si se especifica, 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 el valor especificado.	with (creationTime="2017-02-13")
extend_schema	valor booleano que, si se especifica, indica al comando que extienda el esquema de la tabla (el valor predeterminado es false). Esta opción solo se aplica a los comandos .append y .set-or-append. Las únicas extensiones de esquema permitidas tienen columnas adicionales agregadas a la tabla al final.	Si el esquema de tabla original es (a:string, b:int), una extensión de esquema válida sería (a:string, b:int, c:datetime, d:string), pero (a:string, c:datetime) no lo sería.
folder	En el caso de los comandos de ingesta desde consulta, la carpeta que se va a asignar a la tabla. Si la tabla ya existe, esta propiedad invalidará la carpeta de la tabla.	with (folder="Tables/Temporary")
format	El formato de los datos (consulte los formatos de datos compatibles).	with (format="csv")
ingestIfNotExists	valor de cadena que, si se especifica, impide que la ingesta se realice correctamente si la tabla ya tiene datos con la etiqueta ingest-by: con el mismo valor. Esto garantiza la ingesta de datos idempotente. Para más información, consulte Etiquetas "ingerir por".	Las propiedades with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') indican que, si ya existen datos con la etiqueta ingest-by:Part0001, no se completará la ingesta actual. Sin embargo, si aún no existen, esta nueva ingesta debería tener la etiqueta establecida (por si en el futuro se intentan ingerir de nuevo los mismos datos).
ignoreFirstRecord	valor booleano que, si se establece en true, indica que la ingesta debe omitir el primer registro de cada archivo. Esta propiedad es útil para los archivos con formato CSV y formatos similares, si el primer registro del archivo son los nombres de columna. De manera predeterminada, se presupone que es false.	with (ignoreFirstRecord=false)
policy_ingestiontime	valor booleano que, si se especifica, describe si se habilita la directiva de tiempo de ingesta en una tabla que este comando crea. El valor predeterminado es true.	with (policy_ingestiontime=false)
recreate_schema	valor booleano que, si se especifica, describe si el comando puede volver a crear el esquema de la tabla. Esta propiedad solo se aplica al comando .set-or-replace. Esta propiedad tiene prioridad sobre la propiedad extend_schema si ambas están establecidas.	with (recreate_schema=true)
tags	Una lista de etiquetas que se asocian a los datos ingeridos, cuyo formato es una cadena JSON.	with (tags="['Tag1', 'Tag2']")
validationPolicy	Cadena JSON que indica qué validaciones se ejecutarán durante la ingesta de datos representados mediante formato CSV. Consulte Ingesta de datos para una explicación de las distintas opciones.	with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (en realidad, esta es la directiva predeterminada).
zipPattern	Use esta propiedad al ingerir datos desde el almacenamiento que tiene un archivo ZIP. Se trata de un valor de cadena que indica la expresión regular que se va a usar al seleccionar los archivos del archivo ZIP que se van a ingerir. Se omitirán los restantes archivos del archivo.	with (zipPattern="*.csv")

Autenticación y autorización

Cada cadena de conexión de almacenamiento indica el método de autorización que se va a usar para el acceso al almacenamiento. Según el método de autorización, es posible que la entidad de seguridad deba conceder permisos en el almacenamiento externo para realizar la ingesta.

En la tabla siguiente se enumeran los métodos de autenticación admitidos y los permisos necesarios para ingerir datos del almacenamiento externo.

Método de autenticación	Azure Blob Storage/Data Lake Storage Gen2	Data Lake Storage Gen1
Suplantación	Lector de datos de blobs de almacenamiento	Lector
Token de acceso compartido (SAS)	Lista y lectura	Este método de autenticación no se admite en Gen1.
token de acceso de Microsoft Entra
Clave de acceso de cuenta de almacenamiento		Este método de autenticación no se admite en Gen1.
Identidad administrada	Lector de datos de blobs de almacenamiento	Lector

Devoluciones

El resultado del comando es una tabla con tantos registros como particiones de datos ("extensiones") generadas por el comando haya. Si no se han generado particiones de datos, se devuelve un único registro con un identificador de extensión vacío (con valor cero).

Nombre	Tipo	Descripción
ExtentId	guid	Identificador único de la partición de datos generada por el comando.
ItemLoaded	string	Uno o varios archivos de almacenamiento relacionados con este registro.
Duration	timespan	Tiempo que tardó en realizarse la ingesta.
HasErrors	bool	Si este registro representa un error de ingesta o no.
OperationId	guid	Identificador único que representa la operación. Se puede usar con el comando .show operation.

Nota:

Este comando no modifica el esquema de la tabla en la que se ingiere. Si es necesario, los datos se "convierten" en este esquema durante la ingesta, no al contrario (las columnas adicionales se omiten y las columnas que faltan se tratan como valores NULL).

Ejemplos

Azure Blob Storage con firma de acceso compartido

En el ejemplo siguiente se indica al clúster que lea dos blobs de Azure Blob Storage como archivos CSV e introduzca su contenido en la tabla T. ... representa una firma de acceso compartido (SAS) de Azure Storage que proporciona acceso de lectura a cada blob. Observe también el uso de cadenas ofuscadas (h delante de los valores de cadena) para asegurarse de que nunca se registre la firma de acceso compartido.

.ingest into table T (
    h'https://contoso.blob.core.windows.net/container/file1.csv?...',
    h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)

Azure Blob Storage con identidad administrada

En el ejemplo siguiente se muestra cómo leer un archivo CSV de Azure Blob Storage e ingerir su contenido en la tabla T mediante la autenticación de identidad administrada. Para más información sobre el método de autenticación de identidad administrada, consulte Introducción a la autenticación de identidad administrada.

.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')

Azure Data Lake Storage Gen 2

El ejemplo siguiente es para ingerir datos de Azure Data Lake Storage Gen 2 (ADLSv2). Las credenciales usadas aquí (...) son las credenciales de la cuenta de almacenamiento (clave compartida) y la ofuscación de cadenas solo se usa para la parte secreta de la cadena de conexión.

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)

Azure Data Lake Storage

En el ejemplo siguiente se ingiere un único archivo de Azure Data Lake Storage (ADLS). Usa las credenciales del usuario para acceder a ADLS (por lo que no es necesario tratar el URI de almacenamiento como si contuviera un secreto). También muestra cómo especificar las propiedades de ingesta.

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')

Amazon S3 con una clave de acceso

En el ejemplo siguiente se ingiere un único archivo de Amazon S3 mediante un identificador de clave de acceso y una clave de acceso secreta.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
  with (format='csv')

Amazon S3 con una dirección URL presignada

En el ejemplo siguiente se ingiere un único archivo de Amazon S3 mediante una dirección URL preSigned.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')