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> 的一个临时文件夹中。 成功引入后,始终会删除此默认文件夹。

IngestFromDataReaderIngestFromDataReaderAsync 方法中,retainCsvOnFailure 标志(其默认值为 false)决定了引入失败后是否应保留文件。 如果此标志设置为 false,则不会持久保存引入失败的数据,因此很难了解发生了什么问题。

KustoQueuedIngestClient 异常

KustoQueuedIngestClient 通过将消息上传到 Azure 队列来引入数据。 如果在排队过程之前或排队过程中发生错误,则在该过程结束时会引发 IngestClientAggregateException。 引发的异常包括一个 IngestClientException 集合,该集合包含每个失败的源且尚未发布到队列。 还会引发尝试发布消息时发生的错误。

以文件或 blob 作为源发布到队列时的失败

如果使用 KustoQueuedIngestClientIngestFromFile/IngestFromBlob 方法时发生错误,则即使 deleteSourceOnSuccess 标志设置为 true,也不会删除源。 相反,将保留源供进一步分析。

在了解错误来源后,如果该错误不是源自引入源本身,则客户端的用户可以通过对失败的源使用相关的 IngestFromFile/IngestFromBlob 方法来尝试将数据重新排队。

使用 IDataReader 作为源发布到队列时的失败

使用 DataReader 源时,发布到队列的数据将保存到默认位置为 <Temp Path>\Ingestions_<current date and time> 的一个临时文件夹中。 将数据成功发布到队列后,始终会删除此文件夹。 在 IngestFromDataReaderIngestFromDataReaderAsync 方法中,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

引入期间出现一个或多个错误时引发

基类:AggregateException

字段名称 类型 含义
IngestionErrors IList<IngestClientException> 尝试引入时出现的错误,以及与之相关的源
IsGlobalError bool 指示是否所有源都发生了此异常