operador externaldata
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 em Armazenamento de Blobs do Azure ou um arquivo em Azure Data Lake Storage.
Observação
O externaldata
operador dá suporte a um conjunto específico de serviços de armazenamento, conforme listado em Cadeias de conexão de armazenamento.
Observação
O externaldata
operador dá suporte a métodos de autenticação sas (assinatura de acesso compartilhado), chave de acesso e autenticação de token de Microsoft Entra. Para obter mais informações, consulte Métodos de autenticação de armazenamento.
Observação
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.
Esse operador não tem suporte quando o ponto de extremidade público do artefato de armazenamento está atrás de um firewall.
Syntax
externaldata
(
Columnname:
columnType [,
...] )
[
storageConnectionString [,
...] ]
[with
(
propertyName=
propertyValue [,
...])
]
Saiba mais sobre as convenções de sintaxe.
Parâmetros
Nome | Tipo | Obrigatório | Descrição |
---|---|---|---|
columnName, columnType | string |
✔️ | Uma lista de nomes de coluna e seus tipos. Essa lista define o esquema da tabela. |
storageConnectionString | string |
✔️ | Um 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. |
Propriedades com suporte
Propriedade | Tipo | Descrição |
---|---|---|
format | string |
O formato de dados. Se não for especificado, será feita uma tentativa de detectar o formato de dados da extensão de arquivo. O padrão é CSV . Todos os formatos de dados de ingestão têm suporte. |
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. |
Observação
Esse operador não aceita nenhuma entrada de pipeline.
Os limites de consulta padrão também se aplicam a consultas de dados externos.
Retornos
O externaldata
operador retorna uma tabela de dados do esquema especificado cujos dados foram analisados do artefato de armazenamento especificado, indicado pela cadeia de conexão de armazenamento.
Exemplos
Buscar uma lista de IDs de usuário armazenadas em Armazenamento de Blobs do Azure
O exemplo a seguir mostra como localizar 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. 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"
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 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.
Observação
O particionamento de dados não é reconhecido pelo externaldata
operador .
Consultar formatos de dados hierárquicos
Para consultar o formato de dados hierárquico, como JSON
, Parquet
, Avro
ou ORC
, ingestionMapping
deve ser especificado nas propriedades do operador.
Neste exemplo, há um arquivo JSON armazenado em 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.
Para obter mais informações sobre a sintaxe de mapeamento, confira mapeamentos de dados.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de