在 Durable Task Scheduler(預覽版)中使用任務佇列

任務佇列會將協調工作和活動工作分組在工作中樞內,而您可以控制排程器將這些工作交付給背景工作角色的速率。 使用任務佇列來調節工作負載,例如呼叫具有速率限制的下游服務的批次處理工作流程,而不必建立個別的工作中樞。

要使用任務佇列,首先在你的 Task Hub 下方建立佇列資源。 然後在排程編排或活動時設定 DTS_TaskQueue 標記。 標籤會選取現有的佇列,而不會建立佇列。

Note

任務佇列需要管理 API 版本 2026-07-01-preview 或更新版本。 本文中的範例使用 2026-07-01-preview。 關於資源結構,請參閱任務佇列 ARM 與 Bicep 參考。

任務佇列的運作方式

工作佇列屬於一個工作中樞。 其選用的 properties.throughput.actionsPerSecond 設定可控制工作項目交付的持續速率,也就是排程器將工作項目交付給背景工作角色的速度。

  • 同一佇列中的編排與活動工作項目會共享設定速率。
  • 每個交付給背景工作角色的協調流程回合都算作一次工作項目交付。 協調流程可能需要多個回合才能完成。
  • 每個交付給背景工作角色的活動工作項目都算作一次工作項目交付。 重送也算。
  • 活動和子編排會繼承父層的佇列選擇,除非你明確用它們自己的 DTS_TaskQueue 標籤覆寫它。
  • 實體工作項目不會使用任務佇列。

例如,actionsPerSecond: 20 會將持續速率設定為每秒交付 20 個工作項目,並由該佇列中的協調流程和活動工作共用此速率。 這不代表每秒完成 20 次編排、活動完成或下游 API 請求。 短時間突發可能超過持續速率,實際吞吐量可能因工作分配、工人容量或排程器容量而降低。

如果你在建立佇列時省略吞吐量,該佇列沒有佇列專屬的速率限制。 排程器和工作程序的容量限制仍然適用。 任務佇列不會保留運算資源、提供物理隔離,也不會在命名佇列間設定優先順序。 對於嚴格的下游請求限制,也應在你的活動呼叫下游服務時套用速率限制。

Prerequisites

  • 一個 Azure 訂用帳戶,其中包含現有的排程器和工作中樞。 關於排程器位置,請參見 支援區域。
  • 在工作中樞管理工作佇列資源的權限,例如從排程器或資源群組繼承的參與者角色。 僅靠資料平面角色並不能授予資源管理權限。
  • Azure CLI 範例可使用 az rest,或使用已完成驗證的 Azure Resource Manager REST 用戶端。 CLI 範例使用 Bash 語法,且不需要專用的任務佇列 CLI 擴充功能。
  • 一個設定為使用 Durable Task Scheduler、具備 以身分識別為基礎的存取 及支援標籤的 SDK 的應用程式。 請參閱 SDK 支援。
  • 未使用工作項目篩選條件進行連線的背景工作角色。 請參閱設定符合資格的背景工作角色。

設定符合資格的背景工作角色

只有沒有 工作項目過濾器 的工作者連線才能從定義的任務隊列接收工作。 使用任何篩選條件 (包括萬用字元篩選條件) 的背景工作角色連線都不符合資格。 確保未經篩選的背景工作角色會註冊您導向佇列的所有協調流程和活動。

.NET Durable Task SDK 會自動從其工作登錄檔產生篩選條件。 在設定工作者以進行任務佇列時,明確選擇退出篩選:

builder.Services.AddDurableTaskWorker()
    .AddTasks(registry =>
    {
        registry.AddAllGeneratedTasks();
    })
    .UseDurableTaskScheduler(connectionString)
    .UseWorkItemFilters(null);

在 Java、Python 和 Go SDK 中,不要為這些工作者啟用工作項目篩選。 如果你的應用程式已經設定了過濾器,請移除該設定。 關於 SDK 專屬的篩選選項,請參見 啟用工作項目過濾。

Important

在已定義的佇列中,工作項目會等待,直到符合條件的 worker 連線。 它不會改用經過篩選的背景工作角色。 相反地,如果指定的佇列不存在或已遭刪除,工作就會使用一般的工作中樞路由,而且不會強制執行所要求佇列的速率限制。 建立佇列,並等待佈建成功後,再排程已加上標籤的工作。

設定 Azure CLI

登入並選擇包含您的排程程式的訂用帳戶:

az login
az account set --subscription SUBSCRIPTION_ID

設定以下 Bash 變數。 將資源群組、排程器和任務中心名稱替換成你現有的資源。 這些範例會建立一個名為 orders的隊列。

subscriptionId=$(az account show --query id --output tsv)
resourceGroup="RESOURCE_GROUP"
schedulerName="SCHEDULER_NAME"
taskHubName="TASK_HUB_NAME"
queueName="orders"
apiVersion="2026-07-01-preview"

taskHubResourceId="/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DurableTask/schedulers/$schedulerName/taskHubs/$taskHubName"
queueResourceId="$taskHubResourceId/taskQueues/$queueName"
queueUrl="https://management.azure.com$queueResourceId?api-version=$apiVersion"

建立任務佇列

佇列名稱必須包含 3 到 64 個字母、數字或連字號,且與^[a-zA-Z0-9-]{3,64}$相符。 佇列是任務中心的子資源;它沒有自己的 location 或 Azure 資源 tags 屬性。

以下範例以每秒持續 20 筆工作項目分派的速率建立 orders 佇列。 設 actionsPerSecond 為正整數,或省略 throughput 以建立沒有佇列專屬速率限制的佇列。

使用az rest來呼叫 Azure Resource Manager API:

az rest --method put \
  --url "$queueUrl" \
  --body '{"properties":{"throughput":{"actionsPerSecond":20}}}'

等待配置

資源管理操作是非同步的。 建立或更新隊列後,取回並檢查 properties.provisioningState:

az rest --method get --url "$queueUrl" \
  --query properties.provisioningState --output tsv

重複查詢,直到狀態變成 Succeeded,再傳送已加上標籤的工作。 在狀態為 Failed、發生錯誤,或輪詢逾時到期時停止。 在使用佇列前先解決資源管理錯誤。 僅僅已接受的管理要求並不代表佇列已經準備好。 關於輪詢間隔與操作追蹤,請參見追蹤非同步 Azure 操作。

SDK 支援

佇列選擇使用編排和活動標籤,而非 Azure 資源標籤。 下表顯示你可以明確設定 DTS_TaskQueue。

SDK 或擴充功能 啟動協調流程 安排活動 排程子協調流程
Durable Task .NET SDK Yes Yes Yes
Durable Task JavaScript/TypeScript SDK Yes Yes Yes
Durable Task Python SDK Yes Yes No
Durable Task Java SDK (v1.6.0+) Yes No No
Durable Task Go SDK(測試版) Yes Yes Yes
Durable Functions:.NET 隔離式方案 Yes Yes Yes
Durable Functions: Java Yes No No

Durable Functions .NET in-process、JavaScript 和 Python 綁定都不會暴露這些明確的標籤選項。 不要假設語言的獨立 Durable Task SDK 支援也適用於其 Durable Functions 綁定。 在每種情況下,背景工作程序連線也必須符合 unfiltered-worker 要求。

將協調流程路由至佇列

將常值標籤索引鍵 DTS_TaskQueue 設為同一工作中樞中某個佇列的名稱。 以下程式碼片段假設你已經設定好客戶端並註冊了你的協調流程。 使用先前建立的 orders 隊列。

var options = new StartOrchestrationOptions
{
    Tags = new Dictionary<string, string>
    {
        { "DTS_TaskQueue", "orders" },
    },
};

string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
    "ProcessOrderOrchestration", input: order, options: options);

編排的活動與子編排繼承其佇列選擇。 您不需要在每次呼叫時重複設定標籤。 排程時設定佇列標籤;更新佇列速率不需要更改標籤。

覆寫活動或子協調流程的佇列

若要獨立控制工作流程的子集,請建立另一個隊列,例如 partner-api,並在活動或子編排呼叫中明確設定 DTS_TaskQueue 。 先等待該佇列佈建成功。

例如,你可以將編排協調保留在 orders 中,並透過 partner-api 將呼叫路由到下游服務。 活動覆寫會選取該活動所使用的佇列,而不會移動父系協調流程。

var activityOptions = new TaskOptions(tags: new Dictionary<string, string>
{
    { "DTS_TaskQueue", "partner-api" },
});

await context.CallActivityAsync(
    "CallPartnerApi", input: order, options: activityOptions);

var childOptions = new SubOrchestrationOptions
{
    Tags = new Dictionary<string, string>
    {
        { "DTS_TaskQueue", "partner-api" },
    },
};

await context.CallSubOrchestratorAsync(
    "ValidateOrderOrchestration", input: order, options: childOptions);

檢視與更新佇列

以下管理範例使用 Set up Azure CLI 中的 Bash 變數。

取得佇列的設定:

az rest --method get --url "$queueUrl"

列出任務中心的佇列:

az rest --method get \
  --url "https://management.azure.com$taskHubResourceId/taskQueues?api-version=$apiVersion"

將佇列速率更新為每秒 10 份:

az rest --method patch \
  --url "$queueUrl" \
  --body '{"properties":{"throughput":{"actionsPerSecond":10}}}'

若要移除隊列專屬速率限制同時保留隊列,明確設定 throughput 為 null:

az rest --method patch \
  --url "$queueUrl" \
  --body '{"properties":{"throughput":null}}'

在 PATCH 請求中省略吞吐量,現有速率保持不變。 PUT 請求會取代整個組態設定;省略 PUT 的吞吐量則移除佇列特定的速率限制。 更新後,請等待佈建成功,並確認傳回的設定。

刪除任務佇列

Warning

刪除佇列會移除其速率限制。 標記為已刪除佇列名稱的工作會改用一般的工作中樞路由。 不要用刪除佇列來暫停工作負載。

刪除佇列資源:

az rest --method delete --url "$queueUrl"

刪除是非同步的。 追蹤 Azure Resource Manager 非同步作業直到完成,或設定逾時時間來輪詢 GET,直到佇列傳回 404 Not Found。 不要將授權錯誤或其他要求失敗視為佇列已刪除的確認。 刪除佇列並不會終止使用該佇列的協調流程。

疑難排解佇列路由問題

如果佇列中的工作沒有進展,請確認該佇列是否存在且配置成功,標籤可識別同一任務中心中的目標佇列,且有健康的工作者無需過濾即可連線。 已定義但沒有符合資格的背景工作角色的佇列會保留其工作,而不會將工作交付給經過篩選的背景工作角色。

如果工作執行時未受到預期的速率限制,請檢查是否有缺失或已刪除的隊列。 此時排程器使用一般的任務樞紐路由。 也要考量短時間內的突增負載,以及工作項目交付次數與已完成工作流程數量之間的差異。 使用 排程器儀表板 檢查編排狀態和標籤。