Durable Task Scheduler (プレビュー) でタスク キューを使用する

タスクキューは、task hub 内でオーケストレーションとアクティビティ作業をグループ化し、スケジューラがその作業をワーカーに配信する速度を制御できます。 タスクキューを使って、タスクハブを別に作成せずに、レート制限付きの下流サービスを呼び出すバッチ処理ワークフローなど、ワークロードのペースを調整できます。

タスクキューを使うには、まずタスクハブの下にキューリソースを作成します。 そしてオーケストレーションやアクティビティをスケジュールするときに DTS_TaskQueue タグを設定します。 タグは既存のキューを選択します。キューを作成するわけではありません。

Note

タスクキューは管理APIバージョン 2026-07-01-preview 以降が必要です。 この記事の例では、 2026-07-01-previewを使用します。 リソーススキーマについては、タスクキューのARMおよびBicep参照を参照してください。

タスクキューの仕組み

タスクキューは1つのタスクハブに属します。 オプションの properties.throughput.actionsPerSecond 設定は、作業項目の引き渡し(スケジューラーから作業者への作業項目の配信)の継続的な速度を制御します。

  • 同じキュー内のオーケストレーションとアクティビティ作業項目は設定されたレートを共有します。
  • ワーカーに渡される各オーケストレーションターンは、1回の配布としてカウントされます。 オーケストレーションは完了までに複数回のやり取りが必要になることがあります。
  • ワーカーに届けられた各作業項目は 1 つの配布資料としてカウントされます。 再配達もカウントされます。
  • アクティビティやサブオーケストレーションは、独自の DTS_TaskQueue タグで明示的に上書きしない限り、親のキュー選択を継承します。
  • エンティティの作業項目はタスクキューを使用しません。

例えば、actionsPerSecond: 20 は、オーケストレーション処理と、そのキュー内のアクティビティ処理で共有される、毎秒 20 の配布資料の払い出しレートが継続するように設定します。 それは、1秒あたり20件の完了したオーケストレーション、アクティビティの完了、または下流APIリクエストを意味するものではありません。 短時間のバーストは持続レートを超えることがあり、実際のスループットは作業分散、ワーカーの処理能力、またはスケジューラーの能力により低くなることがあります。

キュー作成時にスループットを省略すると、キュー固有のレート制限はありません。 スケジューラーとワーカーの容量制限は依然として適用されます。 タスクキューは計算を予約したり、物理的な隔離を提供したり、名前付きキュー間の優先順位を設定したりしません。 厳格な下流リクエスト制限のために、アクティビティが下流サービスを呼び出す箇所でもレート制限を適用してください。

Prerequisites

  • 既存のスケジューラーとタスクハブを備えたAzureサブスクリプションです。 スケジューラーの所在地については、サポートされているリージョンを参照してください。
  • タスク ハブ配下のタスク キュー リソースを管理するためのアクセス許可 (スケジューラまたはリソース グループから継承された共同作成者ロールなど)。 データプレーンの役割だけではリソース管理権限は付与されません。
  • az rest の例としては Azure CLI または認証済み Azure Resource Manager REST クライアントが挙げられます。 CLIの例はBashの構文を使用しており、専用のタスクキューCLI拡張を必要としません。
  • Durable Task Schedulerを使用するように設定され、identity ベースのアクセスとタグをサポートするSDKを備えたアプリケーションです。 SDK サポートをご覧ください。
  • 作業項目フィルターなしで接続するワーカー。 適格な作業者を設定を参照してください。

対象となる作業者を設定

ワークアイテムフィルターを持たないワーカー接続のみが定義されたタスクキューから作業を受け取ることができます。 ワーカーの接続は、ワイルドカードフィルターを含むいかなるフィルターがある場合も適格ではありません。 フィルターなしのワーカーが、キューにルーティングするすべてのオーケストレーションとアクティビティを登録するようにしてください。

.NET Durable Task SDKはタスクレジストリから自動的にフィルターを生成します。 タスクキューのワーカー設定時にフィルタリングを明示的に無効にする:

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

Java、Python、Go SDKでは、これらのワーカーの作業アイテムフィルタリングにオプトインしないでください。 もしアプリケーションがすでにフィルターを設定しているなら、その設定を削除してください。 SDK固有のフィルタリングオプションについては、「 作業項目フィルタリングを有効にする」をご覧ください。

Important

定義されたキュー内の作業は、対象となるワーカーが接続するまで待ちます。 フィルター済みのワーカーにフォールバックしません。 逆に、名前付きキューが存在しないか削除された場合、Workは通常のタスクハブルーティングを使い、要求されたキューのレート制限は強制されません。 キューを作成し、プロビジョニングが成功するのを待ってからタグ付きの作業をスケジュールしてください。

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"

タスクキューを作成する

キュー名は、^[a-zA-Z0-9-]{3,64}$ に一致する 3 ~ 64 文字の文字、数字、またはハイフンで構成されている必要があります。 キューはタスク ハブの子リソースであり、独自の location プロパティや Azure リソース tags プロパティがありません。

以下の例は、1秒間に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 isolated Yes Yes Yes
Durable Functions: Java Yes No No

Durable Functions .NETインプロセス、JavaScript、Pythonバインディングではこれらの明示的なタグオプションは公開されません。 言語のスタンドアロンのDurable Task SDKサポートがDurable Functionsバインディングにも適用されるとは限りません。 いずれの場合も、ワーカー接続は フィルターなしワーカー要件も満たさなければなりません。

オーケストレーションをキューにルーティングする

リテラル タグ キー 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"

キューの配布速度を1秒あたり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非同期操作を完了まで続けるか、キューが 404 Not Found を返すまでタイムアウトを設定して GET をポーリングします。 認可エラーやその他のリクエスト失敗を削除の確認とみなさないでください。 キューを削除しても、それを使用したオーケストレーションは終了しません。

キュー ルーティングのトラブルシューティング

キューされている作業が進行していない場合は、キューが存在し、プロビジョニングが成功していること、タグが同じタスク ハブ内の対象キューを識別していること、および正常なワーカーがフィルターなしで接続していることを確認します。 適格なワーカーがいない定義されたキューは、フィルターされたワーカーに作業を引き渡すのではなく、その作業を保持します。

想定したレート制限が適用されずに処理が実行される場合は、キューが存在しない、または削除されていないか確認してください。 その場合、スケジューラは通常のタスクハブルーティングを使用します。 短時間のバースト的な負荷や、配布資料件数とワークフローの完了件数の違いも考慮してください。 スケジューラダッシュボードを使ってオーケストレーションの状態やタグをチェックしてください。