使用 Durable Task Scheduler 匯出編排歷史(預覽)

編排歷史匯出功能允許您的應用程式從 Durable Task Scheduler 擷取終端機編排實例的執行紀錄(完成、失敗或終止狀態),並寫入 Azure Blob 儲存體。 使用此功能用於審計、合規、分析,以及排程器外的編排資料長期歸檔。

備註

編排歷史匯出目前為預覽階段。 本文範例使用了 Durable Task .NET SDK 及其Microsoft.DurableTask.ExportHistory套件。 獨立的 Java SDK 與 Go SDK beta 也透過各自的 API 支援歷史匯出。

對於 Java,請將 com.microsoft:durabletask-exporthistory:1.10.0-preview.1 與用戶端和 Azure Managed 套件一併加入。 請參閱 Java SDK 歷史匯出範例,了解工作者與客戶端註冊、批次工作及進度追蹤。 本地開發則需模擬器版本 0.4.22 或更新。 這項支援不適用於Durable Functions Java應用程式。

關於 Go 的,請參考 Go SDK 匯出歷史範例,該範例會建立匯出工作並下載匯出後的 JSON 和 JSONL 歷史。 使用一個獨立且僅支援 Go 的任務中心並匯出目的地。 本文中的 .NET 註冊和環境變數不適用於 Java 或 Go。

小提示

完整且可執行的參考範例可於 ExportHistoryWebApp 取得。 我們建議你在遵循本指南時,將此書作為參考。

匯出編曲歷史的運作方式

出口歷史利用內部的持久實體與協調機制,透過以下流程可靠管理出口工作。

  1. 你可以透過 ExportHistoryClient,設定時間窗和匯出模式來建立匯出工作。
  2. SDK 建立一個持久實體(ExportJob),用來追蹤作業的狀態和進度。
  3. 內部編排會列出符合指定時間窗與狀態篩選器的終端協調實例。
  4. 對於每個匹配的實例,一個活動會從持久任務排程器取得完整的執行歷史。
  5. 歷史紀錄會序列化(預設為 JSONL 並以 gzip 壓縮),並寫入 Azure Blob 儲存體。
  6. 工作會查核其進度,因此若遭到中斷,可以繼續。

批次與連續作業的匯出模式

匯出歷史支援兩種模式:

模式 行為
Batch 匯出在固定時間窗completedTimeFrom 內達到終端狀態的實例(到 completedTimeTo),然後將該工作標記為完成。
連續的 Tails 終端機實例會從 completedTimeFrom 開始持續運行,沒有設定結束時間。 這個工作會一直保持有效,直到你刪除它為止。

先決條件

啟用編排歷史匯出

  1. 安裝匯出歷史套件。

    dotnet add package Microsoft.DurableTask.ExportHistory
    
  2. 安裝 Azure Managed 客戶端和 Worker 套件以支援 Durable Task Scheduler。

    dotnet add package Microsoft.DurableTask.Client.AzureManaged
    dotnet add package Microsoft.DurableTask.Worker.AzureManaged
    
  3. 同時登記員工和客戶的匯出紀錄。

    using Microsoft.DurableTask.Client;
    using Microsoft.DurableTask.Client.AzureManaged;
    using Microsoft.DurableTask.ExportHistory;
    using Microsoft.DurableTask.Worker;
    using Microsoft.DurableTask.Worker.AzureManaged;
    
    string connectionString = builder.Configuration.GetValue<string>("DURABLE_TASK_CONNECTION_STRING")
        ?? throw new InvalidOperationException("Missing DURABLE_TASK_CONNECTION_STRING");
    
    string storageConnectionString = builder.Configuration.GetValue<string>("EXPORT_HISTORY_STORAGE_CONNECTION_STRING")
        ?? throw new InvalidOperationException("Missing EXPORT_HISTORY_STORAGE_CONNECTION_STRING");
    
    string containerName = builder.Configuration.GetValue<string>("EXPORT_HISTORY_CONTAINER_NAME")
        ?? throw new InvalidOperationException("Missing EXPORT_HISTORY_CONTAINER_NAME");
    
    // Register the worker with export history support.
    // This registers internal entities, orchestrations, and activities that manage export jobs.
    builder.Services.AddDurableTaskWorker(worker =>
    {
        worker.UseDurableTaskScheduler(connectionString);
        worker.UseExportHistory();
    });
    
    // Register the client with export history support.
    // This configures the Azure Blob Storage destination and registers the ExportHistoryClient.
    builder.Services.AddDurableTaskClient(client =>
    {
        client.UseDurableTaskScheduler(connectionString);
        client.UseExportHistory(options =>
        {
            options.ConnectionString = storageConnectionString;
            options.ContainerName = containerName;
    
            // Optional: set a virtual folder path prefix for blob names (for example, "exports/daily").
            // When set, blobs are written to "{prefix}/{hash}.{ext}" instead of "{hash}.{ext}".
            options.Prefix = builder.Configuration.GetValue<string>("EXPORT_HISTORY_PREFIX");
        });
    });
    

創造並管理出口工作

啟用匯出歷程資料後,請使用 ExportHistoryClient 來建立和管理工作。

建立批次匯出工作

以下範例中,批次匯出工作會匯出所有在固定時間窗內達到終端狀態的編排實例。

ExportHistoryClient exportClient = app.Services.GetRequiredService<ExportHistoryClient>();

ExportJobCreationOptions options = new(
    mode: ExportMode.Batch,
    completedTimeFrom: DateTimeOffset.UtcNow.AddHours(-24),
    completedTimeTo: DateTimeOffset.UtcNow,
    destination: new ExportDestination("my-export-container")
    {
        // Virtual folder path prefix applied to all blob names for this job
        Prefix = "exports/daily",
    });

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);
ExportJobDescription description = await jobClient.DescribeAsync();

建立持續性匯出作業

在以下範例中,連續匯出工作會從開始時間無限尾隨終端執行個體。

ExportJobCreationOptions options = new(
    mode: ExportMode.Continuous,
    completedTimeFrom: DateTimeOffset.UtcNow,
    completedTimeTo: null,
    destination: null);

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);

當 destination 為 空時,工作使用預設容器與前綴配置於 ExportHistoryStorageOptions。

取得出口工作詳情

請使用以下程式碼取得工作的完整描述,包括狀態、進度計數器及任何錯誤。

ExportJobDescription? job = await exportClient.GetJobAsync("my-job-id");

備註

GetJobAsync 如果指定的工作 ID 不存在,就會 ExportJobNotFoundException 拋出。 查詢可能已被刪除的作業時,請處理此例外。

此內容 ExportJobDescription 包含:

房產 說明
JobId 唯一的工作識別碼。
Status 目前狀態:Pending、、ActiveFailed、或Completed。
CreatedAt 工作的建立時間。
LastModifiedAt 職缺最後更新的時間。
ScannedInstances 目前掃描的實例總數。
ExportedInstances 目前已匯出的實例總數。
LastError 最後一個錯誤訊息(如果有的話)。

列出作業

用類似以下範例的程式碼匯出一份活躍工作清單。

ExportJobQuery query = new()
{
    Status = ExportJobStatus.Active,
    CreatedFrom = DateTimeOffset.UtcNow.AddDays(-7),
    PageSize = 50,
};

AsyncPageable<ExportJobDescription> jobs = exportClient.ListJobsAsync(query);

await foreach (ExportJobDescription job in jobs)
{
    Console.WriteLine($"{job.JobId}: {job.Status} ({job.ExportedInstances} exported)");
}

ExportJobQuery 支援以下的濾波器特性:

房產 說明
Status 依工作狀態篩選:Pending、Active、 FailedCompleted或 。
JobIdPrefix 篩選 ID 以指定前綴開頭的工作。
CreatedFrom 只傳回在此時間或之後建立的作業。
CreatedTo 只傳回在此時間或之前建立的作業。
PageSize 每頁最多結果數。
ContinuationToken 用來取得下一頁結果的代幣。

刪除工作

請使用以下程式碼刪除工作。

ExportHistoryJobClient jobClient = exportClient.GetJobClient("my-job-id");
await jobClient.DeleteAsync();

備註

DeleteAsync 如果這份工作不存在,那就丟掉 ExportJobNotFoundException 。 刪除作業不會從 Azure Blob 儲存體移除已匯出的 Blob。

出口工作創造選項

該 ExportJobCreationOptions 類別控制匯出工作行為,並包含以下參數。

參數 Required 說明 預設值
mode 是的 Batch對於固定時段或 Continuous 對於持續進行的匯出。 —
completedTimeFrom 是(批次) 時間視窗 (含) 的開始,基於執行個體達到終止狀態的時間 對於連續模式,若未提供,則預設為 UtcNow 。 —
completedTimeTo 是(批次) 時間窗口結束(含)。 在連續模式中,必須將其省略。 不能是未來的時間。 —
destination No 覆寫此工作的預設 Blob 容器和前綴。 使用預設值 ExportHistoryStorageOptions
jobId No 自訂工作識別碼。 自動產生的 GUID
format No 匯出格式:JSONL(gzip壓縮)或JSON(未壓縮)。 JSONL 搭配 gzip
runtimeStatus No 依終端機狀態篩選: Completed, Failed, Terminated. 所有終端狀態
maxInstancesPerBatch No 每批需處理的實例數(1–1000)。 100

匯出資料儲存在 Azure Blob 儲存體 中

匯出的歷史記錄會寫入 Azure Blob 儲存體,並設定以下參數。

  • 容器:預設來自 EXPORT_HISTORY_CONTAINER_NAME,或每個工作 destination 的覆寫。
  • Blob 名稱:源自一個 (completedTimestamp, instanceId) 的 SHA-256 雜湊值。
  • 檔案格式:
    • 預設值: .jsonl.gz (JSON 行,gzip 壓縮 — 每行一個歷史事件)
    • 可選性: .json (未壓縮的 JSON 歷史事件陣列)
  • 帶有前綴的 blob 路徑:當設定前綴(例如 exports/daily),blob 路徑變為 exports/daily/{hash}.{ext}。 若無前綴,blob 會直接寫入容器根節點為 {hash}.{ext}。

每個 blob 都包含 instanceId 一個可追溯的元資料標籤。

匯出歷史設定的環境變數

請將這些環境變數與 Durable Task .NET SDK 匯出歷史範例一起使用。

變數 說明 範例預設值
DURABLE_TASK_CONNECTION_STRING 持久化任務排程器連接字串 Endpoint=http://localhost:8080;TaskHub=default;Authentication=None
EXPORT_HISTORY_STORAGE_CONNECTION_STRING 已匯出歷史區塊的 Azure 儲存體連接字串 UseDevelopmentStorage=true
EXPORT_HISTORY_CONTAINER_NAME 用於匯出歷史的 Blob 容器 export-history
EXPORT_HISTORY_PREFIX Blob 名稱的選用虛擬資料夾路徑前綴 取消設定
ASPNETCORE_URLS 範例 HTTP 主機的接聽 URL 架構預設

匯出歷史的 Azure 使用權限

當你使用 Azure 資源而非本地模擬器時,應用程式身份需要存取 Durable Task Scheduler 和 Blob 儲存體:

  1. 在應用程式的工作中樞上授與 Durable Task Data Contributor。
  2. 在儲存已匯出歷史區塊的儲存體帳戶上授與Storage Blob Data Contributor。

出口作業的重要考量

  • 同時進行清除行動:
    如果你在匯出工作執行時清除編排實例,匯出過程可能會受到影響。 在匯出資料讀取前被清除的實例將不會出現在匯出資料中。 避免在同一時間窗口內,與活躍的匯出作業同時執行清除作業。

  • Blob清理:
    刪除匯出工作並不會移除 Azure Blob 儲存體 中已匯出的 blobs。 如果您需要移除已匯出的資料,請從儲存體帳戶中另外刪除 Bob。

確認匯出是否有效

建立出口工作後,請檢查兩個訊號是否正常:

  • 工作狀態會從 Pending 轉變為 Active,並最終轉換為 Completed(針對批次模式)。
  • blob 條目會出現在你設定好的匯出容器裡。

你可以用程式化方式查詢工作狀態:

ExportJobDescription? job;
do
{
    await Task.Delay(TimeSpan.FromSeconds(5));
    job = await exportClient.GetJobAsync(jobId);
    Console.WriteLine($"Status: {job?.Status}, Exported: {job?.ExportedInstances}");
}
while (job?.Status is ExportJobStatus.Pending or ExportJobStatus.Active);

本地開發時,請執行這個 Azure CLI 指令來檢查容器:

az storage blob list \
  --connection-string "UseDevelopmentStorage=true" \
  --container-name export-history \
  --output table

小提示

ExportHistoryWebApp 範例包含一個 ExportHistoryWebApp.http 檔案,內含現成的 VS Code REST 客戶端請求。 打開它並點選 「發送請求 」,快速測試建立、取得、列出和刪除操作。

下一步