Operatore externaldata

L'operatore externaldata restituisce una tabella lo schema definito nella query stessa e i cui dati vengono letti da un artefatto di archiviazione esterno, ad esempio un BLOB in Archiviazione BLOB di Azure o un file in Azure Data Lake Storage.

Nota

L'operatore externaldata supporta un set specifico di servizi di archiviazione, come indicato in Stringhe di connessione di archiviazione.

Nota

L'operatore externaldata supporta i metodi di autenticazione token di firma di accesso condiviso, chiave di accesso e Microsoft Entra token. Per altre informazioni, vedere Metodi di autenticazione dell'archiviazione.

Nota

Usare l'operatore externaldata per recuperare tabelle di riferimento di piccole dimensioni fino a 100 MB da un artefatto di archiviazione esterno. L'operatore non è progettato per volumi di dati di grandi dimensioni. Per recuperare grandi volumi di dati esterni, è consigliabile inserire i dati esterni in Log Analytics come log personalizzati. Questo operatore non è supportato quando l'endpoint pubblico dell'artefatto di archiviazione è dietro un firewall.

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome	Tipo	Obbligatoria	Descrizione
columnName, columnType	string	✔️	Elenco dei nomi di colonna e dei relativi tipi. Questo elenco definisce lo schema della tabella.
storageConnectionString	string	✔️	Un stringa di connessione di archiviazione dell'artefatto di archiviazione da eseguire una query.
propertyName, propertyValue	string		Elenco di proprietà supportate facoltative che determinano come interpretare i dati recuperati dall'archiviazione.

Proprietà supportate

Proprietà	Type	Descrizione
format	string	Il formato dati. Se non specificato, viene eseguito un tentativo di rilevare il formato di dati dall'estensione file. Il valore predefinito è CSV. Sono supportati tutti i formati di dati di inserimento .
ignoreFirstRecord	bool	Se impostato su true, il primo record in ogni file viene ignorato. Questa proprietà è utile quando si eseguono query sui file CSV con intestazioni.
ingestionMapping	string	Indica come eseguire il mapping dei dati dal file di origine alle colonne effettive nel set di risultati dell'operatore. Vedere mapping dei dati.

Nota

Questo operatore non accetta alcun input della pipeline.

I limiti di query standard si applicano anche alle query di dati esterne.

Restituisce

L'operatore externaldata restituisce una tabella dati dello schema specificato i cui dati sono stati analizzati dall'artefatto di archiviazione specificato, indicato dalla stringa di connessione di archiviazione.

Esempio

Recuperare un elenco di ID utente archiviati in Archiviazione BLOB di Azure

Nell'esempio seguente viene illustrato come trovare tutti i record in una tabella la cui UserID colonna rientra in un set noto di ID, tenuto (una per riga) in un file di archiviazione esterno. Poiché il formato dati non è specificato, il formato dati rilevato è 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
    ]))
| ...

Eseguire query su più file di dati

L'esempio seguente esegue query su più file di dati archiviati nell'archiviazione esterna.

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

L'esempio precedente può essere considerato come un modo rapido per eseguire query su più file di dati senza definire una tabella esterna.

Nota

Il partizionamento dei dati non viene riconosciuto dall'operatore externaldata .

Eseguire query sui formati di dati gerarchici

Per eseguire query su formato di dati gerarchico, ad esempio JSON, Parquet, Avroo ORC, ingestionMapping deve essere specificato nelle proprietà dell'operatore. In questo esempio è presente un file JSON archiviato in Archiviazione BLOB di Azure con il contenuto seguente:

{
  "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"   
  }   
}
...

Per eseguire query su questo file usando l'operatore externaldata , è necessario specificare un mapping dei dati. Il mapping determina come eseguire il mapping dei campi JSON alle colonne del set di risultati dell'operatore:

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"}}]')

Il MultiJSON formato viene usato qui perché i singoli record JSON vengono caricati in più righe.

Per altre informazioni sulla sintassi di mapping, vedere Mapping dei dati.