Use as filas de tarefas no Durable Task Scheduler (prévia)

Filas de tarefas agrupam orquestração e trabalho de atividades dentro de um task hub, e você pode controlar a taxa com que o agendador entrega esse trabalho aos trabalhadores. Use filas de tarefas para ajustar o ritmo de uma carga de trabalho, como um fluxo de trabalho de processamento em lote que chama um serviço downstream limitado por taxa, sem criar um hub de tarefas separado.

Para usar uma fila de tarefas, primeiro crie um recurso de fila no seu hub de tarefas. Depois, defina a DTS_TaskQueue tag quando agendar uma orquestração ou atividade. A marcação seleciona uma fila existente; ela não cria uma.

Note

Filas de tarefas requerem versão 2026-07-01-preview da API de gerenciamento ou posterior. Os exemplos neste artigo usam 2026-07-01-preview. Para o esquema de recursos, veja a fila de tarefas ARM e referência Bicep.

Como funcionam as filas de tarefas

Uma fila de tarefas pertence a um único hub de tarefas. Sua configuração opcional properties.throughput.actionsPerSecond controla a taxa sustentada de distribuição de itens de trabalho: entregas de itens de trabalho do agendador aos trabalhadores.

  • Itens de orquestração e atividade na mesma fila compartilham a taxa configurada.
  • Cada turno de orquestração entregue a um trabalhador conta como um material informativo. Uma orquestração pode exigir várias interações antes de ser concluída.
  • Cada item de trabalho de atividade entregue a um trabalhador conta como um material informativo. As reentregas também contam.
  • Atividades e suborquestrações herdam a seleção de fila do pai, a menos que você a sobrescreva explicitamente com a marcação deles DTS_TaskQueue.
  • Itens de trabalho de entidade não usam filas de tarefas.

Por exemplo, actionsPerSecond: 20 configura uma taxa sustentada de 20 despachos por segundo, compartilhada pelo trabalho de orquestração e atividade nessa fila. Isso não significa 20 orquestrações concluídas, conclusões de atividades ou requisições de API downstream por segundo. Rajadas curtas podem exceder a taxa sustentada, e a taxa real de transferência pode ser menor devido à distribuição do trabalho, capacidade de trabalhadores ou capacidade do escalonador.

Se você omitir o throughput ao criar uma fila, a fila não tem limite de taxa específico para cada fila. Os limites de capacidade do agendador e dos workers ainda se aplicam. Filas de tarefas não reservam computação, não oferecem isolamento físico nem definem prioridade entre filas nomeadas. Para limites rigorosos de requisições downstream, também aplique limites de taxa onde sua atividade chama o serviço downstream.

Prerequisites

  • Uma assinatura do Azure com um agendador e um hub de tarefas existentes. Para localizações de escalonadores, veja regiões suportadas.
  • Permissão para gerenciar recursos da fila de tarefas sob o hub de tarefas, como o papel de Contribuidor herdado do escalonador ou grupo de recursos. Os papéis do plano de dados, por si só, não concedem permissões de gerenciamento de recursos.
  • CLI do Azure para os exemplos az rest, ou um cliente Azure Resource Manager REST autenticado. Os exemplos de CLI usam a sintaxe Bash e não exigem uma extensão de CLI dedicada para fila de tarefas.
  • Uma aplicação configurada para usar o Durable Task Scheduler, com acesso baseado em identidade e um SDK que suporta tags. Veja suporte ao SDK.
  • Trabalhadores que se conectam sem filtros de itens de trabalho. Consulte Configurar trabalhadores elegíveis.

Configurar trabalhadores elegíveis

Somente conexões de trabalhadores sem filtros de itens de trabalho podem receber trabalho de filas de tarefas definidas. Uma conexão de trabalhador com qualquer filtro, incluindo filtros coringa, não é elegível. Garanta que os workers sem filtro registrem todas as orquestrações e atividades que você direcionar para as filas.

O .NET Durable Task SDK gera automaticamente filtros a partir de seu registro de tarefas. Opte explicitamente por não filtrar ao configurar um worker para filas de tarefas:

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

Nos SDKs de Java, Python e Go, não opte pela filtragem de itens de trabalho para esses workers. Se sua aplicação já configura filtros, remova essa configuração. Para opções de filtragem específicas do SDK, veja Habilitar a filtragem de itens de trabalho.

Importante

O trabalho em uma fila definida espera até que um trabalhador elegível se conecte. Não recorre a um trabalhador filtrado. Por outro lado, se a fila nomeada não existir ou foi excluída, o trabalho usa roteamento comum do hub de tarefas e o limite de taxa da fila solicitada não é aplicado. Crie a fila e espere o provisionamento ser concluído com êxito antes de agendar trabalhos com etiquetas.

Configurar a CLI do Azure

Entre e selecione a assinatura que contém seu agendador:

az login
az account set --subscription SUBSCRIPTION_ID

Defina as variáveis Bash a seguir. Substitua os nomes do grupo de recursos, do escalonador e do hub de tarefas pelos nomes dos recursos existentes. Os exemplos criam uma fila chamada 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"

Crie uma fila de tarefas

O nome da fila deve conter de 3 a 64 letras, números ou hífens, que correspondam a ^[a-zA-Z0-9-]{3,64}$. Uma fila é um recurso filho de um hub de tarefas; ela não possui suas próprias propriedades location ou de recurso do Azure tags.

Os exemplos a seguir criam a fila orders com uma taxa sustentada de 20 materiais informativos de itens de trabalho por segundo. Defina actionsPerSecond como um número inteiro positivo ou omita throughput para criar uma fila sem limite de taxa por fila.

Use az rest para chamar a API do Azure Resource Manager:

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

Aguarde o provisionamento

As operações de gerenciamento de recursos são assíncronas. Após criar ou atualizar uma fila, recupere-a e verifique properties.provisioningState:

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

Repita a consulta até que o estado esteja Succeeded antes de enviar o trabalho com marcação. Pare se o estado estiver Failed, ocorrer um erro ou se o tempo limite da sondagem expirar. Resolva o erro de gerenciamento de recursos antes de usar a fila. Uma solicitação de gerenciamento aceita, por si só, não significa que a fila está pronta. Para intervalos de sondagem e rastreamento de operações, veja Rastrear operações assíncronas do Azure.

Suporte do SDK

A seleção de fila usa etiquetas de orquestração e atividade, não tags de recurso do Azure. A tabela a seguir mostra onde você pode definir DTS_TaskQueueexplicitamente .

SDK ou extensão Iniciar uma orquestração Agende uma atividade Agende uma suborquestração
SDK do .NET para Tarefas Duráveis Yes Yes Yes
SDK JavaScript/TypeScript para Tarefas Duráveis Yes Yes Yes
SDK de Tarefa Durável do Python Yes Yes No
SDK Java para Tarefas Duráveis (v1.6.0+) Yes No No
SDK Durable Task Go (beta) Yes Yes Yes
Durable Functions: .NET isolated Yes Yes Yes
Durable Functions: Java Yes No No

Durable Functions .NET in-process, JavaScript e Python bindings não expõem essas opções explícitas de tags. Não presuma que o suporte standalone a Durable Task SDK de uma linguagem também se aplica ao seu binding Durable Functions. Em todos os casos, a conexão do trabalhador também deve atender ao requisito trabalhador sem filtro.

Rotear uma orquestração para uma fila

Defina a chave DTS_TaskQueue literal de tag para o nome de uma fila no mesmo hub de tarefas. Os trechos a seguir assumem que você já configurou um cliente e registrou sua orquestração. Use a fila orders criada anteriormente.

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

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

As atividades e suborquestrações da orquestração herdam sua seleção de filas. Você não precisa repetir a tag em todas as chamadas. Defina a tag de fila ao agendar o trabalho; atualizar a taxa de uma fila não exige alterar a tag.

Substituir a fila para uma atividade ou suborquestração

Para controlar o ritmo de um subconjunto de um fluxo de trabalho de forma independente, crie outra fila, como partner-api, e defina DTS_TaskQueue explicitamente na chamada de atividade ou suborquestração. Espere que a provisão dessa fila seja concluída com êxito primeiro.

Por exemplo, você pode deixar a coordenação de orquestração em orders e encaminhar chamadas para um serviço a jusante através de partner-api. A sobrescrita da atividade seleciona a fila da atividade; ela não move a orquestração pai.

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

Ver e atualizar filas

Os exemplos de gerenciamento a seguir usam as variáveis Bash do Set Up CLI do Azure.

Recuperar a configuração de uma fila:

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

Liste as filas em um hub de tarefas:

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

Atualize a taxa da fila para 10 materiais informativos por segundo:

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

Para remover o limite de taxa específico da fila mantendo a fila, defina throughput explicitamente para null:

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

Omitir o throughput de uma requisição PATCH deixa a taxa existente inalterada. Uma requisição PUT substitui a configuração; omitir o throughput do PUT remove o limite de taxa específico da fila. Após atualizar, aguarde o provisionamento ser concluído com êxito e verifique a configuração retornada.

Exclua uma fila de tarefas

Warning

Excluir uma fila remove seu limite de taxa. Trabalhos marcados com o nome da fila excluída usam o roteamento comum do hub de tarefas. Não use a exclusão de filas para pausar uma carga de trabalho.

Exclua o recurso de fila:

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

A exclusão é assíncrona. Siga a operação assíncrona do Azure Resource Manager até o fim, ou faça uma sondagem no GET com um timeout até que a fila retorne 404 Not Found. Não trate erros de autorização ou outras falhas de requisição como confirmação de exclusão. Deletar uma fila não termina as orquestrações que a usaram.

Solucionar problemas de roteamento da fila

Se o trabalho em fila não estiver progredindo, verifique se a fila existe e que o provisionamento foi bem-sucedido, a tag identifica a fila pretendida no mesmo hub de tarefas e um trabalhador saudável se conecta sem filtros. Uma fila definida, sem workers elegíveis, mantém seu trabalho em vez de entregá-lo a um worker filtrado.

Se o trabalho for executado sem o limite de taxa esperado, verifique se há uma fila ausente ou excluída. Nesse caso, o agendador usa roteamento comum do hub de tarefas. Também considere os picos curtos e a diferença entre materiais informativos e fluxos de trabalho concluídos. Use o painel do agendador para inspecionar o status da orquestração e as marcações.