Utiliza las colas de tareas en Durable Task Scheduler (vista previa)

Las colas de tareas agrupan el trabajo de orquestación y de actividad dentro de un task hub, y puedes controlar la velocidad a la que el planificador entrega ese trabajo a los trabajadores. Utiliza colas de tareas para ajustar el ritmo de una carga de trabajo, como un flujo de trabajo de procesamiento por lotes que llama a un servicio downstream limitado por tasa, sin crear un hub de tareas separado.

Para usar una cola de tareas, primero crea un recurso de cola bajo tu centro de tareas. Luego establece la DTS_TaskQueue etiqueta cuando programes una orquestación o actividad. La etiqueta selecciona una cola existente; no crea una.

Note

Las colas de tareas requieren una versión 2026-07-01-preview de la API de gestión o posterior. En los ejemplos de este artículo se usa 2026-07-01-preview. Para el esquema de recursos, consulte la referencia de ARM y Bicep de la cola de tareas.

Cómo funcionan las colas de tareas

Una cola de tareas pertenece a un solo centro de tareas. Su configuración opcional de properties.throughput.actionsPerSecond controla la tasa sostenida de distribución de elementos de trabajo: las entregas de elementos de trabajo del programador a los procesos de trabajo.

  • Los elementos de orquestación y los elementos de trabajo de actividad en la misma cola comparten la tasa configurada.
  • Cada turno de orquestación entregado a un proceso de trabajo cuenta como una distribución de elementos de trabajo. Una orquestación puede requerir varios turnos antes de completarse.
  • Cada elemento de trabajo de actividad entregado a un proceso de trabajo cuenta como una distribución de elementos de trabajo. Los reenvíos también cuentan.
  • Las actividades y suborquestaciones heredan la selección de cola de su padre a menos que la sobreescribas explícitamente con su propia DTS_TaskQueue etiqueta.
  • Los elementos de trabajo de la entidad no usan colas de tareas.

Por ejemplo, actionsPerSecond: 20 configura una tasa sostenida de 20 distribuciones de elementos de trabajo por segundo, compartida por el trabajo de orquestación y de actividad de esa cola. No significa 20 orquestaciones completadas, finalizaciones de actividad o solicitudes de API downstream por segundo. Los ráfagas cortas pueden superar la tasa sostenida, y el rendimiento real puede ser menor debido a la distribución del trabajo, la capacidad del trabajador o la capacidad del planificador.

Si omite la configuración de rendimiento al crear una cola, esta no tendrá ningún límite de tasa específico. Se siguen aplicando los límites de capacidad del programador y de los procesos de trabajo. Las colas de tareas no reservan computación, no proporcionan aislamiento físico ni establecen una prioridad entre colas nombradas. Para límites estrictos de solicitudes downstream, también aplica limitaciones de velocidad donde tu actividad llama al servicio downstream.

Prerequisites

  • Una suscripción a Azure con un scheduler y task hub existentes. Para las ubicaciones del programador, véase regiones admitidas.
  • Permisos para administrar los recursos de cola de tareas del centro de tareas, como los que proporciona el rol de Colaborador heredado del programador o del grupo de recursos. Los roles de plano de datos por sí solos no otorgan permisos de gestión de recursos.
  • CLI de Azure para los az rest ejemplos, o un cliente Azure Resource Manager REST autenticado. Los ejemplos de CLI usan sintaxis Bash y no requieren una extensión CLI dedicada para la cola de tareas.
  • Una aplicación configurada para usar Durable Task Scheduler, con acceso basado en identidad y un SDK que soporta etiquetas. Consulta el soporte del SDK.
  • Procesos de trabajo que se conectan sin filtros de elementos de trabajo. Consulta Configurar trabajadores elegibles.

Configurar procesos de trabajo aptos

Solo las conexiones de trabajadores sin filtros de elementos de trabajo pueden recibir trabajo de colas de tareas definidas. Una conexión de proceso de trabajo con cualquier tipo de filtro, incluidos los filtros con caracteres comodín, no es apta. Asegúrese de que los procesos de trabajo sin filtros registren todas las orquestaciones y actividades que se enrutan a las colas.

El SDK de tareas duraderas .NET genera automáticamente filtros desde su registro de tareas. Desactivar explícitamente el filtrado al configurar un trabajador para las colas de tareas:

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

En los SDKs de Java, Python y Go, no optes por filtrar elementos de trabajo para estos trabajadores. Si tu aplicación ya configura filtros, elimina esa configuración. Para opciones de filtrado específicas del SDK, consulte Habilitar el filtrado de elementos de trabajo.

Importante

El trabajo en una cola definida espera hasta que un trabajador elegible se conecte. No recurre a un proceso de trabajo con filtros como alternativa. Por el contrario, si la cola con nombre no existe o fue eliminada, el trabajo utiliza el enrutamiento normal del hub de tareas y el límite de velocidad de la cola solicitada no se aplica. Crea la cola y espera a que el aprovisionamiento tenga éxito antes de programar el trabajo etiquetado.

Configuración de la CLI de Azure

Inicie sesión y seleccione la suscripción que contiene el programador:

az login
az account set --subscription SUBSCRIPTION_ID

Establezca las siguientes variables de Bash. Sustituya los nombres del grupo de recursos, el programador y el centro de tareas por los de sus recursos existentes. Los ejemplos crean una cola llamada 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"

Crea una cola de tareas

El nombre de la cola debe contener de 3 a 64 letras, números o guiones, que coincidan con ^[a-zA-Z0-9-]{3,64}$. Una cola es un recurso secundario de un centro de tareas; no tiene propiedades propias de location o propiedades tags de recursos de Azure.

Los siguientes ejemplos crean la cola orders con una tasa sostenida de 20 asignaciones de elementos de trabajo por segundo. Establece actionsPerSecond en un entero positivo, o omite throughput para crear una cola sin un límite de tasa específico de cada cola.

Usar az rest para llamar a la API de Azure Resource Manager:

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

Espere a que se complete el aprovisionamiento

Las operaciones de gestión de recursos son asíncronas. Después de crear o actualizar una cola, recupérala y comprueba properties.provisioningState:

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

Repite la consulta hasta que el estado esté Succeeded antes de enviar el trabajo etiquetado. Detente si el estado es Failed, se produce un error o expira el tiempo límite del sondeo. Resuelve el error de gestión de recursos antes de usar la cola. Una solicitud de gestión aceptada por sí sola no significa que la cola esté lista. Para intervalos de sondeo y seguimiento de operaciones, véase Rastrear operaciones asíncronas de Azure.

Compatibilidad con SDK

La selección de cola utiliza etiquetas de orquestación y actividad, no etiquetas de recursos de Azure. La siguiente tabla muestra dónde puedes establecer DTS_TaskQueueexplícitamente .

SDK o extensión Inicia una orquestación Programa una actividad Programar una suborquestación
SDK .NET de tareas duraderas Yes Yes Yes
SDK JavaScript/TypeScript para tareas duraderas Yes Yes Yes
Durable Task Python SDK Yes Yes No
SDK de Durable Task Java (v1.6.0+) Yes No No
SDK de Durable Task Go (beta) Yes Yes Yes
Durable Functions: .NET aislado Yes Yes Yes
Durable Functions: Java Yes No No

Los enlaces de Durable Functions para .NET en proceso, JavaScript y Python no exponen estas opciones de etiquetas explícitas. No asumas que el soporte independiente para el SDK de tareas duraderas de un lenguaje también se aplica a su enlace de Durable Functions. En todos los casos, la conexión del proceso de trabajo también debe cumplir el requisito de procesos de trabajo sin filtros.

Enrutar una orquestación a una cola

Establezca la clave de etiqueta literal DTS_TaskQueue con el nombre de una cola en el mismo centro de tareas. Los siguientes fragmentos asumen que ya configuraste un cliente y registraste tu orquestación. Use la cola orders creada anteriormente.

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

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

Las actividades y las suborquestaciones de la orquestación heredan su selección de cola. No es necesario repetir la etiqueta en cada llamada. Establezca la etiqueta de cola al programar el trabajo; para actualizar la tasa de la cola no es necesario modificar la etiqueta.

Invalidar la cola para una actividad o suborquestación

Para regular de forma independiente el ritmo de un subconjunto de un flujo de trabajo, crea otra cola, como partner-api, y establece explícitamente DTS_TaskQueue en la llamada de actividad o de suborquestación. Espera a que el provisionamiento de esa cola tenga éxito primero.

Por ejemplo, puedes dejar la coordinación de la orquestación en orders y encaminar las llamadas a un servicio posterior a través de partner-api. La invalidación de la actividad selecciona la cola de dicha actividad, pero no mueve la orquestación 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 y actualizar colas

Los siguientes ejemplos de gestión utilizan las variables Bash de Set Up CLI de Azure.

Recuperar la configuración de una cola:

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

Enumerar las colas de un centro de tareas:

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

Actualizar la tasa de distribución de la cola a 10 elementos de trabajo por segundo:

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

Para eliminar el límite de tasa específico de la cola manteniendo la cola, establezca explícitamente throughput en null:

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

Omitir el throughput de una solicitud PATCH deja la tasa existente sin cambios. Una solicitud PUT reemplaza la configuración; si se omite la configuración de rendimiento en PUT, se elimina el límite de tasa específico de la cola. Tras actualizar, espera a que el aprovisionamiento tenga éxito y verifica la configuración devuelta.

Eliminar una cola de tareas

Warning

Al eliminar una cola, se elimina su límite de tasa. El trabajo etiquetado con el nombre de cola eliminado utiliza en su lugar el enrutamiento ordinario del centro de tareas. No uses la eliminación de colas para pausar una carga de trabajo.

Eliminar el recurso de la cola:

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

La eliminación es asincrónica. Sigue la operación asíncrona de Azure Resource Manager hasta el final, o consulta GET con un tiempo de espera hasta que la cola devuelva 404 Not Found. No trates los errores de autorización u otros fallos de solicitud como confirmación de eliminación. Eliminar una cola no termina las orquestaciones que la usaron.

Solucionar problemas de enrutamiento de colas

Si el trabajo en cola no avanza, verifica que la cola existe y que la provisión ha funcionado, la etiqueta identifica la cola prevista en el mismo centro de tareas y un worker operativo se conecta sin filtros. Una cola definida que no tiene procesos de trabajo aptos retiene sus elementos de trabajo en lugar de entregarlos a un proceso de trabajo con filtros.

Si el trabajo se ejecuta sin el límite de tasa esperado, comprueba si falta o se ha eliminado la cola. En ese caso, el planificador utiliza el enrutamiento ordinario del hub de tareas. Tenga en cuenta también los picos breves de actividad y la diferencia entre la distribución de elementos de trabajo y los flujos de trabajo completados. Usa el panel del scheduler para inspeccionar el estado de la orquestación y las etiquetas.