Ingesta desde almacenamiento
Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer
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] into table TableName SourceDataLocator [with ( IngestionPropertyName = IngestionPropertyValue [, ...] )]
Obtenga más información sobre las convenciones de sintaxis.
Parámetros
| Nombre | Type | Obligatorio | 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 cadena 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 varios cadena de conexión o la ingesta desde una consulta de una tabla externa. |
Nota:
Se recomienda usar literales de cadena ofuscados para SourceDataLocators. 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 y describen las propiedades admitidas 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 usa el valor actual (now()). Invalidar el valor predeterminado es útil al ingerir datos más antiguos, de modo 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 más columnas 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 invalida 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']") |
TreatGzAsUncompressed |
Valor booleano que, si se establece en true, indica que los archivos con la extensión .gz no se comprimen. Esta marca a veces es necesaria al ingerir desde Amazon AWS S3. |
with (treatGzAsUncompressed=true) |
validationPolicy |
Cadena JSON que indica qué validaciones se van a ejecutar 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}') (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 omiten todos los demás 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 tenga que 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 la 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 | Escribir | 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 a la base de datos que lea dos blobs de Azure Blob Storage como archivos CSV e ingera 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')