Kusto.Ingest のエラーと例外

  • [アーティクル]

クライアント側でのインジェスト処理中の任意のエラーは、 C# 例外によって示されます。

エラー

KustoDirectIngestClient の例外

複数のソースからの取り込みを試みているときに、インジェスト プロセス中にエラーが発生する場合があります。 ソースの 1 つで取り込みが失敗した場合、その取り込みはログに記録され、クライアントは残りのソースの取り込みを続行します。 取り込みのためにすべてのソースを調べた後、 IList<IngestClientException> IngestionErrors メンバーが含まれる IngestClientAggregateException がスローされます。

IngestClientException とその派生クラスには、 IngestionSource フィールドと Error フィールドが含まれています。 2 つのフィールドを組み合わせて使用すると、取り込みに失敗したソースから、取り込み試行中に発生したエラーへのマッピングが作成されます。 この情報を IngestionErrors リストで使用して、インジェストに失敗したソースとその理由を調査できます。 例外 IngestClientAggregateException には、すべてのソースでエラーが発生したかどうかを示すブール型プロパティ GlobalError も含まれています。

ファイルまたは BLOB からの取り込みエラー

BLOB またはファイルからの取り込み中にインジェスト エラーが発生した場合、 deleteSourceOnSuccess フラグが true に設定されている場合でも、インジェスト ソースは削除されません。 ソースは、さらに分析するために保持されます。 エラーの原因が解釈され、エラーが取り込みソース自体に起因するものでない場合は、クライアントのユーザーはエラーの再取り込みを試みる可能性があります。

IDataReader からの取り込みエラー

DataReader から取り込み中、取り込むデータは、既定の場所が <Temp Path>\Ingestions_<current date and time> である一時フォルダーに保存されます。 この既定のフォルダーは、取り込みが成功した後に常に削除されます。

IngestFromDataReader メソッドと IngestFromDataReaderAsync メソッドでは、既定値が false である retainCsvOnFailure フラグによって、取り込みに失敗した後にファイルを保持するかどうかを決定します。 このフラグが false に設定されている場合、取り込みに失敗したデータは保持されないため、何が悪かったのかを解釈することが難しくなります。

KustoQueuedIngestClient の例外

KustoQueuedIngestClient は、Azure キューにメッセージをアップロードしてデータを取り込みます。 キュー プロセスの実行前または実行中にエラーが発生した場合は、プロセスの最後に IngestClientAggregateException がスローされます。 スローされる例外には、各エラーの原因が含まれ、キューにポストされていない IngestClientException のコレクションが含まれます。 メッセージの投稿中に発生したエラーもスローされます。

ソースとしてファイルまたは BLOB を使用したキューへの投稿の失敗

KustoQueuedIngestClient の IngestFromFile/IngestFromBlob メソッドの使用中にエラーが発生した場合、 deleteSourceOnSuccess フラグが true に設定されている場合でも、ソースは削除されません。 その代わりに、さらに分析を行うためにソースが保持されます。

エラーの原因が解釈され、エラーが取り込みソース自体に起因するものでない場合は、クライアントのユーザーは、失敗したソースに関連する IngestFromFile/IngestFromBlob メソッドを使用してデータの再キューを試みる可能性があります。

ソースとして IDataReader を使用したキューへの投稿の失敗

DataReader ソースを使用している間、キューに投稿するデータは、既定の場所が <Temp Path>\Ingestions_<current date and time> である一時フォルダーに保存されます。 このフォルダーは、データがキューに正常にポストされた後、常に削除されます。 IngestFromDataReader メソッドと IngestFromDataReaderAsync メソッドでは、既定値が false である retainCsvOnFailure フラグによって、取り込みに失敗した後にファイルを保持するかどうかを決定します。 このフラグが false に設定されている場合、取り込みに失敗したデータは保持されないため、何が悪かったのかを解釈することが難しくなります。

一般的なエラー

エラー 理由 対応策
データベース <データベース名> 名前が存在しません データベースは存在しません kustoIngestionProperties/Create the database でデータベース名を確認します
種類 'Table' のエンティティ 'table name that doesn't exist' が見つかりませんでした。 テーブルが存在しないか、CSV マッピングがありません。 CSV マッピングの追加 / 必要なテーブルの作成
BLOB <BLOB パス> が除外された理由: JSON パターンは jsonMapping パラメーターを使用して取り込む必要があります JSON マッピングが指定されていない場合の JSON の取り込み。 JSON マッピングを提供する
BLOB のダウンロードに失敗しました: 'リモート サーバーからエラーが返されました: (404) 見つかりません。' BLOB が存在しません。 BLOB の存在を確認します。 存在する場合は、再試行して Kusto チームにお問い合わせください
JSON 列マッピングが有効ではありません : 2 つ以上のマッピング要素が同じ列を指しています。 JSON マッピングには、異なるパスを持つ 2 つの列があります JSON マッピングを修正する
EngineError - [UtilsException] IngestionDownloader.Download: 1 つ以上のファイルのダウンロードに失敗しました (KustoLogs で ActivityID:<GUID1>、RootActivityId:<GUID2> を検索してください) 1 つ以上のファイルをダウンロードに失敗しました。 再試行
解析に失敗しました: ID '<ストリーム名>' のストリームの CSV 形式が正しくありません。ValidationOptions ポリシーによって失敗します 不正な形式の CSV ファイル (すべての行に同じ数の列がないなど)。 検証ポリシーが ValidationOptions.ValidateCsvInputConstantColumns に設定されている場合にのみ失敗します。 CSV ファイルを確認します。 このメッセージは CSV/TSV ファイルにのみ適用されます
IngestClientAggregateException のエラーメッセージ「有効な Shared Access Signature の必須パラメータがありません」 使用されている SAS はサービスであり、ストレージ アカウントではありません ストレージ アカウントの SAS を使用する

インジェスト エラー コード

インジェスト エラーをプログラムで処理するために、エラー情報には数値エラー コード (IngestionErrorCode enumeration) が追加されています。

インジェスト エラー コードの完全な一覧については、「 インジェスト エラー コード」を参照してください。

詳細な例外リファレンス

CloudQueuesNotFoundException

データ管理クラスターからキューが返されない場合に発生します

基底クラス: 例外

フィールド名 Type 説明
エラー string DM からキューを取得しようとして発生したエラー

Kusto Queued Ingest Client を使用する場合にのみ関連します。 インジェスト プロセス中に、DM にリンクされている Azure Queues を取得するためにいつくかの試行が行われます。 これらの試行が失敗すると、失敗の理由を含む例外が 'Error' フィールドに発生します。 "InnerException" フィールドの内部例外も発生する可能性があります。

CloudBlobContainersNotFoundException

データ管理クラスターから BLOB コンテナーが返されない場合に発生します

基底クラス: 例外

フィールド名 Type 説明
KustoEndpoint string 関連する DM のエンドポイント

Kusto Queued Ingest Client を使用する場合にのみ関連します。
ファイル、DataReader、Stream などの Azure コンテナーにまだ含まれていないソースを取り込む場合、データは取り込みのために一時的な BLOB にアップロードされます。 この例外は、データをアップロードするコンテナーが見つからない場合に発生します。

DuplicateIngestionPropertyException

取り込みプロパティが複数回構成されている場合に発生します

基底クラス: 例外

フィールド名 Type 説明
PropertyName string 重複するプロパティの名前

PostMessageToQueueFailedException

キューへのメッセージ送信が失敗した場合に発生する

基底クラス: 例外

フィールド名 Type 説明
QueueUri string キューの URI
エラー string キューにポストしようとして生成されたエラー メッセージ

Kusto Queued Ingest Client を使用する場合にのみ関連します。
キューに入れられた取り込みクライアントは、関連する Azure キューにメッセージをアップロードしてデータを取り込みます。 ポスト エラーが発生した場合は、例外が発生します。 これには、キュー URI、'Error' フィールドのエラーが発生した理由、および場合によっては、 'InnerException' フィールドの内部例外が含まれます。

DataFormatNotSpecifiedException

データ形式が必須で、 IngestionProperties で指定されていない場合に発生する

基底クラス : IngestClientException

Stream から取り込む場合は、データを適切に取り込むには、 IngestionProperties でデータ形式を指定する必要があります。 この例外は、 IngestionProperties.Format が指定されていない場合に発生します。

InvalidUriIngestClientException

無効な BLOB URI が取り込みソースとして送信されると発生する

基底クラス : IngestClientException

CompressFileIngestClientException

取り込みクライアントが取り込み用に指定されたファイルを圧縮できない場合に発生する

基底クラス : IngestClientException

ファイルは、取り込みの前に圧縮されます。 この例外は、ファイル圧縮の試行が失敗した場合に発生します。

UploadFileToTempBlobIngestClientException

取り込みクライアントが、取り込み用に提供されたソースを一時的な BLOB にアップロードできない場合に発生する

基底クラス : IngestClientException

SizeLimitExceededIngestClientException

取り込みソースが大きすぎる場合に発生する

基底クラス : IngestClientException

フィールド名 Type 説明
サイズ long 取り込みソースのサイズ
MaxSize long 取り込みに許可される最大サイズ

取り込みソースが最大サイズの 4 GB を超えると、例外がスローされます。 サイズの検証は、IngestionProperties クラスの IgnoreSizeLimit フラグでオーバーライドできます。 ただし、1 GB を超える単一ソースを取り込むのはお勧めしません。 詳細については、「 Kusto Ingest のベスト プラクティス」を参照してください。

UploadFileToTempBlobIngestClientException

取り込みクライアントが、取り込み用に提供されたファイルを一時的な BLOB にアップロードできない場合に発生する

基底クラス : IngestClientException

DirectIngestClientException

直接取り込みの実行中に一般的なエラーが発生した場合に発生する

基底クラス : IngestClientException

QueuedIngestClientException

キューに入った取り込みの実行中にエラーが発生した場合に発生する

基底クラス : IngestClientException

IngestClientAggregateException

取り込み中に 1 つ以上のエラーが発生した場合に発生する

基底クラス : AggregateException

フィールド名 Type 説明
IngestionErrors IList<IngestClientException> 取り込み中に発生するエラーと、それらのエラーに関連するソース
IsGlobalError bool すべてのソースで例外が発生したかどうかを示す