Operador externaldata

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 en Azure Data Lake Storage.

Nota

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

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.

Syntax

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

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

Parámetros

Nombre	Tipo	Requerido	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 admitidas opcionales 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 la externaldata creación de particiones de datos.

Consulta de formatos de datos jerárquicos

Para consultar el formato de datos jerárquico, como JSON, AvroParquet, o 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.