LightIngest は、Azure Data Explorer へのアドホック データ インジェストのためのコマンドライン ユーティリティです。 このユーティリティは、ローカル フォルダー、Azure Blob Storage コンテナー、または Amazon S3 バケットからソース データをプルできます。
LightIngest は、インジェスト期間に時間の制約がないため、大量のデータを取り込む必要がある場合に最も役立ちます。 また、クエリの (取り込み時間ではなく) 作成時間に従って後でレコードのクエリを実行する場合にも役立ちます。
LightIngest コマンドを自動生成する方法の例については、履歴データの取り込みに関する記事を参照してください。
Note
インジェストでは、最大で 6 GB のファイル サイズがサポートされます。 100 MB から 1 GB の間のファイルを取り込むことをお勧めします。
前提条件
- LightIngest。 次の 2 つの方法のいずれかで LightIngest を取得します。
お使いのオペレーティング システム用の LightIngest バイナリをダウンロードします。 バイナリはダウンロード後に解凍してください。
LightIngest を .NET ツールとしてインストールします。 この方法では、お使いのコンピューターに .NET SDK バージョン 6.0 以降がインストールされている必要があります。 次に、次のコマンドを実行します。
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
Note
ソフトウェアをインストールする必要がないため、 キューに置かれたインジェスト コマンド の使用を検討してください。
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:;impersonate を渡して、ユーザー アクセス許可を持つ Azure ストレージ項目を一覧表示します (ユーザー プロンプトの承認)。 | ✔️ |
| -managedIdentity、-mi | string |
接続に使用するマネージド ID (ユーザー割り当てまたはシステム割り当て) のクライアント ID。 システム割り当て ID には "system" を使用します。 | |
| -azCli | bool |
設定されている場合は、Azure CLI を使用して Kusto サービスに対する認証を行います。 Azure CLI をインストールしてサインインする必要があります。 | |
| -ingestWithManagedIdentity、-ingestmi | string |
ストレージからダウンロードするために Kusto サービスにインストールされているマネージド ID (ユーザー割り当てまたはシステム割り当て) のクライアント ID。 システム割り当て ID には "system" を使用します。 | |
| -connectToStorageWithManagedIdentity,-storageMi | string |
ストレージから一覧表示するためにクライアント側にインストールされているマネージド ID (ユーザー割り当てまたはシステム割り当て) のクライアント ID。 | |
| -connectToStorageWithUserAuth,-storageUserAuth | string |
ユーザー資格情報を使用してデータ ソース ストレージ サービスに対して認証します。 この値のオプションは、PROMPT または DEVICE_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 | 倍精度浮動小数点 | 圧縮率のヒント。 圧縮されたファイルと blob を取り込む際に、Azure Data Explorer が生データのサイズを評価するのを助けるのに役立ちます。 元のサイズを圧縮後のサイズで割って算出します。 | |
| -limit、-l | 整数 | 設定した場合、インジェストを最初の N 個のファイルに限定します。 | |
| -listOnly、-list | bool |
設定すると、インジェスト用に選択される項目のみが表示されます。 | |
| -ingestTimeout | 整数 | すべての取り込み操作が完了するまでのタイムアウト (分)。 既定値は 60 です。 |
|
| -forceSync | bool |
設定した場合、同期インジェストを強制的に実行します。 既定値は false です。 |
|
| -interactive | bool |
false に設定した場合、引数の確認を求められません。 非アテンド型フローと非対話型環境向けです。 既定値は true です。 |
|
| -dataBatchSize | 整数 | 各取り込み操作の合計サイズ制限 (MB、非圧縮) を設定します。 | |
| -filesInBatch | 整数 | 各取り込み操作のファイル数と BLOB 数の制限を設定します。 | |
| -devTracing、-trace | string |
設定した場合、診断ログがローカル ディレクトリに書き込まれます (既定では現在のディレクトリ内の RollingLogs ですが、スイッチ値を設定して変更できます)。 |
Azure BLOB に固有の機能
Azure BLOB で LightIngest を使用すると、特定の BLOB メタデータ プロパティを使用してインジェスト プロセスが強化されます。
| メタデータ プロパティ | 使用方法 |
|---|---|
rawSizeBytes、kustoUncompressedSizeBytes |
設定されている場合、LightIngest はこれらのプロパティを非圧縮データ サイズとして解釈します |
kustoCreationTime、kustoCreationTimeUtc |
LightIngest は、これらのプロパティを UTC タイムスタンプとして解釈します。 設定すると、これらのプロパティを使用して Kusto の作成時刻がオーバーライドされます。 この機能は、バックフィル シナリオに役立ちます |
使用例
次の例では、オペレーティング システムに LightIngest バイナリがインストールされていることを前提としています。 .NET ツールとして LightIngest をインストールした場合は、 LightIngest 例の LightIngest に置き換えます。
CreationTime プロパティを使用して履歴データを取り込む
既存のシステムから Azure Data Explorer に履歴データを読み込むと、すべてのレコードが同じインジェスト日を取得します。 インジェスト時間ではなく作成時間でデータをパーティション分割するには、 -creationTimePattern 引数を使用します。
-creationTimePattern 引数を指定すると、ファイルまたは BLOB のパスから CreationTime プロパティが抽出されます。 パターンは、アイテムパス全体を反映する必要はありません。使用するタイムスタンプを囲むセクションだけを反映します。
引数の値には次の値を含める必要があります。
- 単一引用符で囲まれたタイムスタンプ形式の直前の定数テキスト (プレフィックス)
- タイムスタンプ形式 (標準 .NET DateTime 表記)
- タイムスタンプの直後の定数テキスト (サフィックス)。
使用例
次の形式の 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
BLOB を ストレージ アカウント キーまたは SAS トークンで取り込む
- ストレージ アカウント
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"
マネージド ID で認証を行う
LightIngest は、認証にマネージド ID を使用できる 3 つのアクションを実行します。 各手順でマネージド ID を使用する場合、他の手順でマネージド ID を使用する必要はありません。 アクションごとに、関連するコマンドライン引数を指定します。
Kusto クラスターに接続する: インジェストをキューに登録するために、ツールにより接続文字列が使用されます。 "-mi" 引数を使用して、ターゲット データベースの取り込み特権を持つクライアント VM にインストールされているマネージド ID を指定します。
Azure Storage に接続して BLOB をダウンロードする: "-ingestmi" を使用して、ストレージ コンテナーに対する読み取り特権を持つ Kusto サービスにインストールされているマネージド ID を指定します。
Azure Storage に接続してコンテナー BLOB を一覧表示する: "-storageMi" 引数を使用して、ストレージ コンテナーに対する一覧表示特権を持つクライアント VM にインストールされているマネージド ID を指定します。 この方法を使用するが、前の方法 (BLOB をダウンロードするために Azure Storage に接続する) を使用しない場合、マネージド ID にも読み取り特権が必要であり、インジェストに使用するトークンが Kusto サービスに渡されます。 3 つの引数をすべて設定します。