operator externaldata

Operator externaldata 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 usłudze Azure Blob Storage lub plik w usłudze Azure Data Lake Storage.

Uwaga

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

Uwaga

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

Uwaga

externaldata Użyj operatora , 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

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

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko	Type	Wymagania	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ść	Type	Opis
format	string	Format danych. Jeśli nie zostanie określony, zostanie podjęta próba wykrycia formatu danych z rozszerzenia pliku. Wartość domyślna to CSV. Obsługiwane są wszystkie formaty danych pozyskiwania .
ignoreFirstRecord	bool	Jeśli ustawiono truewartość , 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órego 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 usłudze 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ń dotyczących wielu plików danych bez definiowania tabeli zewnętrznej.

Uwaga

Partycjonowanie danych nie jest rozpoznawane przez externaldata operatora.

Wykonywanie zapytań względem formatów danych hierarchicznych

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 usłudze 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.