ストレージからの取り込み

  • [アーティクル]

.ingest into コマンドでは、1 つまたは複数のクラウド ストレージ ファイルからデータを "プル" することで、データがテーブルに取り込まれます。 たとえば、このコマンドを使用すると、Azure Blob Storage から 1000 の CSV 形式の BLOB を取得し、それらを解析して、1 つのターゲット テーブルにまとめて取り込むことができます。 データは、既存のレコードに影響を与えることも、テーブルのスキーマを変更することもなく、テーブルに追加されます。

注意

このインジェスト方法は、探索とプロトタイプ作成を目的としています。 運用環境や大量のシナリオでは使用しないでください。

アクセス許可

このコマンドを実行するには、少なくとも Table Ingestor アクセス許可が必要です。

構文

.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValu e [, ...] )]

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

パラメーター

名前 型 必須 説明
async string 指定した場合、コマンドは直ちにを返し、バックグラウンドでインジェストを続行します。 コマンドの結果には、インジェスト完了の状態と結果を.show operation取得するためにコマンドで使用できる値が含まれますOperationId。
TableName string ✔️ データを取り込むテーブルの名前。 テーブル名は、コンテキスト内のデータベースに対して常に相対的です。 スキーマ マッピング オブジェクトが指定されていない場合は、コンテキスト内のデータベースのスキーマが使用されます。
SourceDataLocator string ✔️ ストレージ接続文字列の 1 つまたはコンマ区切りのリスト。 1 つの接続文字列が、ストレージ アカウントによってホストされる 1 つのファイルを参照する必要があります。 複数のファイルの取り込みを行うには、複数の接続文字列を指定するか、外部テーブルのクエリから取り込みます。

注意

SourceDataPointer には難読化された文字列リテラルを使用することをお勧めします。 サービスは、内部トレースとエラー メッセージの資格情報をスクラブします。

インジェストのプロパティ

重要

次の表に、Azure Data Explorer でサポートされるプロパティの一覧を示し、それらについて説明し、例を示します。

プロパティ 説明 例
ingestionMapping ソース ファイルのデータをテーブルの実際の列にマップする方法を示す文字列値。 関連するマッピングの種類を使用して format の値を定義します。 「データ マッピング」を参照してください。 with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")
(非推奨: avroMapping、csvMapping、jsonMapping)
ingestionMappingReference 名前付きマッピング ポリシー オブジェクトを使用して、ソース ファイルのデータをテーブルの実際の列にマップする方法を示す文字列値。 関連するマッピングの種類を使用して format の値を定義します。 「データ マッピング」を参照してください。 with (format="csv", ingestionMappingReference = "Mapping1")
(非推奨: avroMappingReference、csvMappingReference、jsonMappingReference)
creationTime 取り込まれたデータ エクステントの作成時刻に使用する datetime 値 (ISO8601 文字列の形式)。 指定しない場合は、現在の値 (now()) が使用されます。 既定値のオーバーライドは、古いデータを取り込んで、保持ポリシーが正しく適用されるようにするときに役立ちます。 指定する場合、ターゲット テーブルの有効なエクステント マージ ポリシーの Lookback プロパティが、指定した値と整合していることを確認します。 with (creationTime="2017-02-13")
extend_schema 指定した場合、テーブルのスキーマを拡張するようにコマンドに指示するブール値 (既定値は false)。 このオプションは、.append コマンドと .set-or-append コマンドにのみ適用されます。 許可されるスキーマ拡張のみ、テーブルの最後に列が追加されます。 元のテーブル スキーマが (a:string, b:int) の場合、有効なスキーマ拡張は (a:string, b:int, c:datetime, d:string) になりますが、(a:string, c:datetime) は有効にはなりません
folder ingest-from-query コマンドの場合、テーブルに割り当てるフォルダー。 テーブルが既に存在する場合は、このプロパティによりテーブルのフォルダーがオーバーライドされます。 with (folder="Tables/Temporary")
format データ形式 (サポートされるデータ形式に関する記事を参照してください)。 with (format="csv")
ingestIfNotExists 指定した場合、同じ値を持つ、ingest-by: タグでタグが付けられたデータが既にテーブルにある場合、インジェストが成功しないようにする文字列値。 これにより、べき等データ インジェストが確保されます。 詳細については、ingest-by: タグに関する記事を参照してください。 プロパティ with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') は、タグ ingest-by:Part0001 を備えたデータが既に存在する場合、現在のインジェストが完了されないことを示します。 まだ存在しない場合は、(今後インジェストで同じデータが再び取り込もうとされた場合に備えて、) この新しいインジェストにこのタグが設定されている必要があります。
ignoreFirstRecord true に設定されている場合、インジェストで、すべてのファイルの最初のレコードを無視することを示すブール値。 このプロパティは、ファイルの最初のレコードが列名である場合に、CSV および同様の形式のファイルに対して有用です。 既定では、false が想定されます。 with (ignoreFirstRecord=false)
policy_ingestiontime ブール値。指定されている場合、このコマンドで作成されるテーブルで IngestionTime ポリシーを有効にするかどうかを記述します 既定では、 trueです。 with (policy_ingestiontime=false)
recreate_schema 指定した場合、コマンドでテーブルのスキーマを再作成するかどうかを示すブール値。 このプロパティは、.set-or-replace コマンドに対してのみ適用されます。 両方が設定されている場合、extend_schema プロパティよりもこのプロパティが優先されます。 with (recreate_schema=true)
tags JSON 文字列として書式設定された、取り込まれたデータに関連付けられるタグの一覧。 with (tags="['Tag1', 'Tag2']")
validationPolicy CSV 形式を使用して表されるデータの取り込み中に実行する検証を示す JSON 文字列。 さまざまなオプションの説明については、「データ インジェスト」を参照してください。 with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (これが実際の既定のポリシーです)
zipPattern ZIP アーカイブを持つストレージからデータを取り込むときに、このプロパティを使用します。 これは、取り込む ZIP アーカイブ内のファイルを選択するときに使用する正規表現を示す文字列値です。 アーカイブ内の他のファイルはすべて無視されます。 with (zipPattern="*.csv")

認証と承認

各ストレージ 接続文字列は、ストレージへのアクセスに使用する承認方法を示します。 承認方法によっては、インジェストを実行するために、外部ストレージに対するアクセス許可をプリンシパルに付与する必要がある場合があります。

次の表に、サポートされている認証方法と、外部ストレージからデータを取り込むのに必要なアクセス許可を示します。

認証方法 Azure Blob Storage/Data Lake Storage Gen2 Data Lake Storage Gen1
偽装 ストレージ BLOB データ閲覧者 Reader
Shared Access (SAS) トークン リスト + 読み取り この認証方法は Gen1 ではサポートされていません。
アクセス トークンのMicrosoft Entra
ストレージ アカウントのアクセス キー この認証方法は Gen1 ではサポートされていません。
管理対象 ID ストレージ BLOB データ閲覧者 Reader

戻り値

コマンドの結果は、コマンドによって生成されたデータ シャード ("エクステント") と同じ数のレコードを含むテーブルになります。 データ シャードが生成されていない場合、空の (ゼロ値の) エクステント ID を持つ 1 つのレコードが返されます。

名前 型 説明
ExtentId guid コマンドによって生成されたデータ シャードの一意識別子。
ItemLoaded string このレコードに関連する 1 つ以上のストレージ ファイル。
Duration timespan インジェストの実行に要する時間。
HasErrors bool このレコードがインジェストの失敗を表すかどうか。
OperationId guid 操作を表す一意の ID。 .show operation コマンドで使用できます。

Note

このコマンドでは、取り込まれるテーブルのスキーマは変更されません。 必要に応じて、データはインジェスト中にこのスキーマに "変換" されますが、その逆は行われません (余分な列は無視され、欠落している列は null 値として扱われます)。

例

共有アクセス署名を使用したAzure Blob Storage

次の例では、Azure Blob Storageから 2 つの BLOB を CSV ファイルとして読み取り、その内容をテーブル に取り込むようクラスターに指示しますT。 ... は、各 BLOB に読み取りアクセスを提供する、Azure Storage の Shared Access Signature (SAS) を表します。 また、SAS が記録されないように、難読化された文字列 (文字列値の前にある h) を必ず使用してください。

.ingest into table T (
    h'https://contoso.blob.core.windows.net/container/file1.csv?...',
    h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)

マネージド ID を使用したAzure Blob Storage

次の例では、Azure Blob Storageから CSV ファイルを読み取り、マネージド ID 認証を使用してその内容をテーブルTに取り込む方法を示します。 マネージド ID 認証方法の詳細については、「 マネージド ID 認証の概要」を参照してください。

.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')

Azure Data Lake Storage Gen 2

次の例は、Azure Data Lake Storage Gen 2 (ADLSv2) からデータを取り込む場合です。 ここで使用される資格情報 (...) はストレージ アカウントの資格情報 (共有キー) であり、接続文字列のシークレット部分にのみ文字列難読化を使用します。

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)

Azure Data Lake Storage

次の例では、Azure Data Lake Storage (ADLS) から 1 つのファイルを取り込みます。 ユーザーの資格情報を使用して ADLS にアクセスします (そのため、ストレージ URI をシークレットを含むものとして扱う必要はありません)。 また、インジェスト プロパティを指定する方法も示します。

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')

アクセス キーを持つ Amazon S3

次の例では、 アクセスキー ID とシークレットアクセスキーを使用して、Amazon S3 から 1 つのファイルを取り込みます。

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
  with (format='csv')

署名済み URL を持つ Amazon S3

次の例では、 署名済み URL を使用して Amazon S3 から 1 つのファイルを取り込みます。

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')