operator externaldata

externaldata Operator zwraca tabelę, której schemat jest zdefiniowany w samym zapytaniu i którego dane są odczytywane z zewnętrznego artefaktu magazynu, takiego jak obiekt blob w Azure Blob Storage lub plik w Azure Data Lake Storage.

Uwaga

Operator externaldata obsługuje określony zestaw usług magazynu, jak wymieniono w obszarze Parametry połączenia magazynu.

Uwaga

Operator externaldata obsługuje klucz sygnatury dostępu współdzielonego (SAS), klucz dostępu i metody uwierzytelniania tokenu Microsoft Entra. Aby uzyskać więcej informacji, zobacz Metody uwierzytelniania magazynu.

Uwaga

Użyj operatora , externaldata aby pobrać małe tabele referencyjne do 100 MB z zewnętrznego artefaktu magazynu. Operator nie jest przeznaczony dla dużych woluminów danych. Aby pobrać duże ilości danych zewnętrznych, zalecamy pozyskiwanie danych zewnętrznych do usługi Log Analytics jako dzienników niestandardowych. Ten operator nie jest obsługiwany, gdy publiczny punkt końcowy artefaktu magazynu znajduje się za zaporą.

Składnia

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

Dowiedz się więcej o konwencjach składniowych.

Parametry

Nazwa	Typ	Wymagane	Opis
columnName, columnType	string	✔️	Lista nazw kolumn i ich typów. Ta lista definiuje schemat tabeli.
storageConnectionString	string	✔️	Parametry połączenia magazynu artefaktu magazynu do wykonywania zapytań.
propertyName, propertyValue	string		Lista opcjonalnych obsługiwanych właściwości określających sposób interpretowania danych pobranych z magazynu.

Obsługiwane właściwości

Właściwość	Typ	Opis
format	string	Format danych. W przypadku nieokreślonej próby wykrycia formatu danych z rozszerzenia pliku. Wartość domyślna to CSV. Obsługiwane są wszystkie formaty danych pozyskiwania .
ignoreFirstRecord	bool	Jeśli ustawiono wartość true, pierwszy rekord w każdym pliku jest ignorowany. Ta właściwość jest przydatna podczas wykonywania zapytań dotyczących plików CSV z nagłówkami.
ingestionMapping	string	Wskazuje sposób mapowania danych z pliku źródłowego na rzeczywiste kolumny w zestawie wyników operatora. Zobacz mapowania danych.

Uwaga

Ten operator nie akceptuje żadnych danych wejściowych potoku.

Standardowe limity zapytań dotyczą również zapytań dotyczących danych zewnętrznych.

Zwraca

Operator externaldata zwraca tabelę danych danego schematu, której dane zostały przeanalizowane z określonego artefaktu magazynu wskazanego przez parametry połączenia magazynu.

Przykłady

Pobieranie listy identyfikatorów użytkowników przechowywanych w Azure Blob Storage

W poniższym przykładzie pokazano, jak znaleźć wszystkie rekordy w tabeli, której UserID kolumna znajduje się w znanym zestawie identyfikatorów przechowywanych (jeden na wiersz) w pliku magazynu zewnętrznego. Ponieważ format danych nie jest określony, wykryty format danych to 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
    ]))
| ...

Wykonywanie zapytań dotyczących wielu plików danych

Poniższy przykład wykonuje zapytania dotyczące wielu plików danych przechowywanych w magazynie zewnętrznym.

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

Powyższy przykład można traktować jako szybki sposób wykonywania zapytań o wiele plików danych bez definiowania tabeli zewnętrznej.

Uwaga

Partycjonowanie danych nie jest rozpoznawane przez externaldata operatora.

Wykonywanie zapytań dotyczących hierarchicznych formatów danych

Aby wykonywać zapytania dotyczące formatu danych hierarchicznych, takich jak JSON, Parquet, Avrolub ORC, ingestionMapping należy określić we właściwościach operatora. W tym przykładzie plik JSON jest przechowywany w Azure Blob Storage z następującą zawartością:

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

Aby wysłać zapytanie do tego pliku przy użyciu externaldata operatora, należy określić mapowanie danych. Mapowanie określa sposób mapowania pól JSON na kolumny zestawu wyników operatora:

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

Format MultiJSON jest używany tutaj, ponieważ pojedyncze rekordy JSON są podzielone na wiele wierszy.

Aby uzyskać więcej informacji na temat składni mapowania, zobacz mapowania danych.