Inicio rápido: Utiliza el filtrado de objetos de trabajo con los SDKs de tareas duraderas

En este inicio rápido, aprenderás a ejecutar un ejemplo del SDK de Durable Task que usa el filtrado de elementos de trabajo para dirigir orquestaciones y actividades a trabajadores dedicados.

El filtrado de elementos de trabajo está disponible actualmente en los SDKs de tareas duraderas de .NET, Java y Python. Selecciona tu idioma usando las pestañas en la parte superior de la página. Para aprender cómo funciona el filtrado de elementos de trabajo y cómo permite redes planas a través de computaciones heterogéneas, consulta Filtrado de elementos de trabajo en el Planificador de Tareas Duradero.

Note

El filtrado de elementos de trabajo aún no está disponible para los SDKs de tareas duraderas de JavaScript y PowerShell. Para probar esta función hoy, selecciona la pestaña C#, Java o Python en la parte superior de la página.

  • Configura y ejecuta el emulador del Durable Task Scheduler para el desarrollo local.
  • Ejecute los trabajadores y el cliente de Orchestrator, Validator y Shipper
  • Compruebe que los elementos de trabajo se enrutan solo a los trabajadores que coinciden.
  • Implemente el ejemplo en Azure Container Apps mediante la CLI para desarrolladores de Azure.

Prerrequisitos

Antes de empezar:

Preparación del proyecto

Desde el Azure-Samples/Durable-Task-Scheduler directorio raíz, navega al directorio de ejemplo.

cd samples/scenarios/WorkItemFilteringSplitActivities

Ejecución local con el emulador

  1. Extraiga la imagen del emulador:

    docker pull mcr.microsoft.com/durable-task/emulator:latest
    
  2. Ejecute el emulador:

    docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/durable-task/emulator:latest
    
  3. Compile la muestra:

    dotnet build
    
  4. Ejecute cada trabajador en un terminal aparte:

    Terminal 1 - trabajador de Orchestrator

    dotnet run --project src/OrchestratorWorker
    

    Terminal 2: trabajo del validador

    dotnet run --project src/ValidatorWorker
    

    Terminal 3: trabajador del cargador

    dotnet run --project src/ShipperWorker
    
  5. En un cuarto terminal, ejecute el cliente:

    dotnet run --project src/Client
    
  6. Abra el panel del emulador en http://localhost:8082 para supervisar la actividad de orquestación.

Tip

Como alternativa a abrir cuatro terminales manualmente, puede ejecutar el script de conveniencia incluido:

./run-local.sh

Inicia el emulador, compila la solución y lanza todos los procesos y el cliente.

Salida esperada del filtrado de elementos de trabajo

El cliente programa un lote de tres orquestaciones cada 30 segundos y sigue repitiendo en bucle durante unos 10 minutos. En todos los terminales verás:

  • El cliente programa lotes de orquestación y espera a que cada lote se complete. Un lote finalizado registra 3 completed, 0 failed.
  • El trabajador Orchestrator envía llamadas de actividad ValidateOrder y ShipOrder.
  • El trabajador Validador solo ValidateOrder gestiona los elementos de trabajo de actividad.
  • El trabajador Shipper solo administra elementos de trabajo de actividad ShipOrder.

Este comportamiento confirma que el filtrado de elementos de trabajo solo enruta los elementos a los trabajadores que están registrados con los tipos de tareas coincidentes.

Si ves al menos un informe de lote 3 completed, 0 failed, la muestra funciona según lo esperado. No tienes que esperar a que termine el bucle completo: pulsa Ctrl+C en cada terminal para detener al cliente y a los trabajadores. Si dejas que el cliente se ejecute hasta el final, imprime un resumen final de los resultados y luego permanece activo hasta que lo detienes con Ctrl+C.

Pruébelo: Experimento de enrutamiento estricto

Para ver que el enrutamiento es estricto (sin desviación a otros trabajadores):

  1. Detenga el trabajo del remitente (Ctrl+C en terminal 3).
  2. Vuelva a ejecutar el cliente para programar nuevas orquestaciones.
  3. Observe que:
    • El trabajo de Orchestrator recoge e inicia orquestaciones.
    • El trabajador del validador completa ValidateOrder para cada pedido.
    • ShipOrder Los elementos de trabajo siguen pendientes - los trabajadores del Validador y el Orquestador no los reciben.
    • Las orquestaciones permanecen en estado "En ejecución", esperando a que ShipOrder se complete.
  4. Reinicia el trabajador Shipper: los trabajos pendientes ShipOrder se entregan inmediatamente y las orquestaciones se completan.

Este experimento demuestra que los elementos de trabajo se envían únicamente a los trabajadores con filtros coincidentes. No hay alternativa.

Implementación mediante la CLI para desarrolladores de Azure

  1. Autentíquese con Azure (si aún no lo ha hecho):

    azd auth login
    
  2. Desde samples/scenarios/WorkItemFilteringSplitActivities, ejecute:

    azd up
    
  3. Cuando se le solicite en el terminal, proporcione los parámetros siguientes:

    Parámetro Descripción
    Nombre del entorno Prefijo del grupo de recursos creado para contener todos los recursos de Azure.
    Ubicación de Azure La ubicación de Azure para tus recursos.
    Suscripción a Azure La suscripción de Azure para tus recursos.

El azd up comando aprovisiona recursos de Azure e implementa cuatro servicios en contenedor de este ejemplo: cliente, trabajo de orquestador, trabajo de validador y trabajo de remitente.

Confirmar la implementación exitosa

  1. En la azd up salida, copie el nombre del grupo de recursos.

  2. En Azure Portal, abra ese grupo de recursos.

  3. Para cada aplicación de contenedor implementada (client, orchestrator-worker, validator-worker, shipper-worker), abra Supervisión>flujo de registros.

  4. Compruebe que cada aplicación registra solo sus elementos de trabajo esperados:

    • orchestrator-worker: trabajo de orquestación.
    • validator-worker: ValidateOrder actividad.
    • shipper-worker: ShipOrder actividad.

Note

Cada aplicación de contenedor se configura con una regla de escalado de KEDA (azure-durabletask-scheduler) que escala automáticamente los trabajadores de 0 a 10 réplicas en función de la cola de elementos de trabajo pendientes. Cuando el cliente finaliza su bucle y no quedan elementos de trabajo, los trabajadores se reducen a cero. Para obtener más información, consulte Escala automática del programador de tareas duraderas en Azure Container Apps.

Entiende el código de filtrado de elementos de trabajo en C #

La orquestación llama a dos actividades de manera secuencial. El programador enruta cada elemento de trabajo de actividad al trabajador que lo haya registrado.

public override async Task<string> RunAsync(TaskOrchestrationContext context, string orderId)
{
    string validationResult = await context.CallActivityAsync<string>("ValidateOrder", orderId);
    string shippingResult = await context.CallActivityAsync<string>("ShipOrder", orderId);

    return $"Order '{orderId}' => Validation: [{validationResult}], Shipping: [{shippingResult}]";
}

Cada trabajador registra solo sus tareas locales. El SDK genera automáticamente filtros de elementos de trabajo desde el registro de tareas, así que no necesitas optar explícitamente por participar.

builder.Services.AddDurableTaskWorker()
    .AddTasks(registry =>
    {
        // Only this worker's tasks are registered.
        // Work item filters are auto-generated from the registry, so this
        // worker only receives matching work items.
        registry.AddAllGeneratedTasks();
    })
    .UseDurableTaskScheduler(connectionString);

Note

En el SDK de tareas duraderas .NET, los filtros de elementos de trabajo se generan automáticamente a partir de lo que cada trabajador registra. Para anular los filtros generados o optar por no filtrar, llama UseWorkItemFilters(customFilters) o UseWorkItemFilters(null), respectivamente.

Por ejemplo:

  • OrchestratorWorker registra OrderProcessingOrchestration.
  • ValidatorWorker registra ValidateOrder.
  • ShipperWorker registra ShipOrder.

Cuando un trabajador se conecta a Durable Task Scheduler, el SDK envía su lista de filtros. El planificador crea colas específicas por filtro y enruta cada elemento de trabajo a la cola correspondiente. Los trabajadores nunca reciben tipos de elementos de trabajo que no se registraron.

Limpieza de recursos

  1. Detener el contenedor local del emulador.

    docker rm -f dts-emulator
    
  2. Si ha implementado en Azure, identifique el nombre del grupo de recursos:

    • Cópielo de la salida de azd up.
    • O bien, en Azure Portal, use el cuadro de búsqueda global en la parte superior y busque rg- o el prefijo del nombre del entorno.
  3. Abra el grupo de recursos desde los resultados de la búsqueda.

  4. Seleccione Eliminar grupo de recursos, escriba el nombre del grupo de recursos para confirmar y, a continuación, seleccione Eliminar.

Pasos siguientes

  • Configura y ejecuta el emulador del Durable Task Scheduler para el desarrollo local.
  • Ejecute los trabajadores y el cliente de Orchestrator, Validator y Shipper
  • Compruebe que los elementos de trabajo se enrutan solo a los trabajadores que coinciden.
  • Implemente el ejemplo en Azure Container Apps mediante la CLI para desarrolladores de Azure.

Prerrequisitos

Antes de empezar:

Preparación del proyecto

Desde el Azure-Samples/Durable-Task-Scheduler directorio raíz, ve al directorio de ejemplo:

cd samples/scenarios/WorkItemFilteringSplitActivitiesJava

Ejecución local con el emulador

  1. Descarga la imagen del emulador.

    docker pull mcr.microsoft.com/dts/dts-emulator:latest
    
  2. Ejecutar el emulador.

    docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest
    
  3. Compile el ejemplo.

    ./gradlew build
    
  4. Ejecute cada trabajador en un terminal aparte:

    Terminal 1 - trabajador de Orchestrator

    ./gradlew :orchestrator-worker:run
    

    Terminal 2: trabajo del validador

    ./gradlew :validator-worker:run
    

    Terminal 3: trabajador del cargador

    ./gradlew :shipper-worker:run
    
  5. En un cuarto terminal, ejecuta el cliente.

    ./gradlew :client:run
    
  6. Abra el panel del emulador en http://localhost:8082 para supervisar la actividad de orquestación.

Salida esperada del filtrado de elementos de trabajo

El cliente programa un lote de tres orquestaciones cada 30 segundos y sigue repitiendo en bucle durante unos 10 minutos. En todos los terminales verás:

  • El cliente programa lotes de orquestación y espera a que cada lote se complete. Un lote finalizado registra 3 completed, 0 failed.
  • El trabajador Orchestrator envía llamadas de actividad ValidateOrder y ShipOrder.
  • El trabajador Validador solo ValidateOrder gestiona los elementos de trabajo de actividad.
  • El trabajador Shipper solo administra elementos de trabajo de actividad ShipOrder.

Este comportamiento confirma que el filtrado de elementos de trabajo solo enruta los elementos a los trabajadores que están registrados con los tipos de tareas coincidentes.

Si ves al menos un informe de lote 3 completed, 0 failed, la muestra funciona según lo esperado. No tienes que esperar a que termine el bucle completo: pulsa Ctrl+C en cada terminal para detener al cliente y a los trabajadores. Si dejas que el cliente se ejecute hasta el final, imprime un resumen final de los resultados y luego permanece activo hasta que lo detienes con Ctrl+C.

Pruébelo: Experimento de enrutamiento estricto

Para ver que el enrutamiento es estricto (sin desviación a otros trabajadores):

  1. Detenga el trabajo del remitente (Ctrl+C en terminal 3).
  2. Vuelva a ejecutar el cliente para programar nuevas orquestaciones.
  3. Observe que:
    • El trabajo de Orchestrator recoge e inicia orquestaciones.
    • El trabajador del validador completa ValidateOrder para cada pedido.
    • ShipOrder Los elementos de trabajo siguen pendientes - los trabajadores del Validador y el Orquestador no los reciben.
    • Las orquestaciones permanecen en estado "En ejecución", esperando a que ShipOrder se complete.
  4. Reinicia el trabajador Shipper: los trabajos pendientes ShipOrder se entregan inmediatamente y las orquestaciones se completan.

Este experimento demuestra que los elementos de trabajo se envían únicamente a los trabajadores con filtros coincidentes. No hay alternativa.

Implementación mediante la CLI para desarrolladores de Azure

  1. Autentíquese con Azure (si aún no lo ha hecho):

    azd auth login
    
  2. Desde samples/scenarios/WorkItemFilteringSplitActivitiesJava, ejecute:

    azd up
    
  3. Cuando se le solicite en el terminal, proporcione los parámetros siguientes:

    Parámetro Descripción
    Nombre del entorno Prefijo del grupo de recursos creado para contener todos los recursos de Azure.
    Ubicación de Azure La ubicación de Azure para tus recursos.
    Suscripción a Azure La suscripción de Azure para tus recursos.

El azd up comando aprovisiona recursos de Azure e implementa cuatro servicios en contenedor de este ejemplo: cliente, trabajo de orquestador, trabajo de validador y trabajo de remitente.

Confirmar la implementación exitosa

  1. En la azd up salida, copie el nombre del grupo de recursos.

  2. En Azure Portal, abra ese grupo de recursos.

  3. Para cada aplicación de contenedor implementada (client, orchestrator-worker, validator-worker, shipper-worker), abra Supervisión>flujo de registros.

  4. Compruebe que cada aplicación registra solo sus elementos de trabajo esperados:

    • orchestrator-worker: trabajo de orquestación.
    • validator-worker: ValidateOrder actividad.
    • shipper-worker: ShipOrder actividad.

Note

Cada aplicación de contenedor se configura con una regla de escalado de KEDA (azure-durabletask-scheduler) que escala automáticamente los trabajadores de 0 a 10 réplicas en función de la cola de elementos de trabajo pendientes. Cuando el cliente finaliza su bucle y no quedan elementos de trabajo, los trabajadores se reducen a cero. Para obtener más información, consulte Escala automática del programador de tareas duraderas en Azure Container Apps.

Entiende el código de filtrado de elementos de trabajo en Java

La orquestación llama a dos actividades de manera secuencial. El programador enruta cada elemento de trabajo de actividad al trabajador que lo haya registrado.

String validationResult = ctx.callActivity("ValidateOrder", orderId, String.class).await();
String shippingResult = ctx.callActivity("ShipOrder", orderId, String.class).await();

String combined = String.format("Order '%s' => Validation: [%s], Shipping: [%s]",
        orderId, validationResult, shippingResult);
ctx.complete(combined);

Cada trabajador registra solo sus tareas locales e invocaciones useWorkItemFilters() para optar por participar en el filtrado. A continuación, el SDK genera filtros de elementos de trabajo desde el registro de tareas.

DurableTaskGrpcWorker worker = DurableTaskSchedulerWorkerExtensions
        .createWorkerBuilder(connectionString)
        .addActivity(new TaskActivityFactory() {
            // ...
        })
        .useWorkItemFilters() // auto-generate from registered tasks
        .build();

Note

Cada trabajador debe llamar useWorkItemFilters() explícitamente para habilitar el filtrado. Los trabajadores que no lo invocan reciben todos los tipos de elementos de trabajo.

Por ejemplo:

  • OrchestratorWorker registra OrderProcessingOrchestration.
  • ValidatorWorker registra ValidateOrder.
  • ShipperWorker registra ShipOrder.

Cuando un trabajador se conecta a Durable Task Scheduler, el SDK envía su lista de filtros. El planificador crea colas específicas por filtro y enruta cada elemento de trabajo a la cola correspondiente. Los trabajadores nunca reciben tipos de elementos de trabajo que no se registraron.

Para suministrar filtros explícitos en lugar de generarlos automáticamente desde el registro, pasa WorkItemFilter a useWorkItemFilters():

WorkItemFilter filter = WorkItemFilter.newBuilder()
        .addOrchestration("OrderProcessingOrchestration")
        .addActivity("ValidateOrder")
        .build();

builder.useWorkItemFilters(filter);

Limpieza de recursos

  1. Detener el contenedor local del emulador.

    docker rm -f dts-emulator
    
  2. Si ha implementado en Azure, identifique el nombre del grupo de recursos:

    • Cópielo de la salida de azd up.
    • O bien, en Azure Portal, use el cuadro de búsqueda global en la parte superior y busque rg- o el prefijo del nombre del entorno.
  3. Abra el grupo de recursos desde los resultados de la búsqueda.

  4. Seleccione Eliminar grupo de recursos, escriba el nombre del grupo de recursos para confirmar y, a continuación, seleccione Eliminar.

Pasos siguientes

  • Configura y ejecuta el emulador del Durable Task Scheduler para el desarrollo local.
  • Ejecuta Worker A, Worker B y el cliente.
  • Compruebe que los elementos de trabajo se enrutan solo a los trabajadores que coinciden.

Prerrequisitos

Antes de empezar:

Preparación del proyecto

Desde el Azure-Samples/Durable-Task-Scheduler directorio raíz, ve al directorio de ejemplo:

cd samples/durable-task-sdks/python/work-item-filtering

Ejecución local con el emulador

  1. Descarga la imagen del emulador.

    docker pull mcr.microsoft.com/dts/dts-emulator:latest
    
  2. Ejecutar el emulador.

    docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest
    

    La muestra usa la configuración predeterminada del emulador (endpoint http://localhost:8080 y task hub default), así que no necesitas establecer ninguna variable de entorno.

  3. (Opcional) Crea y activa un entorno virtual en Python.

    python -m venv venv
    source venv/bin/activate  # On Windows, use: venv\Scripts\activate
    
  4. Instale los paquetes necesarios.

    pip install -r requirements.txt
    
  5. Ejecute cada trabajador en un terminal aparte:

    Terminal 1 - Trabajador A (saludo)

    python worker_a.py
    

    Terminal 2 - Trabajador B (matemáticas)

    python worker_b.py
    
  6. En un tercer terminal, ejecuta el cliente.

    python client.py
    
  7. Abra el panel del emulador en http://localhost:8082 para supervisar la actividad de orquestación.

Salida esperada del filtrado de elementos de trabajo

El cliente programa una orquestación de saludos y una orquestación matemática, y luego espera a que ambas se completen. En todos los terminales verás:

  • El worker A solo procesa la orquestación de bienvenida y la actividad say_hello asociada.
  • El trabajador B procesa únicamente la orquestación matemática y su add_numbers actividad.
  • El cliente imprime el resultado de cada orquestación.

Este comportamiento confirma que el filtrado de elementos de trabajo solo enruta los elementos a los trabajadores que están registrados con los tipos de tareas coincidentes.

Entiende el código de filtrado de elementos de trabajo en Python

Cada trabajador registra solo sus tareas locales e invocaciones use_work_item_filters() para optar por participar en el filtrado. El SDK genera los filtros de elementos de trabajo a partir de las tareas registradas.

worker.add_orchestrator(greeting_orchestrator)
worker.add_activity(say_hello)
worker.use_work_item_filters()  # Auto-generate from the registry

Note

Cada trabajador debe llamar use_work_item_filters() explícitamente para habilitar el filtrado. Los trabajadores que no lo invocan reciben todos los tipos de elementos de trabajo.

Por ejemplo:

  • El trabajador A registra greeting_orchestrator y say_hello.
  • El trabajador B registra math_orchestrator y add_numbers.

Cuando un trabajador se conecta a Durable Task Scheduler, el SDK envía su lista de filtros. El planificador crea colas específicas por filtro y enruta cada elemento de trabajo a la cola correspondiente. Los trabajadores nunca reciben tipos de elementos de trabajo que no se registraron.

Para suministrar filtros explícitos en lugar de generarlos automáticamente desde el registro, pasa WorkItemFilters:

from durabletask.worker import WorkItemFilters, OrchestrationWorkItemFilter, ActivityWorkItemFilter

worker.use_work_item_filters(WorkItemFilters(
    orchestrations=[
        OrchestrationWorkItemFilter(name="greeting_orchestrator"),
    ],
    activities=[
        ActivityWorkItemFilter(name="say_hello"),
    ],
))

Limpieza de recursos

Detener el contenedor local del emulador.

docker rm -f dts-emulator

Pasos siguientes