你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

Kusto.Ingest 引入状态报告

使用 “版本 ”下拉列表切换服务。 了解有关导航的详细信息。
适用于: ✅ Microsoft Fabric ✅ Azure 数据资源管理器

本文介绍如何使用 IKustoQueuedIngestClient 功能跟踪引入请求的状态。

说明类

这些说明类包含有关要引入的源数据的重要详细信息,应在引入作中使用。

  • SourceDescription
  • DataReaderDescription
  • StreamDescription
  • FileDescription
  • BlobDescription

这些类都派生自抽象类 SourceDescription,它们用于实例化每个数据源的唯一标识符。 然后,每个标识符将用于状态跟踪,并显示在与相关作相关的所有报表、跟踪和异常中。

类 SourceDescription

大型数据集将拆分为 1GB 区块,每个部分将单独引入。 然后,同一 SourceId 将应用于源自同一数据集的所有引入作。

public abstract class SourceDescription
{
    public Guid? SourceId { get; set; }
}

类 DataReaderDescription

public class DataReaderDescription : SourceDescription
{
    public  IDataReader DataReader { get; set; }
}

类 StreamDescription

public class StreamDescription : SourceDescription
{
    public Stream Stream { get; set; }
}

Class FileDescription

public class FileDescription : SourceDescription
{
    public string FilePath { get; set; }
}

BlobDescription 类

public class BlobDescription : SourceDescription
{
    public string BlobUri { get; set; }
    // Setting the Blob size here is important, as this saves the client the trouble of probing the blob for size
    public long? BlobSize { get; set; }
}

引入结果表示形式

接口 IKustoIngestionResult

此接口捕获单个排队引入作的结果,并且可以通过该作进行 SourceId检索。

public interface IKustoIngestionResult
{
    // Retrieves the detailed ingestion status of the ingestion source with the given sourceId.
    IngestionStatus GetIngestionStatusBySourceId(Guid sourceId);

    // Retrieves the detailed ingestion status of all data ingestion operations into Kusto associated with this IKustoIngestionResult instance.
    IEnumerable<IngestionStatus> GetIngestionStatusCollection();
}

类 IngestionStatus

IngestionStatus 包含单个引入作的完整状态。

public class IngestionStatus
{
    // The ingestion status returns from the service. Status remains 'Pending' during the ingestion process and
    // is updated by the service once the ingestion completes. When <see cref="IngestionReportMethod"/> is set to 'Queue' the ingestion status
    // will always be 'Queued' and the caller needs to query the report queues for ingestion status, as configured. To query statuses that were
    // reported to queue, see: <see href="https://learn.microsoft.com/azure/kusto/api/netfx/kusto-ingest-client-status#ingestion-status-in-azure-queue"/>.
    // When <see cref="IngestionReportMethod"/> is set to 'Table', call <see cref="IKustoIngestionResult.GetIngestionStatusBySourceId"/> or
    // <see cref="IKustoIngestionResult.GetIngestionStatusCollection"/> to retrieve the most recent ingestion status.
    public Status Status { get; set; }
    // A unique identifier representing the ingested source. Can be supplied during the ingestion execution.
    public Guid IngestionSourceId { get; set; }
    // The URI of the blob, potentially including the secret needed to access the blob.
    // This can be a filesystem URI (on-premises deployments only), or an Azure Blob Storage URI (including a SAS key or a semicolon followed by the account key)
    public string IngestionSourcePath { get; set; }
    // The name of the database holding the target table.
    public string Database { get; set; }
    // The name of the target table into which the data will be ingested.
    public string Table { get; set; }
    // The last updated time of the ingestion status.
    public DateTime UpdatedOn { get; set; }
    // The ingestion's operation Id.
    public Guid OperationId { get; set; }
    // The ingestion operation activity Id.
    public Guid ActivityId { get; set; }
    // In case of a failure - indicates the failure's error code.
    public IngestionErrorCode ErrorCode { get; set; }
    // In case of a failure - indicates the failure's status.
    public FailureStatus FailureStatus { get; set; }
    // In case of a failure - indicates the failure's details.
    public string Details { get; set; }
    // In case of a failure - indicates whether or not the failures originate from an Update Policy.
    public bool OriginatesFromUpdatePolicy { get; set; }
}

状态枚举

价值 Meaning 临时/永久
Pending 该值可能会根据引入作的结果在引入过程中发生更改 临时
成功 已成功引入数据 永久性
已失败 引入失败 永久性
已排队 数据已排队等待引入 永久性
已跳过 未提供任何数据,并且跳过了引入作 永久性
PartiallySucceeded 部分数据已成功引入,但有些数据失败 永久性

跟踪引入状态 (KustoQueuedIngestClient)

IKustoQueuedIngestClient 是一个“fire-and-forget”客户端。 客户端上的引入作通过向 Azure 队列发布消息结束。 发布后,完成客户端作业。 为了方便客户端用户,KustoQueuedIngestClient 提供了一种用于跟踪单个引入状态的机制。 此机制不适用于高吞吐量引入管道上的大规模使用。 当速率相对较低且跟踪要求严格时,此机制用于精确引入。

警告

应避免对大型数据流的每个引入请求启用正通知,因为这会使基础 xStore 资源出现极端负载,这可能会导致引入延迟增加,甚至完成响应能力。

以下属性(在 KustoQueuedIngestionProperties 上设置)控制引入成功或失败通知的级别和传输。

IngestionReportLevel 枚举

public enum IngestionReportLevel
{
    FailuresOnly = 0,
    None,
    FailuresAndSuccesses
}

IngestionReportMethod 枚举

public enum IngestionReportMethod
{
    Queue = 0,
    Table,
    QueueAndTable
}

若要跟踪引入的状态,请向执行引入作的 IKustoQueuedIngestClient 提供以下内容:

  1. 将属性设置为 IngestionReportLevel所需的报表级别。 FailuresOnly 要么是默认值,FailuresAndSuccesses要么为默认值。 设置为时 None,引入结束时不会报告任何内容。
  2. 指定IngestionReportMethod - Queue或 。 TableQueueAndTable

可以在 Kusto.Ingest 示例 页上找到使用示例。

Azure 表中的引入状态

IKustoIngestionResult从每个引入作返回的接口包含可用于查询引入状态的函数。 特别注意 Status 返回 IngestionStatus 对象的属性:

  • Pending 指示源已排队等待引入,但尚未更新。 再次使用该函数查询源的状态
  • Succeeded 指示源已成功引入
  • Failed 指示源无法引入

注释

Queued获取状态指示IngestionReportMethod其默认值为“Queue”。 这是永久状态并重新调用 GetIngestionStatusBySourceId 或 GetIngestionStatusCollection 函数,将始终产生相同的“已排队”状态。 若要在引入之前检查 Azure 表中引入的状态,请 IngestionReportMethod 验证 KustoQueuedIngestionProperties 的属性是否已设置为 Table。 如果还希望将引入状态报告给队列,请将状态设置为 QueueAndTable。

Azure 队列中的引入状态

这些 IKustoIngestionResult 方法仅与检查 Azure 表中的状态相关。 若要查询报告给 Azure 队列的状态,请使用以下 IKustoQueuedIngestClient 方法。

方法 目的
PeekTopIngestionFailures 异步方法,该方法返回有关由于请求的消息限制而尚未放弃的最早引入失败的信息
GetAndDiscardTopIngestionFailures 由于请求的消息限制,返回并放弃尚未放弃的最早引入失败的异步方法
GetAndDiscardTopIngestionSuccesses 由于请求的消息限制,返回并放弃尚未放弃的最早引入成功的异步方法。 仅当 IngestionReportLevel 此方法设置为 FailuresAndSuccesses

从 Azure 队列检索到的引入失败

引入失败由 IngestionFailure 包含有关失败的有用信息的对象表示。

资产 Meaning
数据库和表 预期的数据库和表名称
IngestionSourcePath 引入的 Blob 的路径。 如果引入文件,将包含原始文件名。 如果引入 DataReader,则为随机
FailureStatus Permanent (不会执行重试)、 Transient (将执行重试)或 Exhausted (多次重试也失败)
OperationId 和 RootActivityId 引入的作 ID 和 RootActivity ID(可用于进一步故障排除)
FailedOn 失败的 UTC 时间。 将大于调用引入方法的时间,因为数据是在运行引入之前聚合的
详细信息 有关失败的其他详细信息(如果有)
ErrorCode IngestionErrorCode 枚举,表示引入错误代码(如果发生故障)