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

  • [アーティクル]

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

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

Note

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

アクセス許可

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

構文

.ingest [async] into table TableName SourceDataLocator [with ( IngestionPropertyName = IngestionPropertyValue [, ...] )]

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

パラメーター

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

Note

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

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

重要

キュー内のインジェスト データは、インジェスト プロパティを使用してバッチ処理されます。 異なる ConstValue 値など、使用されるインジェスト マッピング プロパティが異なるほど、インジェストの断片化が増え、パフォーマンスが低下する可能性があります。

次の表に、サポートされているプロパティの一覧と説明を示し、例を示します。

プロパティ 説明 例
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']")
TreatGzAsUncompressed trueに設定されている場合は、拡張子が.gzのファイルが圧縮されていないことを示すブール値。 このフラグは、Amazon AWS S3 から取り込むときに必要になることがあります。 with (treatGzAsUncompressed=true)
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 値として扱われます)。

例

Shared Access Signature を使用した 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

次の例では、マネージド ID 認証を使用して、Azure Blob Storage から CSV ファイルを読み取り、その内容をテーブル 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

次の例では、 access キー 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

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

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