Início Rápido: Use a filtragem de itens de trabalho com os SDKs de Tarefas Duráveis

Neste guia de início rápido, ficará a saber como executar um exemplo do SDK Durable Task que utiliza a filtragem de itens de trabalho para encaminhar as orquestrações e atividades para trabalhadores dedicados.

A filtragem de itens de trabalho está atualmente disponível nos SDKs de Tarefas Duráveis .NET, Java e Python. Selecione o seu idioma usando os separadores no topo da página. Para saber como funciona a filtragem de itens de trabalho e como esta permite a criação de uma rede plana entre recursos de computação heterogéneos, consulte Filtragem de itens de trabalho no Durable Task Scheduler.

Note

A filtragem de itens de trabalho ainda não está disponível para os SDKs de Tarefas Durables de JavaScript e PowerShell. Para experimentar esta funcionalidade hoje, selecione o separador C#, Java ou Python no topo da página.

  • Configure e execute o emulador do Durable Task Scheduler para desenvolvimento local.
  • Gerir os trabalhadores do Orquestrador, Validador e Remetente, bem como o cliente.
  • Verifique se os itens de trabalho são encaminhados apenas para trabalhadores correspondentes.
  • Implemente o exemplo para Azure Container Apps usando Azure Developer CLI.

Pré-requisitos

Antes de começar:

Preparar o projeto

A partir do Azure-Samples/Durable-Task-Scheduler diretório raiz, navegue até ao diretório de exemplo:

cd samples/scenarios/WorkItemFilteringSplitActivities

Executa localmente com o emulador

  1. Puxa a imagem do emulador:

    docker pull mcr.microsoft.com/durable-task/emulator:latest
    
  2. Executa o emulador:

    docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/durable-task/emulator:latest
    
  3. Crie o exemplo:

    dotnet build
    
  4. Execute cada processo em um terminal separado.

    Terminal 1 - Trabalhador orquestrador

    dotnet run --project src/OrchestratorWorker
    

    Terminal 2 - Operador de validação

    dotnet run --project src/ValidatorWorker
    

    Terminal 3 - Operário expedidor

    dotnet run --project src/ShipperWorker
    
  5. Num quarto terminal, execute o cliente:

    dotnet run --project src/Client
    
  6. Abra o painel do emulador em http://localhost:8082 para monitorizar a atividade de orquestração.

Sugestão

Como alternativa à abertura manual de quatro terminais, pode executar o script de conveniência incluído:

./run-local.sh

Arranca o emulador, constrói a solução e lança todos os trabalhadores e o cliente.

Saída esperada da filtragem de itens de trabalho

O cliente programa um lote de três orquestrações a cada 30 segundos e continua em ciclo durante aproximadamente 10 minutos. Ao longo dos terminais, vê-se:

  • O cliente agenda lotes de orquestração e espera que cada lote seja concluído. Um lote concluído regista 3 completed, 0 failed.
  • O worker do Orchestrator envia ValidateOrder e ShipOrder chamadas de atividade.
  • O trabalhador Validador trata apenas ValidateOrder dos itens de trabalho de atividade.
  • O trabalhador expedidor trata apenas ShipOrder de trabalhos de atividade.

Este comportamento confirma que a filtragem de itens de trabalho encaminha itens apenas para trabalhadores que registaram tipos de tarefas correspondentes.

Quando vê pelo menos um relatório 3 completed, 0 failedde lote, a amostra está a funcionar como esperado. Não tens de esperar que o loop completo termine – carrega em Ctrl+C em cada terminal para parar o cliente e os trabalhadores. Se deixares o cliente correr até ao fim, ele imprime um resumo dos resultados finais e depois mantém-se ativo até o parares com Ctrl+C.

Experimente: Experimento de roteamento rigoroso

Para ver que o encaminhamento é rigoroso (sem recurso a outros trabalhadores):

  1. Parar o trabalhador expedidor (Ctrl+C no Terminal 3).
  2. Execute o cliente novamente para agendar novas orquestrações.
  3. Observe que:
    • O trabalhador do Orquestrador atende e inicia as orquestrações.
    • Trabalhador validador executa ValidateOrder para cada encomenda.
    • ShipOrder os itens de trabalho permanecem pendentes – os trabalhadores do Validador e do Orquestrador não os recebem.
    • As orquestrações mantêm-se em estado "A Correr", à espera de ShipOrder serem concluídas.
  4. Reinicie o worker do Shipper — os itens de trabalho pendentes ShipOrder são entregues imediatamente e as orquestrações ficam concluídas.

Esta experiência demonstra que os itens de trabalho são encaminhados apenas para trabalhadores com filtros correspondentes. Não há alternativa.

Implantar usando a CLI do Azure Developer

  1. Autentique com o Azure (caso ainda não o fez):

    azd auth login
    
  2. De samples/scenarios/WorkItemFilteringSplitActivities, executar:

    azd up
    
  3. Quando solicitado no terminal, forneça os seguintes parâmetros:

    Parâmetro Descrição
    Nome do ambiente Prefixo para o grupo de recursos criado para armazenar todos os recursos do Azure.
    Localização do Azure A localização do Azure para os seus recursos.
    Subscrição do Azure A subscrição do Azure para os teus recursos.

O azd up comando fornece recursos Azure e implementa quatro serviços containerizados a partir deste exemplo: cliente, trabalhador orquestrador, trabalhador validador e trabalhador expedidor.

Confirmar a implantação bem-sucedida

  1. No azd up resultado, copie o nome do grupo de recursos.

  2. No portal Azure, abre esse grupo de recursos.

  3. Para cada aplicação contentor implementada (client, orchestrator-worker, validator-worker, shipper-worker), abre o fluxo de Registo de Monitorização>.

  4. Verifique se cada aplicação regista apenas os seus itens de trabalho esperados:

    • orchestrator-worker: trabalho de orquestração.
    • validator-worker: ValidateOrder atividade.
    • shipper-worker: ShipOrder atividade.

Note

Cada Aplicação Container está configurada com uma regra de escala KEDA (azure-durabletask-scheduler) que escala automaticamente os trabalhadores de 0 a 10 réplicas com base no atraso de itens de trabalho pendentes. Quando o cliente termina o seu ciclo e não restam itens de trabalho, os trabalhadores reduzem para zero. Para mais informações, consulte Dimensionamento automático do Durable Task Scheduler nos Azure Container Apps.

Compreender o código de filtragem de itens de trabalho em C #

A orquestração convoca duas atividades em sequência. O agendador encaminha cada atividade de item de trabalho para o trabalhador que a registou.

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 trabalhador regista apenas as suas tarefas locais. O SDK gera automaticamente filtros de itens de trabalho a partir do registo de tarefas, por isso não precisas de optar explicitamente 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

No .NET Durable Task SDK, os filtros de itens de trabalho são gerados automaticamente a partir do que cada trabalhador regista. Para sobrescrever os filtros gerados ou optar por não filtrar, chame UseWorkItemFilters(customFilters) ou UseWorkItemFilters(null), respetivamente.

Por exemplo:

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

Quando um trabalhador se liga ao Durable Task Scheduler, o SDK envia a sua lista de filtros. O agendador cria filas por filtro e encaminha cada item de trabalho para a fila correspondente. Os trabalhadores nunca recebem tipos de itens de trabalho que não registaram.

Limpeza de recursos

  1. Interrompa o contentor do emulador local.

    docker rm -f dts-emulator
    
  2. Se implementou para o Azure, identifique o nome do grupo de recursos:

    • Copia a partir da azd up saída.
    • Ou, no portal Azure, usa a caixa de pesquisa global no topo e procura o rg- prefixo do nome do teu ambiente.
  3. Abra o grupo de recursos a partir dos resultados de pesquisa.

  4. Selecione Eliminar grupo de recursos, introduza o nome do grupo para confirmar e depois selecione Eliminar.

Passos seguintes

  • Configure e execute o emulador do Durable Task Scheduler para desenvolvimento local.
  • Gerir os trabalhadores do Orquestrador, Validador e Remetente, bem como o cliente.
  • Verifique se os itens de trabalho são encaminhados apenas para trabalhadores correspondentes.
  • Implemente o exemplo para Azure Container Apps usando Azure Developer CLI.

Pré-requisitos

Antes de começar:

Preparar o projeto

Do Azure-Samples/Durable-Task-Scheduler diretório raiz, vá ao diretório de exemplo:

cd samples/scenarios/WorkItemFilteringSplitActivitiesJava

Executa localmente com o emulador

  1. Puxa a imagem do emulador.

    docker pull mcr.microsoft.com/dts/dts-emulator:latest
    
  2. Execute o emulador.

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

    ./gradlew build
    
  4. Execute cada processo em um terminal separado.

    Terminal 1 - Trabalhador orquestrador

    ./gradlew :orchestrator-worker:run
    

    Terminal 2 - Operador de validação

    ./gradlew :validator-worker:run
    

    Terminal 3 - Operário expedidor

    ./gradlew :shipper-worker:run
    
  5. Num quarto terminal, executa o cliente.

    ./gradlew :client:run
    
  6. Abra o painel do emulador em http://localhost:8082 para monitorizar a atividade de orquestração.

Saída esperada da filtragem de itens de trabalho

O cliente programa um lote de três orquestrações a cada 30 segundos e continua em ciclo durante aproximadamente 10 minutos. Ao longo dos terminais, vê-se:

  • O cliente agenda lotes de orquestração e espera que cada lote seja concluído. Um lote concluído regista 3 completed, 0 failed.
  • O worker do Orchestrator envia ValidateOrder e ShipOrder chamadas de atividade.
  • O trabalhador Validador trata apenas ValidateOrder dos itens de trabalho de atividade.
  • O trabalhador expedidor trata apenas ShipOrder de trabalhos de atividade.

Este comportamento confirma que a filtragem de itens de trabalho encaminha itens apenas para trabalhadores que registaram tipos de tarefas correspondentes.

Quando vê pelo menos um relatório 3 completed, 0 failedde lote, a amostra está a funcionar como esperado. Não tens de esperar que o loop completo termine – carrega em Ctrl+C em cada terminal para parar o cliente e os trabalhadores. Se deixares o cliente correr até ao fim, ele imprime um resumo dos resultados finais e depois mantém-se ativo até o parares com Ctrl+C.

Experimente: Experimento de roteamento rigoroso

Para ver que o encaminhamento é rigoroso (sem recurso a outros trabalhadores):

  1. Parar o trabalhador expedidor (Ctrl+C no Terminal 3).
  2. Execute o cliente novamente para agendar novas orquestrações.
  3. Observe que:
    • O trabalhador do Orquestrador atende e inicia as orquestrações.
    • Trabalhador validador executa ValidateOrder para cada encomenda.
    • ShipOrder os itens de trabalho permanecem pendentes – os trabalhadores do Validador e do Orquestrador não os recebem.
    • As orquestrações mantêm-se em estado "A Correr", à espera de ShipOrder serem concluídas.
  4. Reinicie o worker do Shipper — os itens de trabalho pendentes ShipOrder são entregues imediatamente e as orquestrações ficam concluídas.

Esta experiência demonstra que os itens de trabalho são encaminhados apenas para trabalhadores com filtros correspondentes. Não há alternativa.

Implantar usando a CLI do Azure Developer

  1. Autentique com o Azure (caso ainda não o fez):

    azd auth login
    
  2. De samples/scenarios/WorkItemFilteringSplitActivitiesJava, executar:

    azd up
    
  3. Quando solicitado no terminal, forneça os seguintes parâmetros:

    Parâmetro Descrição
    Nome do ambiente Prefixo para o grupo de recursos criado para armazenar todos os recursos do Azure.
    Localização do Azure A localização do Azure para os seus recursos.
    Subscrição do Azure A subscrição do Azure para os teus recursos.

O azd up comando fornece recursos Azure e implementa quatro serviços containerizados a partir deste exemplo: cliente, trabalhador orquestrador, trabalhador validador e trabalhador expedidor.

Confirmar a implantação bem-sucedida

  1. No azd up resultado, copie o nome do grupo de recursos.

  2. No portal Azure, abre esse grupo de recursos.

  3. Para cada aplicação contentor implementada (client, orchestrator-worker, validator-worker, shipper-worker), abre o fluxo de Registo de Monitorização>.

  4. Verifique se cada aplicação regista apenas os seus itens de trabalho esperados:

    • orchestrator-worker: trabalho de orquestração.
    • validator-worker: ValidateOrder atividade.
    • shipper-worker: ShipOrder atividade.

Note

Cada Aplicação Container está configurada com uma regra de escala KEDA (azure-durabletask-scheduler) que escala automaticamente os trabalhadores de 0 a 10 réplicas com base no atraso de itens de trabalho pendentes. Quando o cliente termina o seu ciclo e não restam itens de trabalho, os trabalhadores reduzem para zero. Para mais informações, consulte Dimensionamento automático do Durable Task Scheduler nos Azure Container Apps.

Compreender o código de filtragem de itens de trabalho em Java

A orquestração convoca duas atividades em sequência. O agendador encaminha cada atividade de item de trabalho para o trabalhador que a registou.

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 trabalhador regista apenas as suas tarefas locais e chama useWorkItemFilters() para aderir à filtragem. O SDK gera então filtros de itens de trabalho a partir do registo de tarefas.

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

Note

Cada trabalhador deve chamar useWorkItemFilters() explicitamente para permitir a filtragem. Os workers que não a invocam recebem todos os tipos de itens de trabalho.

Por exemplo:

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

Quando um trabalhador se liga ao Durable Task Scheduler, o SDK envia a sua lista de filtros. O agendador cria filas por filtro e encaminha cada item de trabalho para a fila correspondente. Os trabalhadores nunca recebem tipos de itens de trabalho que não registaram.

Para fornecer filtros explícitos em vez de os gerar automaticamente a partir do registo, passa a WorkItemFilter para useWorkItemFilters():

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

builder.useWorkItemFilters(filter);

Limpeza de recursos

  1. Interrompa o contentor do emulador local.

    docker rm -f dts-emulator
    
  2. Se implementou para o Azure, identifique o nome do grupo de recursos:

    • Copia a partir da azd up saída.
    • Ou, no portal Azure, usa a caixa de pesquisa global no topo e procura o rg- prefixo do nome do teu ambiente.
  3. Abra o grupo de recursos a partir dos resultados de pesquisa.

  4. Selecione Eliminar grupo de recursos, introduza o nome do grupo para confirmar e depois selecione Eliminar.

Passos seguintes

  • Configure e execute o emulador do Durable Task Scheduler para desenvolvimento local.
  • Executa o Trabalhador A, o Trabalhador B e o cliente.
  • Verifique se os itens de trabalho são encaminhados apenas para trabalhadores correspondentes.

Pré-requisitos

Antes de começar:

Preparar o projeto

Do Azure-Samples/Durable-Task-Scheduler diretório raiz, vá ao diretório de exemplo:

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

Executa localmente com o emulador

  1. Puxa a imagem do emulador.

    docker pull mcr.microsoft.com/dts/dts-emulator:latest
    
  2. Execute o emulador.

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

    O exemplo usa as definições padrão do emulador (endpoint http://localhost:8080 e hub defaultde tarefas), por isso não precisas de definir variáveis de ambiente.

  3. (Opcional) Crie e ative um ambiente virtual em Python.

    python -m venv venv
    source venv/bin/activate  # On Windows, use: venv\Scripts\activate
    
  4. Instale os pacotes necessários.

    pip install -r requirements.txt
    
  5. Execute cada processo em um terminal separado.

    Terminal 1 - Trabalhador A (saudação)

    python worker_a.py
    

    Terminal 2 - Trabalhador B (matemática)

    python worker_b.py
    
  6. Num terceiro terminal, executa o cliente.

    python client.py
    
  7. Abra o painel do emulador em http://localhost:8082 para monitorizar a atividade de orquestração.

Saída esperada da filtragem de itens de trabalho

O cliente agenda uma orquestração de saudação e uma orquestração matemática, e depois espera que ambas sejam concluídas. Ao longo dos terminais, vê-se:

  • O worker A processa apenas a orquestração de saudação e a respetiva atividade say_hello.
  • O Worker B processa apenas a orquestração de cálculos e a respetiva atividade add_numbers.
  • O cliente imprime o resultado de cada orquestração.

Este comportamento confirma que a filtragem de itens de trabalho encaminha itens apenas para trabalhadores que registaram tipos de tarefas correspondentes.

Compreender o código de filtragem de itens de trabalho em Python

Cada trabalhador regista apenas as suas tarefas locais e chama use_work_item_filters() para aderir à filtragem. O SDK gera os filtros de itens de trabalho a partir das tarefas registadas.

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

Note

Cada trabalhador deve chamar use_work_item_filters() explicitamente para permitir a filtragem. Os workers que não a invocam recebem todos os tipos de itens de trabalho.

Por exemplo:

  • O Trabalhador A regista greeting_orchestrator e say_hello.
  • O Trabalhador B regista math_orchestrator e add_numbers.

Quando um trabalhador se liga ao Durable Task Scheduler, o SDK envia a sua lista de filtros. O agendador cria filas por filtro e encaminha cada item de trabalho para a fila correspondente. Os trabalhadores nunca recebem tipos de itens de trabalho que não registaram.

Para fornecer filtros explícitos em vez de os gerar automaticamente a partir do registo, passe WorkItemFilters:

from durabletask.worker import WorkItemFilters, OrchestrationWorkItemFilter, ActivityWorkItemFilter

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

Limpeza de recursos

Interrompa o contentor do emulador local.

docker rm -f dts-emulator

Passos seguintes