Verwenden Sie Task Queues im Durable Task Scheduler (Vorschau)

Aufgabenwarteschlangen fassen Orchestrierungs- und Aktivitätsarbeit innerhalb eines Task Hubs zusammen, und man kann steuern, wie schnell der Scheduler diese Arbeit an die Arbeiter ausliefert. Nutzen Sie Aufgabenwarteschlangen, um eine Arbeitslast zu steuern, wie zum Beispiel einen Batch-Verarbeitungs-Workflow, der einen rate-limitierten Downstream-Service aufruft, ohne einen separaten Task-Hub zu erstellen.

Um eine Task-Warteschlange zu verwenden, erstelle zuerst eine Warteschlangenressource unter deinem Task-Hub. Setzen Sie dann das DTS_TaskQueue-Tag, wenn Sie eine Orchestrierung oder Aktivität planen. Der Tag wählt eine bestehende Warteschlange aus; er erstellt keine Warteschlange.

Wie Aufgaben-Warteschlangen funktionieren

Eine Task-Warteschlange gehört zu einem Task-Hub. Seine optionale properties.throughput.actionsPerSecond Einstellung steuert die dauerhafte Rate der Arbeitsaufgaben-Zuweisungen: Zuweisungen von Arbeitselementen vom Scheduler an die Worker.

• Orchestrierungs- und Aktivitätsarbeitselemente in derselben Warteschlange teilen sich die konfigurierte Rate.
• Jeder Orchestrierungsdurchlauf, der an einen Worker übergeben wird, zählt als ein Handout. Eine Orchestrierung kann mehrere Schritte benötigen, bevor sie abgeschlossen ist.
• Jedes Arbeitselement der Aktivität, das einem Mitarbeiter geliefert wird, zählt als eine Ausgabe. Auch erneute Zustellversuche zählen.
• Aktivitäten und Unterorchestrierungen übernehmen die Warteschlangenauswahl ihres übergeordneten Elements, es sei denn, du überschreibst sie explizit mit ihrem eigenen DTS_TaskQueue-Tag.
• Entitäten-Arbeitselemente verwenden keine Taskwarteschlangen.

Zum Beispiel konfiguriert actionsPerSecond: 20 eine anhaltende Rate von 20 Ausgaben pro Sekunde, die von der Orchestrierung und der Aktivitätsarbeit in dieser Warteschlange gemeinsam genutzt wird. Das bedeutet nicht 20 abgeschlossene Orchestrierungen, Aktivitätsabschlüsse oder nachgelagerte API-Anfragen pro Sekunde. Kurzzeitige Spitzen können die konstante Durchsatzrate übersteigen, und der tatsächliche Durchsatz kann aufgrund der Arbeitsverteilung, der Kapazität der Arbeiter oder der Planungskapazität geringer sein.

Wenn Sie beim Erstellen einer Warteschlange den Durchsatz weglassen, hat die Warteschlange kein warteschlangenspezifisches Rate-Limit. Es gelten weiterhin Begrenzungen für Scheduler- und Worker-Kapazitäten. Task-Warteschlangen reservieren keine Rechenleistung, bieten keine physische Isolation und setzen keine Priorität zwischen benannten Warteschlangen. Für strenge Downstream-Anfragelimits solltest du auch dort eine Ratenbegrenzung anwenden, wo deine Aktivität den Downstream-Dienst aufruft.

Prerequisites

• Ein Azure-Abonnement mit einem bestehenden Scheduler und Task Hub. Informationen zu Scheduler-Standorten finden Sie unter unterstützte Regionen.
• Berechtigung zur Verwaltung von Aufgaben-Warteschlangen-Ressourcen unter dem Task-Hub, wie zum Beispiel der Contributor-Rolle , die vom Scheduler oder der Ressourcengruppe übernommen wurde. Data-Plane-Rollen allein gewähren keine Ressourcenverwaltungsberechtigungen.
• Azure CLI für die az rest Beispiele oder einen authentifizierten Azure Resource Manager REST-Client. Die CLI-Beispiele verwenden die Bash-Syntax und benötigen keine dedizierte Aufgabenwarteschlangen-CLI-Erweiterung.
• Eine Anwendung, die so konfiguriert ist, dass sie den Durable Task Scheduler verwendet, mit identitätsbasiertem Zugriff und einem SDK, das Tags unterstützt. Siehe SDK-Unterstützung.
• Worker, die sich ohne Arbeitsfilter verbinden. Siehe Berechtigte Mitarbeiter konfigurieren.

Berechtigte Mitarbeiter konfigurieren

Nur Worker-Verbindungen ohne Workitem-Filter können Arbeit aus definierten Task-Warteschlangen empfangen. Eine Worker-Verbindung mit irgendwelchen Filtern, einschließlich Wildcard-Filtern, ist nicht zulässig. Stellen Sie sicher, dass die ungefilterten Worker alle Orchestrierungen und Aktivitäten verarbeiten, die Sie an die Warteschlangen weiterleiten.

Das .NET Durable Task SDK generiert automatisch Filter aus seiner Task-Registrierung. Deaktivieren Sie explizit das Filtern beim Konfigurieren eines Workers für Aufgabenwarteschlangen:

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

Aktivieren Sie in den Java-, Python- und Go-SDKs für diese Worker keine Work-Item-Filterung. Wenn deine Anwendung bereits Filter konfiguriert, entferne diese Konfiguration. Für SDK-spezifische Filteroptionen siehe Filterung von Arbeitselementen aktivieren.

Einrichten der Azure CLI

Melden Sie sich an und wählen Sie das Abonnement aus, das den Scheduler enthält:

az login
az account set --subscription SUBSCRIPTION_ID

Legen Sie die folgenden Bash-Variablen fest. Ersetzen Sie die Namen der Ressourcengruppen, des Schedulers und des Task Hubs durch Ihre bestehenden Ressourcen. Die Beispiele erstellen eine Warteschlange namens 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"

Erstellen Sie eine Aufgabenwarteschlange

Der Warteschlangenname muss 3 bis 64 Buchstaben, Zahlen oder Bindestriche enthalten und ^[a-zA-Z0-9-]{3,64}$ entsprechen. Eine Warteschlange ist eine Kindressource eines Task Hubs; sie hat weder eigene location- noch Azure-Ressourcen-tags-Eigenschaften.

Die folgenden Beispiele erstellen die orders Warteschlange mit einer anhaltenden Rate von 20 Ausgaben von Arbeitselementen pro Sekunde. Setze actionsPerSecond auf eine positive ganze Zahl oder lasse throughput weg, um eine Warteschlange ohne warteschlangenspezifische Geschwindigkeitsbegrenzung zu erstellen.

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

PUT https://management.azure.com/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP/providers/Microsoft.DurableTask/schedulers/SCHEDULER_NAME/taskHubs/TASK_HUB_NAME/taskQueues/orders?api-version=2026-07-01-preview
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "properties": {
    "throughput": {
      "actionsPerSecond": 20
    }
  }
}

param schedulerName string
param taskHubName string

@minLength(3)
@maxLength(64)
param queueName string = 'orders'

@minValue(1)
param actionsPerSecond int = 20

resource scheduler 'Microsoft.DurableTask/schedulers@2026-02-01' existing = {
  name: schedulerName
}

resource taskHub 'Microsoft.DurableTask/schedulers/taskHubs@2026-02-01' existing = {
  parent: scheduler
  name: taskHubName
}

resource taskQueue 'Microsoft.DurableTask/schedulers/taskHubs/taskQueues@2026-07-01-preview' = {
  parent: taskHub
  name: queueName
  properties: {
    throughput: {
      actionsPerSecond: actionsPerSecond
    }
  }
}

az deployment group create \
  --resource-group "$resourceGroup" \
  --template-file task-queue.bicep \
  --parameters schedulerName="$schedulerName" taskHubName="$taskHubName" \
    queueName="$queueName" actionsPerSecond=20

Auf die Bereitstellung warten

Ressourcenmanagement-Operationen sind asynchron. Nachdem Sie eine Warteschlange erstellt oder aktualisiert haben, rufen Sie sie ab und prüfen Sie properties.provisioningState:

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

Wiederholen Sie die Abfrage, bis der Zustand Succeeded ist, bevor Sie markierte Arbeitselemente senden. Stoppen, wenn der Status Failed ist, ein Fehler auftritt oder das Polling-Timeout abläuft. Beheben Sie den Fehler im Ressourcenmanagement, bevor Sie die Warteschlange verwenden. Eine akzeptierte Verwaltungsanforderung allein bedeutet nicht, dass die Warteschlange bereit ist. Für Abfrageintervalle und Operationsverfolgung siehe Asynchrone Azure-Operationen verfolgen.

SDK-Unterstützung

Warteschlangenauswahl verwendet Orchestrierungs- und Aktivitäts-Tags, keine Azure-Ressourcen-Tags. Die folgende Tabelle zeigt, wo Sie DTS_TaskQueue explizit setzen können.

Durable Functions .NET In-Process-, JavaScript- und Python-Bindings stellen diese expliziten Tag-Optionen nicht bereit. Gehen Sie nicht davon aus, dass die eigenständige Durable Task SDK-Unterstützung einer Sprache auch für die Durable Functions-Bindung gilt. In jedem Fall muss die Worker-Verbindung auch die unfiltered-worker-Anforderung erfüllen.

Routen Sie eine Orchestrierung zu einer Warteschlange

Setze den literalen Tag-Schlüssel DTS_TaskQueue auf den Namen einer Warteschlange im selben Task-Hub. Die folgenden Ausschnitte gehen davon aus, dass du bereits einen Client konfiguriert und deine Orchestrierung registriert hast. Nutze die orders zuvor erstellte Warteschlange.

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

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

const instanceId = await client.scheduleNewOrchestration(
    "ProcessOrderOrchestration",
    order,
    {
        tags: {
            DTS_TaskQueue: "orders",
        },
    }
);

instance_id = client.schedule_new_orchestration(
    "process_order_orchestration",
    input=order,
    tags={"DTS_TaskQueue": "orders"},
)

NewOrchestrationInstanceOptions options = new NewOrchestrationInstanceOptions()
    .setTags(Map.of("DTS_TaskQueue", "orders"));

String instanceId = client.scheduleNewOrchestrationInstance(
    "ProcessOrderOrchestration", order, options);

instanceID, err := client.ScheduleNewOrchestration(
	ctx,
	"ProcessOrderOrchestration",
	api.WithTags(map[string]string{"DTS_TaskQueue": "orders"}),
)
if err != nil {
	return err
}

Die Aktivitäten und Unterorchestrierungen der Orchestrierung übernehmen die Warteschlangenauswahl. Du musst den Tag nicht bei jedem Aufruf wiederholen. Setzen Sie das Warteschlangen-Tag beim Planen von Arbeit; das Aktualisieren der Warteschlangenrate erfordert keine Änderung des Tags.

Überschreiben der Warteschlange für eine Aktivität oder Suborchestrierung

Um eine Teilmenge eines Workflows unabhängig zu steuern, erstelle eine weitere Warteschlange, wie partner-api, und setze DTS_TaskQueue explizit auf den Aktivitäts- oder Suborchestrierungsaufruf. Warte, bis die Bereitstellung dieser Warteschlange erfolgreich abgeschlossen ist.

Zum Beispiel können Sie die Orchestrierungskoordination in orders belassen und Aufrufe an einen nachgelagerten Dienst über partner-api weiterleiten. Der Aktivitäts-Override wählt die Warteschlange der Aktivität aus; er verschiebt den übergeordneten Orchestrierungsworkflow nicht.

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);

const result = yield ctx.callActivity(callPartnerApi, order, {
    tags: { DTS_TaskQueue: "partner-api" },
});

const childResult = yield ctx.callSubOrchestrator(validateOrderOrchestration, order, {
    tags: { DTS_TaskQueue: "partner-api" },
});

result = yield ctx.call_activity(
    "call_partner_api",
    input=order,
    tags={"DTS_TaskQueue": "partner-api"},
)

Warteschlangen anzeigen und aktualisieren

Die folgenden Management-Beispiele verwenden die Bash-Variablen aus Set up Azure CLI.

Rufen Sie die Konfiguration einer Warteschlange ab:

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

Warteschlangen in einem Task-Hub auflisten:

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

Aktualisieren Sie die Rate der Warteschlange auf 10 Handouts pro Sekunde:

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

Um das warteschlangenspezifische Rate-Limit zu entfernen und gleichzeitig die Warteschlange beizubehalten, setzen Sie explizit throughput auf null:

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

Das Weglassen von Durchsatz bei einer PATCH-Anfrage lässt die bestehende Rate unverändert. Eine PUT-Anfrage ersetzt die Konfiguration; das Weglassen des Durchsatzes aus PUT entfernt das warteschlangenspezifische Rate-Limit. Nach dem Update warten Sie, bis die Bereitstellung erfolgreich ist, und überprüfen Sie die zurückgegebene Konfiguration.

Eine Aufgabenwarteschlange löschen

Löschen Sie die Warteschlangenressource:

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

Das Löschen ist asynchron. Folgen Sie der asynchronen Operation des Azure Resource Manager bis zum Abschluss, oder führen Sie GET-Abfragen mit einem Timeout aus, bis die Warteschlange 404 Not Found zurückgibt. Behandle Autorisierungsfehler oder andere Anfragefehler nicht als Bestätigung der Löschung. Das Löschen einer Warteschlange bricht die Orchestrierungen, die sie verwendet haben, nicht ab.

Probleme beim Warteschlangen-Routing beheben

Wenn die in die Warteschlange eingereihten Arbeiten nicht vorankommen, überprüfen Sie, ob die Warteschlange existiert und die Bereitstellung erfolgreich war, das Tag die vorgesehene Warteschlange im selben Task-Hub identifiziert und sich ein fehlerfreier Worker ohne Filter verbindet. Eine definierte Warteschlange ohne geeignete Worker behält ihre Arbeit, anstatt sie an einen gefilterten Worker zu liefern.

Wenn die Arbeit ohne das erwartete Rate-Limit läuft, prüfe auf eine fehlende oder gelöschte Warteschlange. In diesem Fall verwendet der Scheduler gewöhnliches Task-Hub-Routing. Berücksichtigen Sie auch kurze Bursts und den Unterschied zwischen Handouts und abgeschlossenen Arbeitsabläufen. Nutzen Sie das Scheduler-Dashboard , um den Orchestrierungsstatus und die Tags zu überprüfen.

Verwandte Inhalte

• Fügen Sie Tags zu Orchestrierungen und Aktivitäten hinzu
• Arbeitsaufgabenfilterung
• Konfigurieren des identitätsbasierten Zugriffs
• Task Queue ARM und Bicep-Referenz