externaldata 演算子

  • [アーティクル]

externaldata 演算子では、クエリ自体でスキーマが定義され、Azure Blob Storage の BLOB や Azure Data Lake Storage ファイルなどの外部ストレージ アーティファクトからデータが読み取られるテーブルを返します。

Note

演算子は externaldata 、ストレージ接続文字列に記載されているように、特定のストレージ サービスのセット をサポートします。

Note

オペレーターはexternaldata、Shared Access Signature (SAS) キー、アクセス キー、および Microsoft Entra トークン認証方法をサポートしています。 詳細については、「ストレージの認証方法」を参照してください。

Note

externaldata 演算子を使用すると、外部ストレージの成果物から最大 100 MB までの小さな参照テーブルを取得できます。 この演算子は、大規模なデータ ボリューム向けには設計されていません。 大量の外部データを取得するには、外部データをカスタム ログとして Log Analytics に取り込むことをお勧めします。 ストレージ成果物のパブリック エンドポイントがファイアウォールの背後にある場合、この演算子はサポートされません。

構文

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

構文規則について詳しく知る。

パラメーター

名前 型 必須 説明
columnName、 columnType string ✔️ 列名とその型の一覧。 このリストでは、テーブルのスキーマを定義します。
storageConnectionString string ✔️ クエリを実行するストレージ 成果物のストレージ 接続文字列。
propertyName、 propertyValue string ストレージから取得したデータを解釈する方法を決定する、オプションで サポートされるプロパティ の一覧。

サポートされているプロパティ

プロパティ Type 説明
format string データ形式。 指定されていない場合は、ファイル拡張子からデータ形式を検出しようとします。 既定では、 CSVです。 すべての インジェスト データ形式 がサポートされています。
ignoreFirstRecord bool に設定すると true、すべてのファイルの最初のレコードは無視されます。 このプロパティは、ヘッダーを使用して CSV ファイルにクエリを実行する場合に便利です。
ingestionMapping string ソース ファイルから演算子の結果セット内の実際の列にデータをマップする方法を示します。 「データ マッピング」を参照してください。

Note

この演算子は、パイプラインの入力を受け入れません。

標準のクエリ制限は、外部データ クエリにも適用されます。

戻り値

externaldata 演算子では、指定されたストレージ アーティファクトから解析されたデータを含む指定のスキーマのデータ テーブルを返します。これはストレージ接続文字列で示されます。

例

Azure Blob Storage に格納されているユーザー ID の一覧を取得します

次の例では、列が既知の一連の ID に分類され、外部ストレージファイルに1行ずつ保持される、テーブル 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

上の例は、外部テーブルを定義せずに、複数のデータ ファイルに対してクエリを実行する簡単な方法として考えることができます。

Note

データのパーティション分割は externaldata 演算子によって認識されません。

階層データ形式に対するクエリの実行

JSON、Parquet、Avro、または ORC、ingestionMapping などの階層データ形式のクエリを実行するには、演算子のプロパティでを指定する必要があります。 この例では、次の内容を含む Azure Blob Storage に格納されている 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"}}]')

ここでは、単一の JSON レコードが複数の行にまたがるため、 MultiJSON 形式が使用されます。

マッピング構文の詳細については、「データのマッピング」を参照してください。