Use as filas de tarefas no Durable Task Scheduler (pré-visualização)

As filas de tarefas agrupam o trabalho de orquestração e de atividades dentro de um hub de tarefas e pode controlar a taxa a que o agendador entrega esse trabalho aos trabalhadores. Utilize filas de tarefas para controlar o ritmo de uma carga de trabalho, como um fluxo de trabalho de processamento em lote que invoca um serviço a jusante com limitação de taxa, sem criar um hub de tarefas separado.

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

Note

As filas de tarefas requerem a versão 2026-07-01-preview ou posterior da API de gestão. Os exemplos neste artigo usam 2026-07-01-preview. Para o esquema de recursos, veja a fila de tarefas ARM e Bicep reference.

Como funcionam as filas de tarefas

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

  • Os itens de orquestração e atividade na mesma fila partilham a taxa configurada.
  • Cada turno de orquestração entregue a um trabalhador conta como uma entrega. 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 uma distribuição. As novas tentativas de entrega também contam.
  • Atividades e suborquestrações herdam a seleção de fila do pai, a menos que a redefinas explicitamente com a própria etiqueta deles DTS_TaskQueue.
  • Os itens de trabalho da Entidade não usam filas de tarefas.

Por exemplo, actionsPerSecond: 20 configura uma taxa sustentada de 20 distribuições por segundo, partilhada pelo trabalho de orquestração e atividade nessa fila. Não significa 20 orquestrações concluídas, conclusões de atividades ou pedidos à API a jusante por segundo. Rajadas curtas podem exceder a taxa sustentada, e o débito real pode ser menor devido à distribuição do trabalho, capacidade do trabalhador ou capacidade do agendador.

Se omitir o throughput ao criar uma fila, esta não tem limite de taxa específico para cada fila. Os limites de capacidade para scheduler e worker continuam a aplicar-se. As filas de tarefas não reservam computação, não fornecem isolamento físico nem definem prioridade entre filas nomeadas. Para limites rigorosos de pedidos para serviços downstream, aplique também a limitação da taxa de pedidos nas atividades que chamam o serviço downstream.

Prerequisites

  • Uma subscrição do Azure com um agendador e task hub existente. Para localizações de agendadores, consulte regiões suportadas.
  • Permissão para gerir recursos da fila de tarefas sob o hub de tarefas, como a função Contribuidor herdada do agendador ou grupo de recursos. Os papéis de plano de dados por si só não concedem permissões de gestão de recursos.
  • CLI do Azure para os az rest exemplos, ou um cliente Azure Resource Manager REST autenticado. Os exemplos de CLI usam sintaxe Bash e não requerem uma extensão CLI dedicada para a 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 ligam sem filtros de itens de trabalho. Veja Configurar trabalhadores elegíveis.

Configurar trabalhadores elegíveis

Apenas as ligações de worker sem work item filters podem receber trabalho de filas de tarefas definidas. Uma ligação de trabalhador com quaisquer filtros, incluindo filtros coringa, não é elegível. Garante que os workers sem filtro registem todas as orquestrações e atividades que encaminhas para as filas.

O .NET Durable Task SDK gera automaticamente filtros a partir do seu registo 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 em Java, Python e Go, não optes por fazer filtragem de itens de trabalho para estes workers. Se a tua aplicação já configura filtros, remove essa configuração. Para opções de filtragem específicas do SDK, veja Enable work item filtering.

Importante

O trabalho numa fila definida espera até que um trabalhador elegível se ligue ao sistema. Não reverte para um worker filtrado. Por outro lado, se a fila nomeada não existir ou foi eliminada, o trabalho usa o encaminhamento normal do hub de tarefas e o limite de taxa da fila solicitada não é aplicado. Cria a fila e espera que o provisionamento tenha sucesso antes de agendares o trabalho etiquetado.

Configurar a CLI do Azure

Inicie sessão e selecione a subscrição que contém o seu agendador de tarefas:

az login
az account set --subscription SUBSCRIPTION_ID

Defina as seguintes variáveis Bash. Substitua os nomes do grupo de recursos, do agendador e do hub de tarefas pelos nomes dos seus 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"

Criar uma fila de tarefas

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

Os exemplos seguintes criam a fila orders com uma taxa sustentada de 20 distribuições de itens de trabalho por segundo. Definir actionsPerSecond para um número inteiro positivo, ou omitir throughput para criar uma fila sem um limite de taxa específico para cada fila.

Utilize 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 gestão de recursos são assíncronas. Depois de 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 seja Succeeded antes de enviar o trabalho etiquetado. Pare se o estado estiver Failed, ocorrer um erro ou se o seu tempo limite de sondagem expirar. Resolva o erro de gestão de recursos antes de usar a fila. Um pedido de gestão aceite por si só não significa que a fila esteja pronta. Para intervalos de sondagem e acompanhamento de operações, veja Seguir operações assíncronas do Azure.

Suporte SDK

A seleção de fila usa etiquetas de orquestração e atividade, não etiquetas de recursos do Azure. A tabela seguinte mostra onde pode definir DTS_TaskQueueexplicitamente .

SDK ou extensão Inicie uma orquestração Agendar uma atividade Agendar sub-orquestração
SDK .NET de Tarefas Duráveis Yes Yes Yes
SDK JavaScript/TypeScript de Tarefas Duráveis Yes Yes Yes
SDK Python de Tarefas Duráveis Yes Yes No
SDK Durable Task Java (v1.6.0+) Yes No No
Durable Task Go SDK (beta) Yes Yes Yes
Durable Functions: .NET isolated Yes Yes Yes
Durable Functions: Java Yes No No

As associações in-process do Durable Functions .NET, JavaScript e Python não expõem estas opções explícitas de etiquetas. Não presuma que o suporte autónomo de uma linguagem para SDK de Tarefas Durables também se aplica ao seu binding Durable Functions. Em todos os casos, a ligação do worker deve também cumprir o requisito de worker não filtrado.

Encaminhar uma orquestração para uma fila

Defina a chave da etiqueta literal DTS_TaskQueue como o nome de uma fila no mesmo hub de tarefas. Os excertos seguintes assumem que já configurou um cliente e registou a sua orquestração. Utilize a orders queue 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 a sua seleção de filas. Não precisas de repetir a tag em todas as invocações. Defina a etiqueta da fila ao agendar o trabalho; atualizar a taxa de processamento da fila não requer alterar a etiqueta.

Sobrescrever a fila para uma atividade ou suborquestração

Para ajustar 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. Aguarda que o provisionamento dessa fila seja concluído com êxito primeiro.

Por exemplo, pode deixar a coordenação de orquestração em orders e encaminhar chamadas para um serviço downstream através de partner-api. A sobreposição da atividade seleciona a fila da atividade; não move a orquestração principal.

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 seguintes exemplos de gestão utilizam 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 num task hub:

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

Atualize a taxa da fila para 10 folhetos 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 um pedido PATCH mantém a taxa existente inalterada. Um pedido PUT substitui a configuração; omitir o throughput no pedido PUT remove o limite de taxa específico da fila. Após atualizar, aguarde até que o provisionamento seja concluído com sucesso e verifique a configuração devolvida.

Eliminar uma fila de tarefas

Warning

Eliminar uma fila remove o seu limite de pedidos. Trabalhos marcados com o nome da fila eliminada usam o roteamento normal do hub de tarefas. Não uses a eliminação de filas para pausar uma carga de processamento.

Eliminar o recurso de fila:

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

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

Resolver problemas de encaminhamento de filas

Se o trabalho em fila não estiver a progredir, verifique se a fila existe e que o provisionamento foi bem-sucedido, a etiqueta identifica a fila pretendida no mesmo hub de tarefas e um worker funcional liga-se sem filtros. Uma fila definida, sem trabalhadores elegíveis, mantém a sua tarefa de trabalho em vez de a entregar a um trabalhador excluído pelo filtro.

Se o trabalho for executado sem o limite de taxa esperado, verifique se há fila em falta ou eliminada. Nesse caso, o agendador usa o encaminhamento normal do hub de tarefas. Também tenha em conta os picos breves e a diferença entre materiais distribuídos e fluxos de trabalho concluídos. Utilize o painel do escalonador para inspecionar o estado da orquestração e as etiquetas.