Compartir a través de

Operador de datos externos

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

El externaldata operador devuelve una tabla cuyo esquema se define en la propia consulta y cuyos datos se leen desde un artefacto de almacenamiento externo, como un blob en Azure Blob Storage o un archivo de Azure Data Lake Storage.

Note

El operador externaldata admite:

  • un conjunto específico de servicios de almacenamiento, como se muestra en Cadenas de conexión de almacenamiento.
  • Clave de firma de acceso compartido (SAS), clave de acceso, token de Microsoft Entra y métodos de autenticación de identidad administrada. Para más información, consulte Métodos de autenticación de almacenamiento.

Note

El operador externaldata admite:

  • un conjunto específico de servicios de almacenamiento, como se muestra en Cadenas de conexión de almacenamiento.
  • clave de firma de acceso compartido (SAS), clave de acceso y métodos de autenticación de token de Microsoft Entra. Para más información, consulte Métodos de autenticación de almacenamiento.

Note

Use el externaldata operador para recuperar tablas de referencia pequeñas de hasta 100 MB desde un artefacto de almacenamiento externo. El operador no está diseñado para grandes volúmenes de datos. Para recuperar grandes volúmenes de datos externos, se recomienda ingerir los datos externos en Log Analytics como registros personalizados. Este operador no se admite cuando el punto de conexión público del artefacto de almacenamiento está detrás de un firewall.

Syntax

externaldatacolumnName( [ ...] [:,)[ [ ...]],

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

Parameters

Name Type Required Description
columnName, columnType string ✔️ Lista de nombres de columna y sus tipos. Esta lista define el esquema de la tabla.
storageConnectionString string ✔️ Un almacenamiento cadena de conexión del artefacto de almacenamiento que se va a consultar.
propertyName, propertyValue string Lista de propiedades opcionales admitidas que determina cómo interpretar los datos recuperados del almacenamiento.

[! WARN] Por motivos de seguridad, asegúrese de que la propiedad storageConnectionString no especifica ninguna credencial. Si la consulta necesita especificar credenciales, use parámetros de consulta para especificar toda la cadena de conexión.

Por ejemplo, suponiendo que la consulta incluya un parámetro de consulta denominado URI cuyos puntos de valor en Blob Storage, la consulta tendría este aspecto:

declare query_parameters(URI:string);
externaldata(x:string)[URI]

Si esto no es posible (por ejemplo, usa un cliente que no admite la configuración de parámetros de consulta), asegúrese de usar literales de cadena ofuscados.

Propiedades compatibles

Property Type Description
format string El formato de datos. Si no se especifica, se intenta detectar el formato de datos de la extensión de archivo. El valor predeterminado es CSV. Se admiten todos los formatos de datos de ingesta.
ignoreFirstRecord bool Si se establece trueen , se omite el primer registro de cada archivo. Esta propiedad es útil cuando se consultan archivos .csv con encabezados.
ingestionMapping string Indica cómo asignar datos del archivo de origen a las columnas reales del conjunto de resultados del operador. Vea Asignaciones de datos.

Note

Este operador no acepta ninguna entrada de canalización.

Los límites de consulta estándar también se aplican a las consultas de datos externos.

Returns

El externaldata operador devuelve una tabla de datos del esquema especificado cuyos datos se analizaron desde el artefacto de almacenamiento especificado, indicado por el cadena de conexión de almacenamiento.

Examples

En el ejemplo siguiente se muestra cómo buscar todos los registros de una tabla cuya UserID columna se encuentra en un conjunto conocido de identificadores, mantenidos (uno por línea) en un archivo de almacenamiento externo almacenado en Azure Blob Storage. Dado que no se especifica el formato de datos, el formato de datos detectado es TXT.

Users
| where UserID in ((externaldata (UserID:string) [
    @"https://storageaccount.blob.core.windows.net/storagecontainer/users.txt;managed_identity=..."
    ]))
| ...

En el ejemplo siguiente se consultan varios archivos de datos almacenados en almacenamiento externo.

externaldata(Timestamp:datetime, ProductId:string, ProductDescription:string)
[
  h@"https://mycompanystorage.blob.core.windows.net/archivedproducts/2019/01/01/part-00000-7e967c99-cf2b-4dbb-8c53-ce388389470d.csv.gz?...SAS...",
  h@"https://mycompanystorage.blob.core.windows.net/archivedproducts/2019/01/02/part-00000-ba356fa4-f85f-430a-8b5a-afd64f128ca4.csv.gz?...SAS...",
  h@"https://mycompanystorage.blob.core.windows.net/archivedproducts/2019/01/03/part-00000-acb644dc-2fc6-467c-ab80-d1590b23fc31.csv.gz?...SAS..."
]
with(format="csv")
| summarize count() by ProductId

El ejemplo anterior se puede considerar como una manera rápida de consultar varios archivos de datos sin definir una tabla externa.

Note

El operador no reconoce externaldata la creación de particiones de datos.

Para consultar el formato de datos jerárquico, como JSON, Parquet, Avroo ORC, ingestionMapping debe especificarse en las propiedades del operador. En este ejemplo, hay un archivo JSON almacenado en Azure Blob Storage con el siguiente contenido:

{
  "timestamp": "2019-01-01 10:00:00.238521",   
  "data": {    
    "tenant": "e1ef54a6-c6f2-4389-836e-d289b37bcfe0",   
    "method": "RefreshTableMetadata"   
  }   
}   
{
  "timestamp": "2019-01-01 10:00:01.845423",   
  "data": {   
    "tenant": "9b49d0d7-b3e6-4467-bb35-fa420a25d324",   
    "method": "GetFileList"   
  }   
}
...

Para consultar este archivo mediante el externaldata operador , se debe especificar una asignación de datos. La asignación determina cómo asignar campos JSON a las columnas del conjunto de resultados del operador:

externaldata(Timestamp: datetime, TenantId: guid, MethodName: string)
[ 
   h@'https://mycompanystorage.blob.core.windows.net/events/2020/09/01/part-0000046c049c1-86e2-4e74-8583-506bda10cca8.json?...SAS...'
]
with(format='multijson', ingestionMapping='[{"Column":"Timestamp","Properties":{"Path":"$.timestamp"}},{"Column":"TenantId","Properties":{"Path":"$.data.tenant"}},{"Column":"MethodName","Properties":{"Path":"$.data.method"}}]')

El MultiJSON formato se usa aquí porque los registros JSON únicos se abarcan en varias líneas.

Contenido relacionado

Para más información sobre la sintaxis de asignación, consulte asignaciones de datos.

  • Last updated on