Kusto.Ingest 错误和异常
适用于：✅Azure 数据资源管理器
在客户端上处理引入时发生的任何错误都通过 C# 异常来指示。
失败数
KustoDirectIngestClient 异常
尝试从多个源进行引入时，在引入过程中可能会发生错误。
如果某个源的引入失败，则会记录该失败，客户端会继续引入剩余的源。
完成用于引入的所有源后，会引发 IngestClientAggregateException，其中包含 IList<IngestClientException> IngestionErrors 成员。
IngestClientException 及其派生类包含 IngestionSource 字段和 Error 字段。 这两个字段共同创建了一个映射，从引入失败的源映射到尝试引入时发生的错误。 此信息可用于 IngestionErrors 列表，用以调查哪些源引入失败以及原因是什么。 IngestClientAggregateException 异常还包含布尔属性 GlobalError，用于指示是否所有源都发生了某个错误。
从文件或 blob 引入时的失败
如果尝试从 blob 或文件引入时发生引入失败，则即使 deleteSourceOnSuccess 标志设置为 true，也不会删除引入源。 将保留源供进一步分析。 在了解错误来源后，如果该错误不是源自引入源本身，则客户端的用户可以尝试重新引入它。
从 IDataReader 引入时的失败
从 DataReader 引入时，要引入的数据将保存到默认位置为 <Temp Path>\Ingestions_<current date and time> 的一个临时文件夹中。 成功引入后，始终会删除此默认文件夹。
在 IngestFromDataReader 和 IngestFromDataReaderAsync 方法中，retainCsvOnFailure 标志（其默认值为 false）决定了引入失败后是否应保留文件。 如果此标志设置为 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 方法中，retainCsvOnFailure 标志（其默认值为 false）决定了引入失败后是否应保留文件。 如果此标志设置为 false，则不会持久保存引入失败的数据，因此很难了解发生了什么问题。
常见失败
| 错误 | Reason | 缓解措施 |
|---|---|---|
| 数据库 <数据库> 名称不存在 | 数据库不存在 | 在 kustoIngestionProperties 中检查数据库名称/创建数据库 |
| 找不到类型为 "Table" 的实体“不存在的表名”。 | 该表不存在，也没有 CSV 映射。 | 添加 CSV 映射/创建所需的表 |
| 出于 <某种原因> 排除的 Blob Blob 路径：必须使用 jsonMapping 参数来导入 JSON 模式 | 进行 JSON 引入时未提供 JSON 映射。 | 提供 JSON 映射 |
| 下载 blob 失败：“远程服务器返回了错误: (404)未找到。” | Blob 不存在。 | 请验证该 blob 是否存在。 如果它存在，请重试并联系 Kusto 团队 |
| JSON 列映射无效：两个或多个映射元素指向同一列。 | JSON 映射有 2 个不同路径的列 | 纠正 JSON 映射 |
EngineError - [UtilsException] IngestionDownloader.Download：一个或多个文件无法下载 (搜索 ActivityID：<GUID1>、RootActivityId：<GUID2>) |
一个或多个文件下载失败。 | 重试 |
| ID 为“<”的流的 CSV 格式错误，无法通过 ValidationOptions 策略 | CSV 文件格式不正确（例如，每行的列数不相同）。 仅当验证策略设置为 ValidationOptions.ValidateCsvInputConstantColumns 时才会失败。 |
检查你的 CSV 文件。 此消息仅适用于 CSV/TSV 文件 |
IngestClientAggregateException，错误消息为“缺少有效共享访问签名的必需参数” |
使用的 SAS 是服务的，而不是存储帐户的 | 使用存储帐户的 SAS |
引入错误代码
为了便于以编程方式处理引入失败，我们对失败消息进行了扩充，在其中包含了数值错误代码 (IngestionErrorCode enumeration)。
有关引入错误代码的完整列表，请参阅引入错误代码。
详细的异常参考信息
CloudQueuesNotFoundException
当数据管理群集未返回任何队列时引发
基类：异常
| 字段名称 | 类型 | 含义 |
|---|---|---|
| 错误 | string |
尝试从 DM 检索队列时发生的错误 |
仅当使用 Kusto 排队引入客户端时才适用。 在引入过程中，会多次尝试检索链接到 DM 的 Azure 队列。 当这些尝试失败时，将在“错误”字段中引发包含失败原因的异常。 还可能会在“InnerException”字段中引发内部异常。
CloudBlobContainersNotFoundException
当数据管理群集未返回任何 blob 容器时引发
基类：异常
| 字段名称 | 类型 | 含义 |
|---|---|---|
| KustoEndpoint | string |
相关 DM 的终结点 |
仅当使用 Kusto 排队引入客户端时才适用。
当引入尚未存在于 Azure 容器中的源（例如文件、DataReader 或流）时，数据将上传到临时 blob 进行引入。
如果未找到要将数据上传到其中的容器，则会引发异常。
DuplicateIngestionPropertyException
在多次配置了某个引入属性时引发
基类：异常
| 字段名称 | 类型 | 含义 |
|---|---|---|
| PropertyName | string |
重复属性的名称 |
PostMessageToQueueFailedException
将消息发布到队列失败时引发
基类：异常
| 字段名称 | 类型 | 含义 |
|---|---|---|
| QueueUri | string |
队列的 URI |
| 错误 | string |
尝试发布到队列时生成的错误消息 |
仅当使用 Kusto 排队引入客户端时才适用。
排队引入客户端通过将消息上传到相关的 Azure 队列来引入数据。 如果出现发布失败，则会引发异常。 它将包含队列 URI，在“错误”字段中包含失败原因，并可能在“InnerException”字段中包含内部异常。
DataFormatNotSpecifiedException
当需要指定数据格式但未在 IngestionProperties 中指定时引发
基类：IngestClientException
从流引入时，必须在 IngestionProperties 中指定数据格式，以正确地引入数据。 当未指定 IngestionProperties.Format 时，将引发此异常。
InvalidUriIngestClientException
在将无效的 blob URI 作为引入源提交时引发
基类：IngestClientException
CompressFileIngestClientException
当引入客户端无法压缩为引入提供的文件时引发
基类：IngestClientException
文件在引入之前会进行压缩。 当尝试压缩文件失败时，将引发异常。
UploadFileToTempBlobIngestClientException
当引入客户端将为引入提供的源上传到临时 blob 失败时引发
基类：IngestClientException
SizeLimitExceededIngestClientException
当引入源太大时引发
基类：IngestClientException
| 字段名称 | 类型 | 含义 |
|---|---|---|
| 大小 | long |
引入源的大小 |
| MaxSize | long |
允许引入的最大大小 |
如果引入源超过最大大小 (4GB)，则会引发异常。 可以通过 IngestionProperties 类中的 IgnoreSizeLimit 标志重写大小验证。 但是，不建议引入大于 1 GB 的单个源。 有关详细信息，请参阅 Kusto 引入最佳做法。
UploadFileToTempBlobIngestClientException
当引入客户端将为引入提供的文件上传到临时 blob 失败时引发
基类：IngestClientException
DirectIngestClientException
在执行直接引入的过程中出现常规错误时引发
基类：IngestClientException
QueuedIngestClientException
在执行排队引入的过程中发生错误时引发
基类：IngestClientException
IngestClientAggregateException
引入期间出现一个或多个错误时引发
| 字段名称 | 类型 | 含义 |
|---|---|---|
| IngestionErrors | IList<IngestClientException> | 尝试引入时出现的错误，以及与之相关的源 |
| IsGlobalError | bool |
指示是否所有源都发生了此异常 |