externaldata 運算子

發行項
01/23/2024

externaldata 運算子會傳回資料表，其結構描述是在查詢本身定義，而其資料是從外部儲存體成品讀取，例如 Azure Blob 儲存體中的 Blob 或 Azure Data Lake Storage 中的檔案。

注意

操作員 externaldata 支援一組特定的記憶體服務，如記憶體連接字串下所列。

注意

操作員externaldata支援共用存取簽章 (SAS) 金鑰、存取金鑰和 Microsoft Entra 令牌驗證方法。如需詳細資訊，請參閱記憶體驗證方法。

注意

externaldata使用運算符，從外部記憶體成品擷取最多 100 MB 的小型參考數據表。運算子不是針對大型數據磁碟區所設計。若要擷取大量的外部數據，建議您將外部數據擷取至Log Analytics作為自定義記錄。當記憶體成品的公用端點位於防火牆後方時，不支援此運算符。

Syntax

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

深入瞭解語法慣例。

參數

名稱	類型	必要	Description
columnName、 columnType	`string`	✔️	數據行名稱和其類型的清單。此清單會定義資料表的架構。
storageConnectionString	`string`	✔️	要查詢之記憶體成品的記憶體連接字串。
propertyName， propertyValue	`string`		選擇性支援的屬性清單，決定如何解譯從記憶體擷取的數據。

支援的屬性

屬性	類型	Description
format	`string`	數據格式。如果未指定，則會嘗試從擴展名偵測數據格式。預設為 `CSV`。支援所有擷取數據格式。
ignoreFirstRecord	`bool`	如果設定為 `true`，則會忽略每個檔案中的第一筆記錄。使用標頭查詢 CSV 檔案時，這個屬性將發揮作用。
ingestionMapping	`string`	指出如何將來源檔案中的數據對應至運算子結果集中的實際數據行。請參閱資料對應。

注意

此運算子不接受任何管線輸入。

標準查詢限制也適用於外部資料查詢。

傳回

externaldata 運算子會傳回指定結構描述的資料表，其資料會從指定的儲存體成品剖析，以儲存體連接字串表示。

範例

擷取儲存在 Azure Blob 儲存體中的使用者識別碼清單

下列範例示範如何尋找 UserID 資料行屬於已知識別碼集的資料表的所有記錄，並保留在外部儲存體檔案中 (每行一個)。因為未指定資料格式，偵測到的資料格式為 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
    ]))
| ...

查詢多個資料檔案

下列範例會查詢儲存在外部儲存體中的多個資料檔案。

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

可以將上述範例視為在不定義外部資料表的情況下，查詢多個資料檔案的快速方法。

注意

externaldata 運算子無法辨識資料分割區。

查詢階層式資料格式

若要查詢階層式資料格式，例如 JSON、Parquet、Avro 或 ORC，必須在運算子屬性中指定 ingestionMapping。在此範例中，有一個儲存在 Azure Blob 儲存體中的 JSON 檔案，其中包含下列內容：

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

若要使用 externaldata 運算子來查詢此檔案，必須指定資料對應。對應會決定如何將 JSON 欄位對應到運算子結果集資料行：

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

在這裡使用 MultiJSON 格式，因為單一 JSON 記錄會橫跨多行。

如需對應語法的詳細資訊，請參閱資料對應。