Compartilhar via

operador de dados externos

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

O externaldata operador 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 Azure Data Lake Storage.

Note

O operador externaldata dá suporte a:

  • um conjunto específico de serviços de armazenamento, conforme listado em cadeias de conexão de armazenamento .
  • chave SAS (assinatura de acesso compartilhado), chave de acesso, token do Microsoft Entra e métodos de autenticação de Identidade Gerenciada. Para obter mais informações, consulte Métodos de autenticação de armazenamento.

Note

O operador externaldata dá suporte a:

  • um conjunto específico de serviços de armazenamento, conforme listado em cadeias de conexão de armazenamento .
  • chave SAS (assinatura de acesso compartilhado), chave de acesso e métodos de autenticação de token do Microsoft Entra. Para obter mais informações, consulte Métodos de autenticação de armazenamento.

Note

Use o externaldata operador 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. Não há suporte para esse operador quando o ponto de extremidade público do artefato de armazenamento está atrás de um firewall.

Syntax

externaldata ( columnName:columnType [, ...] )[

Saiba mais sobre as convenções de sintaxe.

Parameters

Name Tipo Required Description
columnName, columnType string ✔️ Uma lista de nomes de coluna 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 com suporte que determina como interpretar os dados recuperados do armazenamento.

[! AVISO] Por motivos de segurança, verifique se nenhuma credencial é especificada pela propriedade storageConnectionString . Se a consulta precisar especificar credenciais, use parâmetros de consulta para especificar toda a cadeia de conexão.

Por exemplo, supondo que a consulta inclua um parâmetro de consulta chamado URI cujos pontos de valor no Armazenamento de Blobs, a consulta teria esta aparência:

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

Se isso não for possível (por exemplo, você está usando um cliente que não dá suporte à definição de parâmetros de consulta), certifique-se de usar literais de cadeia de caracteres ofuscados.

Propriedades com suporte

Property Tipo Description
format string O formato de dados. Se não for especificado, será feita uma tentativa de detectar o formato de dados da extensão do arquivo. O padrão é CSV. Todos os formatos de dados de assimilação são suportados.
ignoreFirstRecord bool Se definido como true, o primeiro registro em cada arquivo será ignorado. Essa propriedade é útil na consulta a arquivos CSV com cabeçalhos.
ingestionMapping string Indica como mapear dados do arquivo de origem para as colunas reais no conjunto de resultados do operador. Confira os mapeamentos de dados.

Note

Esse operador não aceita nenhuma entrada de pipeline.

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

Returns

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

Examples

O exemplo a seguir mostra como encontrar todos os registros em uma tabela cuja UserID coluna se enquadra em um conjunto conhecido de IDs, mantidas (uma por linha) em um arquivo de armazenamento externo armazenado no Armazenamento de Blobs do Azure. Como o formato de dados não é especificado, o formato de dados detectado é TXT.

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

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

Note

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

Para consultar o formato de dados hierárquicos, como JSON, Parquet, Avro, ou 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 externaldata operador, um mapeamento de dados deve ser especificado. O mapeamento determina 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 é usado aqui porque os registros JSON únicos são estendidos em várias linhas.

Conteúdo relacionado

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

  • Last updated on