快速入門:使用 Durable Task SDK 的工作項目篩選功能

在這個快速入門中,你將學習如何執行一個 Durable Task SDK 範例,該範例利用工作項目篩選來將編排和活動路由給專屬工作者。

目前工作項目篩選功能已在 .NET、Java 和 Python Durable Task SDK 中提供。 請使用頁面頂端的分頁選擇您的語言。 想了解工作項目過濾的運作方式及其如何實現跨異質計算的扁平網路,請參閱 Durable Task Scheduler 中的工作項目過濾。

Note

JavaScript 和 PowerShell Durable Task SDK 尚未支援工作項目篩選功能。 今天就要嘗試此功能,請選擇頁面頂端的 C#、Java 或 Python 標籤。

  • 設定並執行耐用任務排程器模擬器以進行本機開發。
  • 執行 Orchestrator、Validator、Shipper 背景工作角色和用戶端。
  • 確認工作項目只分配給匹配的工人。
  • 使用 Azure Developer CLI 將範例部署到 Azure 容器應用程式。

先決條件

在開始之前:

準備專案

從 Azure-Samples/Durable-Task-Scheduler 根目錄,導覽至範例目錄:

cd samples/scenarios/WorkItemFilteringSplitActivities

用模擬器在本地執行

  1. 拉出模擬器映像檔:

    docker pull mcr.microsoft.com/durable-task/emulator:latest
    
  2. 執行模擬器:

    docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/durable-task/emulator:latest
    
  3. 建置範例:

    dotnet build
    
  4. 請在不同的終端機中執行每個背景工作角色:

    航廈1 - 協調員

    dotnet run --project src/OrchestratorWorker
    

    終端機2 - 驗證器工作員

    dotnet run --project src/ValidatorWorker
    

    第三航廈 - 貨運工人

    dotnet run --project src/ShipperWorker
    
  5. 在第四個終端機中,執行以下用戶端:

    dotnet run --project src/Client
    
  6. 在 http://localhost:8082 開啟模擬器儀表板,以監視協調流程活動。

Tip

作為手動開啟四個終端機的替代方案,你可以執行附帶的便利腳本:

./run-local.sh

它啟動模擬器,建置解決方案,並啟動所有工作者和客戶端。

工作項目篩選的預期輸出

客戶會每 30 秒排定一批三段編曲,並持續循環約 10 分鐘。 在航廈對面,你會看到:

  • 用戶端會排定編排批次,並等待各批次完成。 完成的批次記錄 3 completed, 0 failed。
  • Orchestrator 工作者負責派遣 ValidateOrder 和 ShipOrder 活動呼叫。
  • Validator 工作器只處理 ValidateOrder 活動工作項目。
  • Shipper 背景工作角色僅處理 ShipOrder 活動性工作項目。

此行為證實工作項目過濾僅將項目路由至註冊符合任務類型的工作者。

當你看到至少一個批次報告 3 completed, 0 failed 時,該範例即表示運作符合預期。 你不必等整個迴圈結束——在每個終端機按 Ctrl+C 就能停止客戶和工作者。 如果你讓客戶端跑到最後,它會印出最終結果摘要,然後一直保持運作,直到你用 Ctrl+C 停止它。

試試看:嚴格的路由實驗

若要查看路由很嚴格 (不會遞補至其他背景工作):

  1. 停止貨運工人(在第三航廈按 Ctrl+C)。
  2. 再次執行用戶端以排程新的協調流程。
  3. 請注意:
    • Orchestrator 背景工作會挑選並啟動協調流程。
    • Validator 背景工作會完成每個訂單的 ValidateOrder。
    • ShipOrder 工作項目仍處於 待處理 狀態——驗證者與協調者工作者無法接收。
    • 協調流程會保持在「執行中」狀態,等待 ShipOrder 完成。
  4. 重新啟動 Shipper 背景工作角色後,擱置中的 ShipOrder 工作項目會立即傳遞,協調流程也會完成。

此實驗證明工作項目僅會路由到具有相符過濾器的工人。 沒有退路。

使用 Azure 開發人員 CLI 進行部署

  1. 使用 Azure 認證(如果你還沒驗證過):

    azd auth login
    
  2. 從 samples/scenarios/WorkItemFilteringSplitActivities 中執行:

    azd up
    
  3. 當終端機中提示時,請提供以下參數:

    參數 說明
    環境名稱 為用來儲存所有 Azure 資源而建立的資源群組所使用的前綴。
    Azure 位置 您資源的 Azure 地區位置。
    Azure 訂用帳戶 您資源的 Azure 訂閱。

該 azd up 指令配置 Azure 資源並部署此範例中的四個容器化服務:客戶端、協調器工作者、驗證工作者和裝運工作者。

確認成功部署

  1. 在 azd up 輸出中複製資源群組名稱。

  2. 在 Azure 入口網站中,開啟那個資源群組。

  3. 對於每個已部署的容器應用程式(client, orchestrator-worker, validator-worker, shipper-worker), 開啟 監控>日誌串流。

  4. 確認每個應用程式只記錄其預期的工作項目:

    • orchestrator-worker:編排工作。
    • validator-worker:ValidateOrder 活動。
    • shipper-worker:ShipOrder 活動。

Note

每個容器應用程式都設定了 KEDA 縮放規則 (azure-durabletask-scheduler),會根據擱置工作項目待處理項目,自動將背景工作從 0 縮放到 10 個複本。 當用戶端完成其迴圈且沒有剩餘工作項目時,背景工作會縮減回零。 欲了解更多資訊,請參閱Azure 容器應用程式 上的 Durable Task Scheduler 自動縮放。

了解 C 語言中的工作項目過濾程式碼#

協調流程會依序呼叫兩個活動。 排程器會將每個活動工作項目分配給註冊的工作者。

public override async Task<string> RunAsync(TaskOrchestrationContext context, string orderId)
{
    string validationResult = await context.CallActivityAsync<string>("ValidateOrder", orderId);
    string shippingResult = await context.CallActivityAsync<string>("ShipOrder", orderId);

    return $"Order '{orderId}' => Validation: [{validationResult}], Shipping: [{shippingResult}]";
}

每個工作者只註冊其本地任務。 SDK 會自動從任務登錄產生工作項目篩選,所以你不需要明確選擇加入。

builder.Services.AddDurableTaskWorker()
    .AddTasks(registry =>
    {
        // Only this worker's tasks are registered.
        // Work item filters are auto-generated from the registry, so this
        // worker only receives matching work items.
        registry.AddAllGeneratedTasks();
    })
    .UseDurableTaskScheduler(connectionString);

Note

在 .NET Durable Task SDK 中,工作項目過濾器會自動從每位工作者登錄的資料中產生。 若要覆寫產生的篩選器,或選擇停用篩選,請分別呼叫 UseWorkItemFilters(customFilters) 或 UseWorkItemFilters(null)。

例如:

  • OrchestratorWorker 登記器 OrderProcessingOrchestration。
  • ValidatorWorker 登記器 ValidateOrder。
  • ShipperWorker 登記器 ShipOrder。

當工作者連接到 Durable Task Scheduler,SDK 會傳送其篩選清單。 排程器為每個篩選器建立佇列,並將每個工作項目路由到相匹配的佇列。 員工從來不會收到他們沒註冊的工作項目類型。

清理資源

  1. 停止本地模擬器容器。

    docker rm -f dts-emulator
    
  2. 如果你部署到 Azure,請標示資源群組名稱:

    • 從azd up輸出端複製。
    • 或者在 Azure 入口網站,使用頂端的全域搜尋框,搜尋 rg- 或你的環境名稱的前綴。
  3. 從搜尋結果中開啟資源群組。

  4. 選擇 刪除資源群組,輸入資源群組名稱確認,然後選擇 刪除。

下一步

  • 設定並執行耐用任務排程器模擬器以進行本機開發。
  • 執行 Orchestrator、Validator、Shipper 背景工作角色和用戶端。
  • 確認工作項目只分配給匹配的工人。
  • 使用 Azure Developer CLI 將範例部署到 Azure 容器應用程式。

先決條件

在開始之前:

準備專案

從 Azure-Samples/Durable-Task-Scheduler 根目錄,前往範例目錄:

cd samples/scenarios/WorkItemFilteringSplitActivitiesJava

用模擬器在本地執行

  1. 拉出模擬器映像檔。

    docker pull mcr.microsoft.com/dts/dts-emulator:latest
    
  2. 執行模擬器。

    docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest
    
  3. 建置範例。

    ./gradlew build
    
  4. 請在不同的終端機中執行每個背景工作角色:

    航廈1 - 協調員

    ./gradlew :orchestrator-worker:run
    

    終端機2 - 驗證器工作員

    ./gradlew :validator-worker:run
    

    第三航廈 - 貨運工人

    ./gradlew :shipper-worker:run
    
  5. 在第四個終端機裡,執行客戶端。

    ./gradlew :client:run
    
  6. 在 http://localhost:8082 開啟模擬器儀表板,以監視協調流程活動。

工作項目篩選的預期輸出

客戶會每 30 秒排定一批三段編曲,並持續循環約 10 分鐘。 在航廈對面,你會看到:

  • 用戶端會排定編排批次,並等待各批次完成。 完成的批次記錄 3 completed, 0 failed。
  • Orchestrator 工作者負責派遣 ValidateOrder 和 ShipOrder 活動呼叫。
  • Validator 工作器只處理 ValidateOrder 活動工作項目。
  • Shipper 背景工作角色僅處理 ShipOrder 活動性工作項目。

此行為證實工作項目過濾僅將項目路由至註冊符合任務類型的工作者。

當你看到至少一個批次報告 3 completed, 0 failed 時,該範例即表示運作符合預期。 你不必等整個迴圈結束——在每個終端機按 Ctrl+C 就能停止客戶和工作者。 如果你讓客戶端跑到最後,它會印出最終結果摘要,然後一直保持運作,直到你用 Ctrl+C 停止它。

試試看:嚴格的路由實驗

若要查看路由很嚴格 (不會遞補至其他背景工作):

  1. 停止貨運工人(在第三航廈按 Ctrl+C)。
  2. 再次執行用戶端以排程新的協調流程。
  3. 請注意:
    • Orchestrator 背景工作會挑選並啟動協調流程。
    • Validator 背景工作會完成每個訂單的 ValidateOrder。
    • ShipOrder 工作項目仍處於 待處理 狀態——驗證者與協調者工作者無法接收。
    • 協調流程會保持在「執行中」狀態,等待 ShipOrder 完成。
  4. 重新啟動 Shipper 背景工作角色後,擱置中的 ShipOrder 工作項目會立即傳遞,協調流程也會完成。

此實驗證明工作項目僅會路由到具有相符過濾器的工人。 沒有退路。

使用 Azure 開發人員 CLI 進行部署

  1. 使用 Azure 認證(如果你還沒驗證過):

    azd auth login
    
  2. 從 samples/scenarios/WorkItemFilteringSplitActivitiesJava 中執行:

    azd up
    
  3. 當終端機中提示時,請提供以下參數:

    參數 說明
    環境名稱 為用來儲存所有 Azure 資源而建立的資源群組所使用的前綴。
    Azure 位置 您資源的 Azure 地區位置。
    Azure 訂用帳戶 您資源的 Azure 訂閱。

該 azd up 指令配置 Azure 資源並部署此範例中的四個容器化服務:客戶端、協調器工作者、驗證工作者和裝運工作者。

確認成功部署

  1. 在 azd up 輸出中複製資源群組名稱。

  2. 在 Azure 入口網站中,開啟那個資源群組。

  3. 對於每個已部署的容器應用程式(client, orchestrator-worker, validator-worker, shipper-worker), 開啟 監控>日誌串流。

  4. 確認每個應用程式只記錄其預期的工作項目:

    • orchestrator-worker:編排工作。
    • validator-worker:ValidateOrder 活動。
    • shipper-worker:ShipOrder 活動。

Note

每個容器應用程式都設定了 KEDA 縮放規則 (azure-durabletask-scheduler),會根據擱置工作項目待處理項目,自動將背景工作從 0 縮放到 10 個複本。 當用戶端完成其迴圈且沒有剩餘工作項目時,背景工作會縮減回零。 欲了解更多資訊,請參閱Azure 容器應用程式 上的 Durable Task Scheduler 自動縮放。

了解 Java 中的工作項目過濾程式碼

協調流程會依序呼叫兩個活動。 排程器會將每個活動工作項目分配給註冊的工作者。

String validationResult = ctx.callActivity("ValidateOrder", orderId, String.class).await();
String shippingResult = ctx.callActivity("ShipOrder", orderId, String.class).await();

String combined = String.format("Order '%s' => Validation: [%s], Shipping: [%s]",
        orderId, validationResult, shippingResult);
ctx.complete(combined);

每位工作者只註冊其本地任務,並致電 useWorkItemFilters() 選擇是否加入過濾。 SDK 接著會從任務登錄檔產生工作項目篩選。

DurableTaskGrpcWorker worker = DurableTaskSchedulerWorkerExtensions
        .createWorkerBuilder(connectionString)
        .addActivity(new TaskActivityFactory() {
            // ...
        })
        .useWorkItemFilters() // auto-generate from registered tasks
        .build();

Note

每位工作者都必須明確呼叫 useWorkItemFilters() 以啟用過濾功能。 不呼叫的背景工作角色會收到所有工作項目類型。

例如:

  • OrchestratorWorker 登記器 OrderProcessingOrchestration。
  • ValidatorWorker 登記器 ValidateOrder。
  • ShipperWorker 登記器 ShipOrder。

當工作者連接到 Durable Task Scheduler,SDK 會傳送其篩選清單。 排程器為每個篩選器建立佇列,並將每個工作項目路由到相匹配的佇列。 員工從來不會收到他們沒註冊的工作項目類型。

若要提供明確的篩選條件,而非自動從登錄檔產生,請將 a WorkItemFilter 傳遞給 useWorkItemFilters():

WorkItemFilter filter = WorkItemFilter.newBuilder()
        .addOrchestration("OrderProcessingOrchestration")
        .addActivity("ValidateOrder")
        .build();

builder.useWorkItemFilters(filter);

清理資源

  1. 停止本地模擬器容器。

    docker rm -f dts-emulator
    
  2. 如果你部署到 Azure,請標示資源群組名稱:

    • 從azd up輸出端複製。
    • 或者在 Azure 入口網站,使用頂端的全域搜尋框,搜尋 rg- 或你的環境名稱的前綴。
  3. 從搜尋結果中開啟資源群組。

  4. 選擇 刪除資源群組,輸入資源群組名稱確認,然後選擇 刪除。

下一步

  • 設定並執行耐用任務排程器模擬器以進行本機開發。
  • 執行 Worker A、Worker B 和用戶端。
  • 確認工作項目只分配給匹配的工人。

先決條件

在開始之前:

準備專案

從 Azure-Samples/Durable-Task-Scheduler 根目錄,前往範例目錄:

cd samples/durable-task-sdks/python/work-item-filtering

用模擬器在本地執行

  1. 拉出模擬器映像檔。

    docker pull mcr.microsoft.com/dts/dts-emulator:latest
    
  2. 執行模擬器。

    docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest
    

    範例使用預設的模擬器設定(端點 http://localhost:8080 和任務中心 default),所以你不需要設定任何環境變數。

  3. (可選)建立並啟用 Python 虛擬環境。

    python -m venv venv
    source venv/bin/activate  # On Windows, use: venv\Scripts\activate
    
  4. 安裝所需的套件。

    pip install -r requirements.txt
    
  5. 請在不同的終端機中執行每個背景工作角色:

    第一航廈 - 員工A(問候)

    python worker_a.py
    

    第二航廈 - 工人B(數學)

    python worker_b.py
    
  6. 在第三個終端機中執行客戶端。

    python client.py
    
  7. 在 http://localhost:8082 開啟模擬器儀表板,以監視協調流程活動。

工作項目篩選的預期輸出

用戶端會排定一個問候協調流程和一個數學協調流程,然後等待兩者完成。 在航廈對面,你會看到:

  • 工作者 A 僅處理問候協調流程及其 say_hello 活動。
  • 工作者 B 只處理數學編排及其 add_numbers 活動。
  • 客戶端會列印每個編曲的結果。

此行為證實工作項目過濾僅將項目路由至註冊符合任務類型的工作者。

了解 Python 中的工作項目過濾程式碼

每位工作者只註冊其本地任務,並致電 use_work_item_filters() 選擇是否加入過濾。 SDK 會從註冊的任務中產生工作項目過濾器。

worker.add_orchestrator(greeting_orchestrator)
worker.add_activity(say_hello)
worker.use_work_item_filters()  # Auto-generate from the registry

Note

每位工作者都必須明確呼叫 use_work_item_filters() 以啟用過濾功能。 不呼叫的背景工作角色會收到所有工作項目類型。

例如:

  • 工作者A註冊 greeting_orchestrator 且 say_hello。
  • 工作者B註冊 math_orchestrator 且 add_numbers。

當工作者連接到 Durable Task Scheduler,SDK 會傳送其篩選清單。 排程器為每個篩選器建立佇列,並將每個工作項目路由到相匹配的佇列。 員工從來不會收到他們沒註冊的工作項目類型。

若要提供明確的過濾器,而非自動從登錄檔產生,請傳遞:WorkItemFilters

from durabletask.worker import WorkItemFilters, OrchestrationWorkItemFilter, ActivityWorkItemFilter

worker.use_work_item_filters(WorkItemFilters(
    orchestrations=[
        OrchestrationWorkItemFilter(name="greeting_orchestrator"),
    ],
    activities=[
        ActivityWorkItemFilter(name="say_hello"),
    ],
))

清理資源

停止本地模擬器容器。

docker rm -f dts-emulator

下一步