LightIngest を使用して Azure Data Explorer にデータを取り込む

  • [アーティクル]

LightIngest は、Azure Data Explorer へのアドホック データ インジェストのためのコマンドライン ユーティリティです。 このユーティリティは、ローカル フォルダー、Azure Blob Storage コンテナー、または Amazon S3 バケットからソース データをプルできます。

LightIngest は、インジェスト期間に時間の制約がないため、大量のデータを取り込む必要がある場合に最も役立ちます。 また、クエリの (取り込み時間ではなく) 作成時間に従って後でレコードのクエリを実行する場合にも役立ちます。

LightIngest コマンドを自動生成する方法の例については、履歴データの取り込みに関する記事を参照してください。

Note

インジェストでは、最大で 6 GB のファイル サイズがサポートされます。 100 MB から 1 GB の間のファイルを取り込むことをお勧めします。

前提条件

LightIngest を実行する

LightIngest を実行するには、次の操作を実行します。

  1. コマンド プロンプトで、「LightIngest」に続けて関連するコマンドライン引数を入力します。

    ヒント

    サポートされているコマンド ライン引数を確認するには、「LightIngest /help」と入力します。

  2. 「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" を使用します。
-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 integer 設定した場合、インジェストを最初の N 個のファイルに限定します。
-listOnly、-list bool 設定した場合、インジェストに選択された項目のみが表示されます。
-ingestTimeout integer すべての取り込み操作が完了するまでのタイムアウト (分)。 既定値は 60 です。
-forceSync bool 設定した場合、同期インジェストを強制的に実行します。 既定値は false です。
-interactive 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 ツールとしてインストールした場合は、例の LightIngest を LightIngest に置き換えます。

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"

マネージド ID で認証を行う

LightIngest が実行するアクションには、認証にマネージド ID を使用できるものが 3 つあります。 各手順でマネージド ID を使用する場合、他の手順でマネージド ID を使用する必要はありません。 アクションごとに、関連するコマンドライン引数を指定します。

  • Kusto クラスターに接続する: インジェストをキューに登録するために、ツールにより接続文字列が使用されます。 "-mi" 引数を使用して、ターゲット データベースの取り込み特権を持つクライアント VM にインストールされているマネージド ID を指定します。

  • Azure Storage に接続して BLOB をダウンロードする: "-ingestmi" を使用して、ストレージ コンテナーに対する読み取り特権を持つ Kusto サービスにインストールされているマネージド ID を指定します。

  • Azure Storage に接続してコンテナー BLOB を一覧表示する: "-storageMi" 引数を使用して、ストレージ コンテナーに対する一覧表示特権を持つクライアント VM にインストールされているマネージド ID を指定します。 この方法を使用し、前の方法 (Azure ストレージに接続して BLOB をダウンロードする) を使用していない場合は、マネージド ID にも読み取り特権が必要であり、インジェストに使用するトークンが Kusto サービスに渡されます。 したがって、3 つの引数をすべて設定することをお勧めします。