Condividi tramite

Operatore externaldata

  • Articolo

Si applica a: ✅Microsoft Fabric✅Azure Esplora dati✅ Azure Monitor✅Microsoft Sentinel

L'operatore externaldata restituisce una tabella il cui 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 Archiviazione stringa di connessione.

Nota

L'operatore externaldata supporta i metodi di autenticazione token di accesso condiviso, chiave di accesso e firma di accesso condiviso. 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 si trova dietro un firewall.

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Digita Obbligatorio Descrizione
columnName, columnType string ✔️ Elenco di nomi di colonna e relativi tipi. Questo elenco definisce lo schema della tabella.
storageConnectionString string ✔️ Un stringa di connessione di archiviazione dell'artefatto di archiviazione su cui eseguire 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 Formato dati. Se non specificato, viene effettuato un tentativo di rilevare il formato di dati dall'estensione di 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.

Valori restituiti

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

Esempi

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, mantenuto (uno per riga) in un file di archiviazione esterno. Poiché il formato dei 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 una 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 sul formato di dati gerarchico, ad esempio JSON, Parquet, Avroo ORC, ingestionMapping è necessario specificare 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 estendono in più righe.

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