LightIngest を使用して Azure Data Explorer にデータを取り込む
LightIngest は、Azure Data Explorerへのアドホック データ インジェスト用のコマンド ライン ユーティリティです。 ユーティリティは、ローカル フォルダー、Azure BLOB ストレージ コンテナー、または Amazon S3 バケットからソース データをプルできます。
LightIngest は、取り込み時間に時間制約がないため、大量のデータを取り込む場合に最も便利です。 また、クエリの (取り込み時間ではなく) 作成時間に従って後でレコードのクエリを実行する場合にも役立ちます。
LightIngest コマンドを自動生成する方法の例については、「 履歴データの取り込み」を参照してください。
注意
インジェストでは、最大で 6 GB のファイル サイズがサポートされます。 100 MB から 1 GB の間のファイルを取り込むことをお勧めします。
前提条件
- LightIngest。 LightIngest を取得するには、次の 2 つの方法があります。
オペレーティング システム用の LightIngest バイナリをダウンロードします。 ダウンロード後にバイナリを解凍してください。
.NET ツールとして LightIngest をインストールします。 この方法では、コンピューターに .NET SDK バージョン 6.0 以降がインストールされている必要があります。 次に、次のコマンドを実行します。
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
LightIngest を実行する
LightIngest を実行するには:
コマンド プロンプトで、「
LightIngest」に続けて関連するコマンドライン引数を入力します。ヒント
サポートされているコマンド ライン引数を確認するには、「
LightIngest /help」と入力します。「
ingest-」に続けて、インジェストを管理する Azure Data Explorer クラスターへの接続文字列を入力します。 接続文字列を二重引用符で囲み、その後に Kusto 接続文字列の指定を入力します。次に例を示します。
LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true
パフォーマンスに関する推奨事項
インジェストの負荷を最適に管理し、一時的なエラーから回復するには、 のインジェスト エンドポイントを使用します
https://ingest-{yourClusterNameAndRegion}.kusto.windows.net。インジェストのパフォーマンスを最適にするには、圧縮されていないローカル ファイルのサイズを LightIngest が推定できるように、生データのサイズが必要です。 ただし、LightIngest では、先にダウンロードしない限り、圧縮された BLOB の生のサイズを正しく見積もることができないことがあります。 したがって、圧縮された BLOB を取り込むときは、BLOB メタデータの
rawSizeBytesプロパティを圧縮されていないデータ サイズ (バイト単位) に設定します。
コマンド ライン引数
| 引数 | 型 | 説明 | 必須 |
|---|---|---|---|
string |
Kusto 接続文字列インジェストを処理する Kusto エンドポイントを指定します。 この値は二重引用符で囲む必要があります。 | ✔️ | |
| -database、-db | string |
ターゲットの Azure Data Explorer データベース名。 | |
| -table | string |
ターゲットの Azure Data Explorer テーブル名。 | ✔️ |
| -sourcePath、-source | string |
ソース データの場所。ローカル ファイル パス、Azure BLOB コンテナーのルート URI、または Amazon S3 バケットの URI のいずれかです。 データが Azure BLOB に格納されている場合、URI にはストレージ アカウント キーまたは Shared Access Signature (SAS) が含まれている必要があります。 データが S3 バケット内にある場合は、URI に資格情報キーを含める必要があります。 この値は二重引用符で囲うことをお勧めします。 詳細については、「 ストレージ接続文字列」を参照してください。 -sourcePath:; を渡します。ユーザーアクセス許可 (ユーザー プロンプト承認) を使用して Azure ストレージ項目を一覧表示する権限を借用します。 | ✔️ |
| -managedIdentity、-mi | string |
接続に使用するマネージド ID (ユーザー割り当てまたはシステム割り当て) のクライアント ID。 システム割り当て ID には "system" を使用します。 | |
| -ingestWithManagedIdentity、-imgestmi | string |
接続に使用するマネージド ID (ユーザー割り当てまたはシステム割り当て) のクライアント ID。 システム割り当て ID には "system" を使用します。 | |
| -connectToStorageWithUserAuth, -storageUserAuth | string |
ユーザー資格情報を使用してデータ ソース ストレージ サービスに対して認証します。 この値のオプションは または PROMPTDEVICE_CODEです。 |
|
| -connectToStorageLoginUri、-storageLoginUri | string |
が設定されている場合-connectToStorageWithUserAuthは、必要に応じてMicrosoft Entra IDログイン URI を指定できます。 |
|
| -prefix | string |
取り込むソース データが Blob Storage に存在する場合、この URL プレフィックスが、コンテナー名を除くすべての BLOB で共有されます。 たとえば、データが MyContainer/Dir1/Dir2 にある場合は、プレフィックスを Dir1/Dir2 にする必要があります。 この値は二重引用符で囲うことをお勧めします。 |
|
| -pattern | string |
ソース ファイルまたは BLOB を選択するパターン。 ワイルドカードがサポートされます。 たとえば、「 "*.csv" 」のように入力します。 この値は二重引用符で囲うことをお勧めします。 |
|
| -zipPattern | string |
取り込む ZIP アーカイブ内のファイルを選択するときに使用する正規表現。 アーカイブ内の他のファイルはすべて無視されます。 たとえば、「 "*.csv" 」のように入力します。 この値は二重引用符で囲うことをお勧めします。 |
|
| -format、-f | string |
ソース データの形式。 サポートされている形式のいずれかである必要があります | |
| -ingestionMappingPath、-mappingPath | string |
インジェスト列マッピング用のローカル ファイルへのパス。 「データ マッピング」を参照してください。 | |
| -ingestionMappingRef、-mappingRef | string |
テーブルに以前に作成されたインジェスト列マッピングの名前。 「データ マッピング」を参照してください。 | |
| -creationTimePattern | string |
設定した場合、ファイルまたは BLOB のパスから CreationTime プロパティを抽出するために使用されます。 「 を使用してデータを取り込む方法」を参照 CreationTimeしてください。 |
|
| -ignoreFirstRow、-ignoreFirst | bool |
設定した場合、各ファイル/BLOB の最初のレコードは無視されます。 たとえば、ソース データにヘッダーがある場合です。 | |
| -tag | string |
取り込まれたデータと関連付けるためのタグ。 複数回の出現が許可されています | |
| -dontWait | bool |
に設定すると true、インジェストの完了を待機しません。 大量のファイル/BLOB を取り込む場合に便利です。 |
|
| -compression、-cr | double | 圧縮率のヒント。 圧縮されたファイルまたは BLOB を取り込むときに、Azure Data Explorer が生データのサイズを評価できるようにするのに便利です。 元のサイズを圧縮サイズで除算して計算されます。 | |
| -limit、-l | 整数 (integer) | が設定されている場合は、インジェストを最初の N 個のファイルに制限します。 | |
| -listOnly、-list | bool |
設定されている場合は、インジェスト用に選択されたアイテムのみが表示されます。 | |
| -ingestTimeout | 整数 (integer) | すべての取り込み操作が完了するまでのタイムアウト (分)。 既定値は 60 です。 |
|
| -forceSync | bool |
設定した場合、同期インジェストを強制的に実行します。 既定値は false です。 |
|
| -インタラクティブ | bool |
に設定すると false、引数の確認を求めるメッセージは表示されません。 無人フローと非対話型環境の場合。 既定値は true です。 |
|
| -dataBatchSize | 整数 (integer) | 各取り込み操作の合計サイズ制限 (MB、非圧縮) を設定します。 | |
| -filesInBatch | 整数 (integer) | 各取り込み操作のファイル/BLOB 数の制限を設定します。 | |
| -devTracing、-trace | string |
設定した場合、診断ログはローカル ディレクトリに書き込まれます (既定では、 RollingLogs 現在のディレクトリで、またはスイッチ値を設定して変更できます)。 |
Azure BLOB に固有の機能
Azure BLOB で使用する場合、LightIngest は特定の BLOB メタデータ プロパティを使用してインジェスト プロセスを拡張します。
| メタデータのプロパティ | 使用法 |
|---|---|
rawSizeBytes, kustoUncompressedSizeBytes |
設定すると、非圧縮データ サイズとして解釈されます |
kustoCreationTime, kustoCreationTimeUtc |
UTC タイムスタンプとして解釈されます。 設定すると、Kusto の作成時刻を上書きするために使用されます。 バックフィル シナリオに役立ちます |
使用例
次の例では、オペレーティング システム用の LightIngest バイナリがインストールされていることを前提としています。 LightIngest を .NET ツールとしてインストールした場合は、例で を に置き換えますLightIngestLightIngest。
CreationTime プロパティを使用して履歴データを取り込む
既存のシステムから Azure Data Explorerに履歴データを読み込むと、すべてのレコードが同じインジェスト日を受け取ります。 -creationTimePattern 引数を使用すると、データをインジェスト時間ではなく作成時間でパーティション分割できます。 -creationTimePattern 引数を指定すると、ファイルまたは BLOB のパスから CreationTime プロパティが抽出されます。 パターンに項目のパス全体を反映する必要はなく、使用するタイムスタンプを囲むセクションだけでかまいません。
引数の値には次の値を含める必要があります。
- 単一引用符で囲まれたタイムスタンプ形式の直前の定数テキスト (プレフィックス)
- タイムスタンプ形式 (標準 .NET DateTime 表記)
- タイムスタンプの直後の定数テキスト (サフィックス)。
重要
作成時刻をオーバーライドする必要があることを指定する場合は、ターゲット テーブルの有効なエクステント マージ ポリシーの Lookback プロパティが、ファイルまたは BLOB パスの値と整合していることを確認します。
使用例
次の形式の datetime を含む BLOB 名:
historicalvalues19840101.parquet(タイムスタンプは 4 桁の年、2 桁の月、2 桁の日の数字)、-creationTimePattern引数の値は次のファイル名の一部です: "' historicalvalues'yyyyMMdd ' parquet'"LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'historicalvalues'yyyyMMdd'.parquet'" -pattern:"*.parquet" -format:parquet -limit:2 -cr:10.0 -dontWait:true次の形式で階層フォルダー構造を参照する BLOB URI:
https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension、-creationTimePattern引数の値は次のフォルダー構造の一部です: "'folder/'yyyy/MM/dd'/blob'"LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'mycontainer/myfolder/'yyyy/MM/dd'/'" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true
ストレージ アカウント キーまたは SAS トークンを使用して BLOB を取り込む
- ストレージ アカウント
ACCOUNT、フォルダーDIR、コンテナーCONT、一致パターン*.csv.gzを指定して、10 個の BLOB を取り込みます - 取り込み先はデータベース
DBのテーブルTABLEであり、取り込み先にインジェスト マッピングMAPPINGが事前に作成されています - このツールは、取り込み操作が完了するまで待機します
- 以下を指定するための異なるオプションに注意してください: ターゲット データベース、ストレージ アカウント キーと SAS トークン
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
-database:DB
-table:TABLE
-source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}"
-prefix:"DIR"
-pattern:*.csv.gz
-format:csv
-mappingRef:MAPPING
-limit:10
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True;Initial Catalog=DB"
-table:TABLE
-source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
-prefix:"DIR"
-pattern:*.csv.gz
-format:csv
-mappingRef:MAPPING
-limit:10
ヘッダー行を含めずに、コンテナー内のすべての BLOB を取り込む
- ストレージ アカウント
ACCOUNT、フォルダーDIR1/DIR2、コンテナーCONT、一致パターン*.csv.gzを指定して、すべての BLOB を取り込みます - 取り込み先はデータベース
DBのテーブルTABLEであり、取り込み先にインジェスト マッピングMAPPINGが事前に作成されています - ソース BLOB にはヘッダー行が含まれるため、各 BLOB の最初のレコードを削除するようツールに指示します
- このツールは、インジェストのためにデータをポストし、取り込み操作が完了するまで待機しません
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
-database:DB
-table:TABLE
-source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
-prefix:"DIR1/DIR2"
-pattern:*.csv.gz
-format:csv
-mappingRef:MAPPING
-ignoreFirstRow:true
パスからすべての JSON ファイルを取り込む
- パス
PATHの下にある、パターン*.jsonに一致するすべてのファイルを取り込みます - 取り込み先はデータベース
DBのテーブルTABLEであり、インジェスト マッピングはローカル ファイルMAPPING_FILE_PATHで定義されています - このツールは、インジェストのためにデータをポストし、取り込み操作が完了するまで待機しません
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
-database:DB
-table:TABLE
-source:"PATH"
-pattern:*.json
-format:json
-mappingPath:"MAPPING_FILE_PATH"
ファイルを取り込んで、診断トレース ファイルを書き込む
- パス
PATHの下にある、パターン*.jsonに一致するすべてのファイルを取り込みます - 取り込み先はデータベース
DBのテーブルTABLEであり、インジェスト マッピングはローカル ファイルMAPPING_FILE_PATHで定義されています - このツールは、インジェストのためにデータをポストし、取り込み操作が完了するまで待機しません
- 診断トレース ファイルはフォルダーの下にローカルに書き込まれます
LOGS_PATH
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
-database:DB
-table:TABLE
-source:"PATH"
-pattern:*.json
-format:json
-mappingPath:"MAPPING_FILE_PATH"
-trace:"LOGS_PATH"
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示