編排歷史匯出功能允許您的應用程式從 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 取得。 我們建議你在遵循本指南時,將此書作為參考。
匯出編曲歷史的運作方式
出口歷史利用內部的持久實體與協調機制,透過以下流程可靠管理出口工作。
- 你可以透過
ExportHistoryClient,設定時間窗和匯出模式來建立匯出工作。 - SDK 建立一個持久實體(
ExportJob),用來追蹤作業的狀態和進度。 - 內部編排會列出符合指定時間窗與狀態篩選器的終端協調實例。
- 對於每個匹配的實例,一個活動會從持久任務排程器取得完整的執行歷史。
- 歷史紀錄會序列化(預設為 JSONL 並以 gzip 壓縮),並寫入 Azure Blob 儲存體。
- 工作會查核其進度,因此若遭到中斷,可以繼續。
批次與連續作業的匯出模式
匯出歷史支援兩種模式:
| 模式 | 行為 |
|---|---|
| Batch | 匯出在固定時間窗completedTimeFrom 內達到終端狀態的實例(到 completedTimeTo),然後將該工作標記為完成。 |
| 連續的 | Tails 終端機實例會從 completedTimeFrom 開始持續運行,沒有設定結束時間。 這個工作會一直保持有效,直到你刪除它為止。 |
先決條件
- .NET 8 SDK 或更新版本
- 一個持久任務排程器(Durable Task Scheduler)任務中心(或本地模擬器)
- 一個 Azure 儲存體 帳號(或本地開發的 Azurite)
- 以下 NuGet 套件:
Microsoft.DurableTask.ExportHistoryMicrosoft.DurableTask.Client.AzureManagedMicrosoft.DurableTask.Worker.AzureManaged
啟用編排歷史匯出
安裝匯出歷史套件。
dotnet add package Microsoft.DurableTask.ExportHistory安裝 Azure Managed 客戶端和 Worker 套件以支援 Durable Task Scheduler。
dotnet add package Microsoft.DurableTask.Client.AzureManaged dotnet add package Microsoft.DurableTask.Worker.AzureManaged同時登記員工和客戶的匯出紀錄。
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 儲存體:
- 在應用程式的工作中樞上授與
Durable Task Data Contributor。 - 在儲存已匯出歷史區塊的儲存體帳戶上授與
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 客戶端請求。 打開它並點選 「發送請求 」,快速測試建立、取得、列出和刪除操作。