クイックスタート:Durable Task SDKで作業項目フィルタリングを活用してください

このクイックスタートでは、ワークアイテムフィルタリングを用いてオーケストレーションやアクティビティを専任のワーカーにルーティングするDurable Task SDKサンプルの実行方法を学びます。

作業項目フィルタリングは現在、.NET、Java、Python Durable Task SDKで利用可能です。 ページ上部のタブを使って言語を選択してください。 作業項目フィルタリングの仕組みや、異種計算間でのフラットネットワーキングの実現方法については、 Durable Task Schedulerの「Work item filtering」をご覧ください。

Note

JavaScriptおよびPowerShellのDurable Task SDKでワークアイテムフィルタリングはまだ利用できません。 この機能を今日試すには、ページ上部のC#、Java、またはPythonタブを選択してください。

  • ローカル開発用の Durable Task Scheduler エミュレーターを設定して実行します。
  • Orchestrator、Validator、Shipperのワーカーおよびクライアントを実行します。
  • 作業項目が一致するワーカーにのみルーティングされていることを確認します。
  • Azure Developer CLI を使用して Azure Container Apps にサンプルをデプロイします。

前提条件

開始する前に、次の手順を実行します。

プロジェクトを準備する

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
    

    ターミナル 3 - 荷送人

    dotnet run --project src/ShipperWorker
    
  5. 4 番目のターミナルで、クライアントを実行します。

    dotnet run --project src/Client
    
  6. http://localhost:8082でエミュレーター ダッシュボードを開き、オーケストレーション アクティビティを監視します。

Tip

4 つのターミナルを手動で開く代わりに、付属の便利なスクリプトを実行できます。

./run-local.sh

エミュレーターを起動し、ソリューションをビルドし、すべてのワーカーとクライアントを起動します。

作業項目のフィルター処理からの予想される出力

クライアントは30秒ごとに3つのオーケストレーションをスケジュールし、約10分間ループを続けます。 ターミナルの向こう側には、次のようなものがあります:

  • クライアントはオーケストレーションバッチをスケジュールし、各バッチの完了を待ちます。 完了したバッチは 3 completed, 0 failed とログに記録します。
  • オーケストレーターワーカーは ValidateOrder と活動呼び出し ShipOrder を発信します。
  • Validator ワーカーは ValidateOrder 活動作業項目のみを扱います。
  • シッパーワーカーは ShipOrder 活動作業項目のみを扱います。

この動作により、作業項目のフィルター処理によって、一致するタスクの種類を登録したワーカーにのみアイテムがルーティングされることを確認します。

少なくとも 1 つのバッチ レポート3 completed, 0 failed が表示されたら、サンプルは想定どおりに動作しています。 ループが終わるのを待つ必要はなく、各ターミナルでCtrl+Cを押すだけでクライアントとワーカーを停止できます。 クライアントを最後まで実行させると、最終的な結果の概要を印刷し、Ctrl+Cで停止するまでそのまま機能します。

試してみる: 厳密なルーティング実験

ルーティングが厳密であることを確認するには (他のワーカーにフォールバックしない):

  1. 荷送人作業者を停止します (ターミナル 3 では Ctrl + C)。
  2. クライアントをもう一度実行して、新しいオーケストレーションをスケジュールします。
  3. 次の点を確認します。
    • Orchestrator ワーカーがオーケストレーションを引き受けて開始します。
    • バリデーター ワーカーは、各注文の ValidateOrder を完了します。
    • ShipOrder 作業項目 は保留中の ままであり、バリデーターやオーケストレーターの作業員はそれらを受け取っていません。
    • オーケストレーションは "実行中" 状態のままで、 ShipOrder が完了するまで待機します。
  4. シッパーワーカーを再起動すれば、保留中の ShipOrder 作業項目が即座に納品され、オーケストレーションも完了します。

この実験は、作業項目が対応するフィルターを持つワーカーにのみルーティングされることを示しています。 フォールバックはありません。

Azure Developer CLI を使用してデプロイする

  1. Azureで認証します (まだ行っていない場合)。

    azd auth login
    
  2. samples/scenarios/WorkItemFilteringSplitActivitiesから、次のコマンドを実行します。

    azd up
    
  3. ターミナルでメッセージが表示されたら、次のパラメーターを指定します。

    パラメーター 説明
    環境名 すべてのAzureリソースを保持するために作成されたリソース グループのプレフィックス。
    Azureの場所 リソースの Azure の場所。
    Azure サブスクリプション リソースのAzure サブスクリプション。

azd up コマンドは、Azure リソースをプロビジョニングし、このサンプルから 4 つのコンテナー化されたサービス (クライアント、オーケストレーター ワーカー、バリデーター ワーカー、荷送人ワーカー) をデプロイします。

デプロイが成功したことを確認する

  1. azd up出力で、リソース グループ名をコピーします。

  2. Azure portal で、そのリソース グループを開きます。

  3. デプロイされたコンテナー アプリ (client、 orchestrator-worker、 validator-worker、 shipper-worker) ごとに、 監視>Log ストリームを開きます。

  4. 各アプリで、予想される作業項目のみをログに記録することを確認します。

    • orchestrator-worker: オーケストレーション作業。
    • validator-worker: ValidateOrder のアクティビティ。
    • shipper-worker: ShipOrder のアクティビティ。

Note

各コンテナー アプリは、保留中の作業項目のバックログに基づいてワーカーを 0 から 10 個のレプリカに自動的にスケーリングする KEDA スケール ルール (azure-durabletask-scheduler) で構成されます。 クライアントがループを終了し、作業項目が残っていない場合、ワーカーはゼロにスケール バックします。 詳細については、「Azure Container Apps での永続タスク スケジューラーのオートスケール 」を参照してください。

C言語の作業項目フィルタリングコードを理解する#

オーケストレーションは、2 つのアクティビティを順番に呼び出します。 スケジューラは、各アクティビティ作業項目を登録したワーカーにルーティングします。

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 portal の上部にあるグローバル検索ボックスを使用して、 rg- または環境名のプレフィックスを検索します。
  3. 検索結果からリソース グループを開きます。

  4. [ リソース グループの削除] を選択し、確認するリソース グループ名を入力して、[削除] を選択 します。

次のステップ

  • ローカル開発用の Durable Task Scheduler エミュレーターを設定して実行します。
  • Orchestrator、Validator、Shipperのワーカーおよびクライアントを実行します。
  • 作業項目が一致するワーカーにのみルーティングされていることを確認します。
  • Azure Developer CLI を使用して Azure Container Apps にサンプルをデプロイします。

前提条件

開始する前に、次の手順を実行します。

プロジェクトを準備する

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
    

    ターミナル 3 - 荷送人

    ./gradlew :shipper-worker:run
    
  5. 4台目の端末でクライアントを起動します。

    ./gradlew :client:run
    
  6. http://localhost:8082でエミュレーター ダッシュボードを開き、オーケストレーション アクティビティを監視します。

作業項目のフィルター処理からの予想される出力

クライアントは30秒ごとに3つのオーケストレーションをスケジュールし、約10分間ループを続けます。 ターミナルの向こう側には、次のようなものがあります:

  • クライアントはオーケストレーションバッチをスケジュールし、各バッチの完了を待ちます。 完了したバッチは 3 completed, 0 failed とログに記録します。
  • オーケストレーターワーカーは ValidateOrder と活動呼び出し ShipOrder を発信します。
  • Validator ワーカーは ValidateOrder 活動作業項目のみを扱います。
  • シッパーワーカーは ShipOrder 活動作業項目のみを扱います。

この動作により、作業項目のフィルター処理によって、一致するタスクの種類を登録したワーカーにのみアイテムがルーティングされることを確認します。

少なくとも 1 つのバッチ レポート3 completed, 0 failed が表示されたら、サンプルは想定どおりに動作しています。 ループが終わるのを待つ必要はなく、各ターミナルでCtrl+Cを押すだけでクライアントとワーカーを停止できます。 クライアントを最後まで実行させると、最終的な結果の概要を印刷し、Ctrl+Cで停止するまでそのまま機能します。

試してみる: 厳密なルーティング実験

ルーティングが厳密であることを確認するには (他のワーカーにフォールバックしない):

  1. 荷送人作業者を停止します (ターミナル 3 では Ctrl + C)。
  2. クライアントをもう一度実行して、新しいオーケストレーションをスケジュールします。
  3. 次の点を確認します。
    • Orchestrator ワーカーがオーケストレーションを引き受けて開始します。
    • バリデーター ワーカーは、各注文の ValidateOrder を完了します。
    • ShipOrder 作業項目 は保留中の ままであり、バリデーターやオーケストレーターの作業員はそれらを受け取っていません。
    • オーケストレーションは "実行中" 状態のままで、 ShipOrder が完了するまで待機します。
  4. シッパーワーカーを再起動すれば、保留中の ShipOrder 作業項目が即座に納品され、オーケストレーションも完了します。

この実験は、作業項目が対応するフィルターを持つワーカーにのみルーティングされることを示しています。 フォールバックはありません。

Azure Developer CLI を使用してデプロイする

  1. Azureで認証します (まだ行っていない場合)。

    azd auth login
    
  2. samples/scenarios/WorkItemFilteringSplitActivitiesJavaから、次のコマンドを実行します。

    azd up
    
  3. ターミナルでメッセージが表示されたら、次のパラメーターを指定します。

    パラメーター 説明
    環境名 すべてのAzureリソースを保持するために作成されたリソース グループのプレフィックス。
    Azureの場所 リソースの Azure の場所。
    Azure サブスクリプション リソースのAzure サブスクリプション。

azd up コマンドは、Azure リソースをプロビジョニングし、このサンプルから 4 つのコンテナー化されたサービス (クライアント、オーケストレーター ワーカー、バリデーター ワーカー、荷送人ワーカー) をデプロイします。

デプロイが成功したことを確認する

  1. azd up出力で、リソース グループ名をコピーします。

  2. Azure portal で、そのリソース グループを開きます。

  3. デプロイされたコンテナー アプリ (client、 orchestrator-worker、 validator-worker、 shipper-worker) ごとに、 監視>Log ストリームを開きます。

  4. 各アプリで、予想される作業項目のみをログに記録することを確認します。

    • orchestrator-worker: オーケストレーション作業。
    • validator-worker: ValidateOrder のアクティビティ。
    • shipper-worker: ShipOrder のアクティビティ。

Note

各コンテナー アプリは、保留中の作業項目のバックログに基づいてワーカーを 0 から 10 個のレプリカに自動的にスケーリングする KEDA スケール ルール (azure-durabletask-scheduler) で構成されます。 クライアントがループを終了し、作業項目が残っていない場合、ワーカーはゼロにスケール バックします。 詳細については、「Azure Container Apps での永続タスク スケジューラーのオートスケール 」を参照してください。

Javaの作業項目フィルタリングコードを理解しましょう

オーケストレーションは、2 つのアクティビティを順番に呼び出します。 スケジューラは、各アクティビティ作業項目を登録したワーカーにルーティングします。

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 はフィルター リストを送信します。 スケジューラはフィルターごとのキューを作成し、各作業項目を一致するキューにルーティングします。 ワーカーは、登録しなかった作業項目の種類を受け取ることはありません。

レジストリから自動生成するのではなく、明示的なフィルターを提供するには、useWorkItemFilters()にWorkItemFilterを渡します。

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

builder.useWorkItemFilters(filter);

リソースをクリーンアップする

  1. ローカルエミュレーターコンテナを停止してください。

    docker rm -f dts-emulator
    
  2. Azure にデプロイした場合は、リソース グループ名を特定します。

    • azd up出力からコピーします。
    • または、 Azure portal の上部にあるグローバル検索ボックスを使用して、 rg- または環境名のプレフィックスを検索します。
  3. 検索結果からリソース グループを開きます。

  4. [ リソース グループの削除] を選択し、確認するリソース グループ名を入力して、[削除] を選択 します。

次のステップ

  • ローカル開発用の Durable Task Scheduler エミュレーターを設定して実行します。
  • ワーカーA、ワーカー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. 各ワーカーを個別のターミナルで実行します。

    ターミナル1 - ワーカーA(挨拶)

    python worker_a.py
    

    ターミナル2 - ワーカーB(数学)

    python worker_b.py
    
  6. 3つ目の端末でクライアントを起動します。

    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

次のステップ