Compartir a través de

Operador externaldata

  • Artículo

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.

Nota:

El externaldata operador admite un conjunto específico de servicios de almacenamiento, como se muestra en Almacenamiento cadena de conexión s.

Nota:

El externaldata operador admite la clave de firma de acceso compartido (SAS), la clave de acceso y los métodos de autenticación de token de Microsoft Entra. Para más información, consulte Métodos de autenticación de almacenamiento.

Nota:

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.

Sintaxis

externaldatacolumnName:columnType [, ...] )[ (storageConnectionString [ ...] ] [with ( , propertyName = propertyValue [, ...]])

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

Parámetros

Nombre Type Obligatorio Descripción
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.

Propiedades admitidas

Propiedad Tipo Descripción
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.

Nota:

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.

Devoluciones

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.

Ejemplos

Captura de una lista de identificadores de usuario almacenados en Azure Blob Storage

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. 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" 
      h@"?...SAS..." // Secret token needed to access the blob
    ]))
| ...

Consulta de varios archivos de datos

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.

Nota:

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

Consulta de formatos de datos jerárquicos

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.

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