Compartir a través de

.ingest en

  • Artículo

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.

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. Para obtener más información sobre las opciones de ingesta, consulte Introducción a la ingesta de datos.

Permisos

Debe tener al menos permisos de de table Ingestor para ejecutar este comando.

Sintaxis

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

Obtenga más información sobre las convenciones de sintaxis de .

Parámetros

Nombre Tipo 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 valor de OperationId que se puede usar con el comando .show operation 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 de string ✔️ Una lista separada por comas o única 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 especificando varias cadenas de conexión o la ingesta desde una consulta de una tabla externa de .

Nota

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

Propiedades de ingesta

Importante

En la ingesta en cola los datos 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 asignar datos del archivo de origen a las columnas reales de la tabla. Defina el valor de format con el tipo de asignación correspondiente. Consulte asignaciones de datos. with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")
(en desuso: avroMapping, csvMapping, jsonMapping)
ingestionMappingReference Valor de cadena que indica cómo asignar 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 de format con el tipo de asignación correspondiente. Consulte asignaciones de datos. with (format="csv", ingestionMappingReference = "Mapping1")
(en desuso: avroMappingReference, csvMappingReference, jsonMappingReference)
creationTime Valor datetime (con formato de cadena de ISO8601) que se usará en el momento de creación de las extensiones de datos ingeridas. 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. Cuando se especifica, asegúrese de que la propiedad Lookback en la directiva de combinación de extensiones de de la tabla de destino esté alineada 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), se (a:string, b:int, c:datetime, d:string)una extensión de esquema válida, pero (a:string, c:datetime) no sería válido.
folder Para comandos de de ingesta desde consulta, la carpeta que se 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 datos (consulte formatos de datos admitidos). with (format="csv")
ingestIfNotExists Valor de cadena que, si se especifica, impide que la ingesta se realice correctamente si la tabla ya tiene datos etiquetados con una etiqueta ingest-by: con el mismo valor. Esto garantiza la ingesta de datos idempotentes. Para obtener más información, consulte ingest-by: etiquetas. Las propiedades with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') indican que si ya existen datos con la etiqueta ingest-by:Part0001, no complete la ingesta actual. Si aún no existe, esta nueva ingesta debe tener establecida esta etiqueta (en caso de que una ingesta futura intente volver a ingerir 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 en CSVy formatos similares, si el primer registro del archivo son los nombres de columna. De forma predeterminada, se supone false. with (ignoreFirstRecord=false)
policy_ingestiontime Valor booleano que, si se especifica, describe si se debe habilitar la directiva de tiempo de ingesta de en una tabla creada por este comando. 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 se establecen ambas. with (recreate_schema=true)
tags Lista de etiquetas de asociar a los datos ingeridos, con formato de 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 están comprimidos. 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 de ingesta de datos para obtener 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 del 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. En función del 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
de suplantación Lector de datos de Storage Blob Lector
token de acceso compartido (SAS) Lista y lectura Este método de autenticación no se admite en Gen1.
de 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.
de identidad administrada Lector de datos de Storage Blob Lector

Devuelve

El resultado del comando es una tabla con tantos registros como haya particiones de datos ("extensiones") generadas por el comando. Si no se generaron 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.
Duración timespan Cuánto tiempo tardó en realizar la ingesta.
HasErrors bool Si este registro representa o no un error de ingesta.
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 "coercieron" en este esquema durante la ingesta, no en el otro sentido (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. El ... representa una firma de acceso compartido (SAS) de Azure Storage que proporciona acceso de lectura a cada blob. Las cadenas ofuscadas (el h delante de los valores de cadena) se usan para asegurarse de que la SAS nunca se registra.

.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. La autenticación usa el identificador de identidad administrada (id. de objeto) asignado a Azure Blob Storage en Azure. Para obtener más información, consulte Creación de una identidad administrada para contenedores de almacenamiento.

.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 que se usan aquí (...) son las credenciales de la cuenta de almacenamiento (clave compartida) y usamos ofuscación de cadena solo 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 que contiene un secreto). También muestra cómo especificar 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')

Contenido relacionado