次の方法で共有

エクスターナルデータ演算子

適用対象: ✅Microsoft Fabric✅Azure データ エクスプローラー✅Azure Monitor✅Microsoft Sentinel

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

Note

externaldata 演算子は次をサポートします。

  • ストレージ接続文字列の一覧に示されているように、ストレージ サービスの特定のセット。
  • Shared Access Signature (SAS) キー、アクセス キー、Microsoft Entra トークン、およびマネージド ID 認証方法。 詳細については、「ストレージの認証方法」を参照してください。

Note

externaldata 演算子は次をサポートします。

  • ストレージ接続文字列の一覧に示されているように、ストレージ サービスの特定のセット。
  • Shared Access Signature (SAS) キー、アクセス キー、および Microsoft Entra Token 認証方法。 詳細については、「ストレージの認証方法」を参照してください。

Note

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

Syntax

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

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

Parameters

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

[!WARN] セキュリティ上の理由から、 storageConnectionString プロパティで資格情報が指定されていないことを確認してください。 クエリで資格情報を指定する必要がある場合は、 クエリ パラメーター を使用して接続文字列全体を指定します。

たとえば、値が Blob Storage をポイントする URI というクエリ パラメーターがクエリに含まれている場合、クエリは次のようになります。

declare query_parameters(URI:string);
externaldata(x:string)[URI]

これが不可能な場合 (たとえば、クエリ パラメーターの設定をサポートしていないクライアントを使用している場合)、 難読化された文字列リテラルを使用してください。

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

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

Note

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

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

Returns

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

Examples

次の例は、 UserID 列が既知の ID セットに分類され、Azure Blob Storage に格納されている外部ストレージ ファイルに保持されている (1 行に 1 つずつ) テーブル内のすべてのレコードを検索する方法を示しています。 データ形式が指定されていないため、検出されたデータ形式は TXT です。

Users
| where UserID in ((externaldata (UserID:string) [
    @"https://storageaccount.blob.core.windows.net/storagecontainer/users.txt;managed_identity=..."
    ]))
| ...

次の例では、外部ストレージに格納されている複数のデータファイルに対してクエリを行います。

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 形式が使用されます。

関連コンテンツ

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

  • Last updated on