Partilhar via

operador de dados externos

  • Artigo

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

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

Observação

O operador externaldata suporta:

Observação

Use o operador externaldata para recuperar pequenas tabelas de referência de até 100 MB de um artefato de armazenamento externo. O operador não foi projetado para grandes volumes de dados. Para recuperar grandes volumes de dados externos, recomendamos ingerir os dados externos no Log Analytics como logs personalizados. Este operador não é suportado quando o ponto de extremidade público do artefato de armazenamento está atrás de um firewall.

Sintaxe

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

Saiba mais sobre convenções de sintaxe.

Parâmetros

Designação Tipo Necessário Descrição
columnName, columnType string ✔️ Uma lista de nomes de colunas e seus tipos. Esta lista define o esquema da tabela.
storageConnectionString string ✔️ Uma cadeia de conexão de armazenamento do artefato de armazenamento a ser consultado.
propertyName, propertyValue string Uma lista de propriedades opcionais suportadas que determina como interpretar os dados recuperados do armazenamento.

Propriedades suportadas

Propriedade Tipo Descrição
Formato string O formato dos dados. Se não for especificado, é feita uma tentativa para detetar o formato de dados da extensão do arquivo. O padrão é CSV. Todos os formatos de dados de ingestão são suportados.
ignoreFirstRecord bool Se definido como true, o primeiro registro em cada arquivo será ignorado. Essa propriedade é útil ao consultar arquivos CSV com cabeçalhos.
ingestãoMapeamento string Indica como mapear dados do arquivo de origem para as colunas reais no conjunto de resultados do operador. Consulte mapeamentos de dados.

Observação

Este operador não aceita nenhuma entrada de pipeline.

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

Devoluções

O operador externaldata retorna uma tabela de dados do esquema fornecido cujos dados foram analisados a partir do artefato de armazenamento especificado, indicado pela cadeia de conexão de armazenamento.

Exemplos

Os exemplos consultam dados em um arquivo de armazenamento externo.

Buscar uma lista de IDs de usuário armazenadas no Armazenamento de Blobs do Azure

O exemplo a seguir mostra como localizar todos os registros em uma tabela cuja coluna UserID se enquadra em um conjunto conhecido de IDs, mantidos (um por linha) em um arquivo de armazenamento externo. Como 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 arquivos de dados

O exemplo a seguir consulta vários arquivos de dados armazenados em 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 pensado como uma maneira rápida de consultar vários arquivos de dados sem definir uma tabela externa .

Observação

O particionamento de dados não é reconhecido pelo operador externaldata.

Formatos de dados hierárquicos de consulta

Para consultar o formato de dados hierárquicos, como JSON, Parquet, Avroou ORC, ingestionMapping deve ser especificado nas propriedades do operador. Neste exemplo, há um arquivo JSON armazenado no Armazenamento de Blobs do Azure com o seguinte conteúdo:

{
  "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 esse arquivo usando o operador externaldata, um mapeamento de dados deve ser especificado. 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 formato MultiJSON é usado aqui porque registros JSON únicos são distribuídos em várias linhas.

Conteúdo relacionado

Para saber mais sobre sintaxe de mapeamento, veja mapeamentos de dados.