operador externaldata

O externaldata operador devolve uma tabela cujo esquema é definido na própria consulta e cujos dados são lidos a partir de um artefacto de armazenamento externo, como um blob no Armazenamento de Blobs do Azure ou um ficheiro no Azure Data Lake Storage.

Nota

O externaldata operador suporta um conjunto específico de serviços de armazenamento, conforme listado em Cadeias de ligação de armazenamento.

Nota

O externaldata operador suporta a chave de Assinatura de Acesso Partilhado (SAS), a chave de Acesso e os métodos de autenticação de tokens de Microsoft Entra. Para obter mais informações, veja Métodos de autenticação de armazenamento.

Nota

Utilize o externaldata operador para obter pequenas tabelas de referência de até 100 MB de um artefacto de armazenamento externo. O operador não foi concebido para grandes volumes de dados. Para obter grandes volumes de dados externos, recomendamos que ingira os dados externos no Log Analytics como registos personalizados. Este operador não é suportado quando o ponto final público do artefacto de armazenamento está protegido por uma firewall.

Syntax

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Tipo	Necessário	Descrição
columnName, columnType	string	✔️	Uma lista de nomes de colunas e os respetivos tipos. Esta lista define o esquema da tabela.
storageConnectionString	string	✔️	Uma cadeia de ligação de armazenamento do artefacto de armazenamento a consultar.
propertyName, propertyValue	string		Uma lista de propriedades suportadas opcionais que determina como interpretar os dados obtidos do armazenamento.

Propriedades suportadas

Propriedade	Tipo	Description
formato	string	O formato de dados. Se não for especificado, é efetuada uma tentativa de detetar o formato de dados da extensão de ficheiro. A predefinição é CSV. Todos os formatos de dados de ingestão são suportados.
ignoreFirstRecord	bool	Se estiver definido como true, o primeiro registo em cada ficheiro é ignorado. Esta propriedade é útil ao consultar ficheiros CSV com cabeçalhos.
ingestãoMapping	string	Indica como mapear dados do ficheiro de origem para as colunas reais no conjunto de resultados do operador. Veja mapeamentos de dados.

Nota

Este operador não aceita nenhuma entrada de pipeline.

Os limites de consulta padrão também se aplicam a consultas de dados externos.

Devoluções

O externaldata operador devolve uma tabela de dados do esquema especificado cujos dados foram analisados a partir do artefacto de armazenamento especificado, indicado pelo cadeia de ligação de armazenamento.

Exemplos

Obter uma lista de IDs de utilizador armazenados no Armazenamento de Blobs do Azure

O exemplo seguinte mostra como localizar todos os registos numa tabela cuja UserID coluna se insere num conjunto conhecido de IDs, mantidos (um por linha) num ficheiro de armazenamento externo. Uma vez que o formato de dados não é especificado, o formato de dados detetado é 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
    ]))
| ...

Consultar vários ficheiros de dados

O exemplo seguinte consulta vários ficheiros de dados armazenados no armazenamento 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

O exemplo acima pode ser considerado uma forma rápida de consultar vários ficheiros de dados sem definir uma tabela externa.

Nota

A criação de partições de dados não é reconhecida pelo externaldata operador.

Consultar formatos de dados hierárquicos

Para consultar o formato de dados hierárquicos, como JSON, Parquet, Avroou ORC, ingestionMapping tem de ser especificado nas propriedades do operador. Neste exemplo, existe um ficheiro JSON armazenado no Armazenamento de Blobs do Azure com os seguintes conteúdos:

{
  "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 ficheiro com o externaldata operador , tem de ser especificado um mapeamento de dados. O mapeamento dita como mapear campos JSON para as colunas do conjunto de resultados do 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"}}]')

O MultiJSON formato é utilizado aqui porque os registos JSON individuais são divididos em múltiplas linhas.

Para obter mais informações sobre a sintaxe de mapeamento, veja mapeamentos de dados.