Início rápido: use a filtragem de itens de trabalho com os SDKs de Durable Task

Neste guia de início rápido, você aprenderá a executar um exemplo do SDK Durable Task que usa a filtragem de itens de trabalho para encaminhar orquestrações e atividades a trabalhadores dedicados.

A filtragem de itens de trabalho está atualmente disponível nos SDKs de Tarefas Duráveis .NET, Java e Python. Selecione seu idioma usando as abas no topo da página. Para entender como funciona o filtro de itens de trabalho e como ele possibilita rede plana através de computação heterogênea, veja 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 duradouras em JavaScript e PowerShell. Para tentar esse recurso hoje, selecione a aba C#, Java ou Python no topo da página.

  • Configure e execute o emulador do Agendador de Tarefas Duráveis para desenvolvimento local.
  • Execute os workers do Orquestrador, do Validator e do Expedidor, bem como o cliente.
  • Verifique se os itens de trabalho são encaminhados apenas para os trabalhadores correspondentes.
  • Implante o exemplo nos Aplicativos de Contêiner do Azure usando a CLI do Desenvolvedor do Azure.

Pré-requisitos

Antes de começar:

Preparar o projeto

Azure-Samples/Durable-Task-Scheduler No diretório raiz, navegue até o diretório de exemplo:

cd samples/scenarios/WorkItemFilteringSplitActivities

Executar localmente com o emulador

  1. Baixar a imagem do emulador:

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

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

    dotnet build
    
  4. Execute cada trabalho em um terminal separado:

    Terminal 1 – Trabalho do Orchestrator

    dotnet run --project src/OrchestratorWorker
    

    Terminal 2 – Trabalho do validador

    dotnet run --project src/ValidatorWorker
    

    Terminal 3 – Trabalho do carregador

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

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

Dica

Como alternativa para abrir quatro terminais manualmente, você pode executar o script de conveniência incluído:

./run-local.sh

Ele inicia o emulador, cria a solução e inicia todos os trabalhadores e o cliente.

Saída esperada da filtragem de itens de trabalho

O cliente agenda um lote de três orquestrações a cada 30 segundos e continua repetindo por cerca de 10 minutos. Em todos os terminais, você vê:

  • O cliente agenda lotes de orquestração e espera a conclusão de cada lote. Um lote concluído registra 3 completed, 0 failed.
  • O worker do Orchestrator despacha chamadas de atividade ValidateOrder e ShipOrder.
  • O trabalhador Validador lida apenas ValidateOrder com os itens de trabalho de atividade.
  • O trabalho do Expedidor é tratar apenas com itens de trabalho de atividade ShipOrder.

Esse comportamento confirma que a filtragem de item de trabalho roteia itens apenas para trabalhadores que registraram tipos de tarefa correspondentes.

Quando você vê pelo menos um relatório 3 completed, 0 failedde lote, a amostra está funcionando como esperado. Você não precisa esperar o loop completo terminar – pressione Ctrl+C em cada terminal para parar o cliente e os trabalhadores. Se você deixar o cliente rodar até o final, ele imprime um resumo dos resultados finais e depois permanece ativo até você parar com Ctrl+C.

Experimente: Teste de roteamento rigoroso

Para conferir se o roteamento é restrito (sem fallback para outros trabalhos):

  1. Interrompa o trabalho do Carregador (Ctrl+C no Terminal 3).
  2. Execute o cliente novamente para agendar novas orquestrações.
  3. Observe que:
    • O trabalho Orquestrador seleciona e inicia as orquestrações.
    • O trabalho Validador conclui ValidateOrder para cada ordem.
    • ShipOrder os itens de trabalho permanecem pendentes - os trabalhadores do Validador e do Orquestrador não os recebem.
    • As orquestrações permanecem no status "Em execução", aguardando a conclusão de ShipOrder.
  4. Reinicie o worker do Shipper - os ShipOrder itens de trabalho pendentes são entregues imediatamente e as orquestrações são concluídas.

Este experimento demonstra que os itens de trabalho são direcionados apenas para trabalhadores com filtros correspondentes. Não há opção de recurso.

Implantar usando Azure Developer CLI

  1. Autenticar com Azure (se você ainda não fez):

    azd auth login
    
  2. Do samples/scenarios/WorkItemFilteringSplitActivities, execute:

    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 Azure.
    Localização do Azure A localização do Azure para seus recursos.
    Assinatura do Azure A assinatura do Azure para seus recursos.

O azd up comando provisiona recursos do Azure e implanta quatro serviços em contêineres a partir deste exemplo: cliente, trabalho do orquestrador, trabalho do validador e trabalho de entrega.

Confirmar a implantação bem-sucedida

  1. azd up Na saída, copie o nome do grupo de recursos.

  2. No portal do Azure, abra esse grupo de recursos.

  3. Para cada aplicativo de contêiner implantado (client, orchestrator-worker, validator-worker, shipper-worker), abra Monitoramento>fluxo de Log.

  4. Verifique se cada aplicativo registra apenas seus itens de trabalho esperados:

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

Note

Cada Aplicativo de Contêiner é configurado com uma regra de escala KEDA (azure-durabletask-scheduler) que escala automaticamente os trabalhos de 0 a 10 réplicas com base na lista de pendências dos itens de trabalho. Quando o cliente conclui o loop e não há nenhum item de trabalho restante, os trabalhos são escalados de volta para zero. Para obter mais informações, consulte Dimensionamento automático do Agendador de Tarefas Duráveis no Aplicativos de Contêiner do Azure.

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

A orquestração chama duas atividades em sequência. O agendador direciona cada item de atividade ao trabalhador que o registrou.

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 registra apenas suas tarefas locais. O SDK gera automaticamente filtros de itens de trabalho a partir do registro de tarefas, então você não precisa optar explicitamente por isso.

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, filtros de itens de trabalho são gerados automaticamente a partir do que cada trabalhador registrar. Para sobrescrever os filtros gerados ou optar por não filtrar, chame UseWorkItemFilters(customFilters) ou UseWorkItemFilters(null), respectivamente.

Por exemplo:

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

Quando um trabalhador se conecta ao Agendador de Tarefas Duráveis, o SDK envia sua lista de filtros. O agendador cria filas por filtro e roteia cada item de trabalho para a fila correspondente. Os trabalhadores nunca recebem tipos de item de trabalho que não registraram.

Limpar os recursos

  1. Pare o container local do emulador.

    docker rm -f dts-emulator
    
  2. Se você implantou no Azure, identifique o nome do grupo de recursos:

    • Copie-o a partir da saída azd up.
    • Ou, no portal do Azure, use a caixa de pesquisa global na parte superior e pesquise rg- ou o prefixo do nome do ambiente.
  3. Abra o grupo de recursos nos resultados da pesquisa.

  4. Selecione Excluir grupo de recursos, insira o nome do grupo de recursos a ser confirmado e selecione Excluir.

Próximas Etapas 

  • Configure e execute o emulador do Agendador de Tarefas Duráveis para desenvolvimento local.
  • Execute os workers do Orquestrador, do Validator e do Expedidor, bem como o cliente.
  • Verifique se os itens de trabalho são encaminhados apenas para os trabalhadores correspondentes.
  • Implante o exemplo nos Aplicativos de Contêiner do Azure usando a CLI do Desenvolvedor do Azure.

Pré-requisitos

Antes de começar:

Preparar o projeto

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

cd samples/scenarios/WorkItemFilteringSplitActivitiesJava

Executar localmente com o emulador

  1. Puxe a imagem do emulador.

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

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

    ./gradlew build
    
  4. Execute cada trabalho em um terminal separado:

    Terminal 1 – Trabalho do Orchestrator

    ./gradlew :orchestrator-worker:run
    

    Terminal 2 – Trabalho do validador

    ./gradlew :validator-worker:run
    

    Terminal 3 – Trabalho do carregador

    ./gradlew :shipper-worker:run
    
  5. Em um quarto terminal, execute o cliente.

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

Saída esperada da filtragem de itens de trabalho

O cliente agenda um lote de três orquestrações a cada 30 segundos e continua repetindo por cerca de 10 minutos. Em todos os terminais, você vê:

  • O cliente agenda lotes de orquestração e espera a conclusão de cada lote. Um lote concluído registra 3 completed, 0 failed.
  • O worker do Orchestrator despacha chamadas de atividade ValidateOrder e ShipOrder.
  • O trabalhador Validador lida apenas ValidateOrder com os itens de trabalho de atividade.
  • O trabalho do Expedidor é tratar apenas com itens de trabalho de atividade ShipOrder.

Esse comportamento confirma que a filtragem de item de trabalho roteia itens apenas para trabalhadores que registraram tipos de tarefa correspondentes.

Quando você vê pelo menos um relatório 3 completed, 0 failedde lote, a amostra está funcionando como esperado. Você não precisa esperar o loop completo terminar – pressione Ctrl+C em cada terminal para parar o cliente e os trabalhadores. Se você deixar o cliente rodar até o final, ele imprime um resumo dos resultados finais e depois permanece ativo até você parar com Ctrl+C.

Experimente: Teste de roteamento rigoroso

Para conferir se o roteamento é restrito (sem fallback para outros trabalhos):

  1. Interrompa o trabalho do Carregador (Ctrl+C no Terminal 3).
  2. Execute o cliente novamente para agendar novas orquestrações.
  3. Observe que:
    • O trabalho Orquestrador seleciona e inicia as orquestrações.
    • O trabalho Validador conclui ValidateOrder para cada ordem.
    • ShipOrder os itens de trabalho permanecem pendentes - os trabalhadores do Validador e do Orquestrador não os recebem.
    • As orquestrações permanecem no status "Em execução", aguardando a conclusão de ShipOrder.
  4. Reinicie o worker do Shipper - os ShipOrder itens de trabalho pendentes são entregues imediatamente e as orquestrações são concluídas.

Este experimento demonstra que os itens de trabalho são direcionados apenas para trabalhadores com filtros correspondentes. Não há opção de recurso.

Implantar usando Azure Developer CLI

  1. Autenticar com Azure (se você ainda não fez):

    azd auth login
    
  2. Do samples/scenarios/WorkItemFilteringSplitActivitiesJava, execute:

    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 Azure.
    Localização do Azure A localização do Azure para seus recursos.
    Assinatura do Azure A assinatura do Azure para seus recursos.

O azd up comando provisiona recursos do Azure e implanta quatro serviços em contêineres a partir deste exemplo: cliente, trabalho do orquestrador, trabalho do validador e trabalho de entrega.

Confirmar a implantação bem-sucedida

  1. azd up Na saída, copie o nome do grupo de recursos.

  2. No portal do Azure, abra esse grupo de recursos.

  3. Para cada aplicativo de contêiner implantado (client, orchestrator-worker, validator-worker, shipper-worker), abra Monitoramento>fluxo de Log.

  4. Verifique se cada aplicativo registra apenas seus itens de trabalho esperados:

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

Note

Cada Aplicativo de Contêiner é configurado com uma regra de escala KEDA (azure-durabletask-scheduler) que escala automaticamente os trabalhos de 0 a 10 réplicas com base na lista de pendências dos itens de trabalho. Quando o cliente conclui o loop e não há nenhum item de trabalho restante, os trabalhos são escalados de volta para zero. Para obter mais informações, consulte Dimensionamento automático do Agendador de Tarefas Duráveis no Aplicativos de Contêiner do Azure.

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

A orquestração chama duas atividades em sequência. O agendador direciona cada item de atividade ao trabalhador que o registrou.

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 registra apenas suas tarefas locais e chama useWorkItemFilters() para participar da filtragem. Em seguida, o SDK gera filtros de item de trabalho do registro 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 habilitar a filtragem. Os trabalhadores que não o chamarem receberão todos os tipos de itens de trabalho.

Por exemplo:

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

Quando um trabalhador se conecta ao Agendador de Tarefas Duráveis, o SDK envia sua lista de filtros. O agendador cria filas por filtro e roteia cada item de trabalho para a fila correspondente. Os trabalhadores nunca recebem tipos de item de trabalho que não registraram.

Para fornecer filtros explícitos em vez de gerá-los automaticamente a partir do registro, passe a WorkItemFilter para useWorkItemFilters():

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

builder.useWorkItemFilters(filter);

Limpar os recursos

  1. Pare o container local do emulador.

    docker rm -f dts-emulator
    
  2. Se você implantou no Azure, identifique o nome do grupo de recursos:

    • Copie-o a partir da saída azd up.
    • Ou, no portal do Azure, use a caixa de pesquisa global na parte superior e pesquise rg- ou o prefixo do nome do ambiente.
  3. Abra o grupo de recursos nos resultados da pesquisa.

  4. Selecione Excluir grupo de recursos, insira o nome do grupo de recursos a ser confirmado e selecione Excluir.

Próximas Etapas 

  • Configure e execute o emulador do Agendador de Tarefas Duráveis para desenvolvimento local.
  • Inicie o Worker A, o Worker B e o cliente.
  • Verifique se os itens de trabalho são encaminhados apenas para os trabalhadores correspondentes.

Pré-requisitos

Antes de começar:

Preparar o projeto

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

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

Executar localmente com o emulador

  1. Puxe a imagem do emulador.

    docker pull mcr.microsoft.com/dts/dts-emulator:latest
    
  2. Executar 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 configurações padrão do emulador (endpoint http://localhost:8080 e hub defaultde tarefas), então você não precisa 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 trabalho em um terminal separado:

    Terminal 1 - Operador A (saudação)

    python worker_a.py
    

    Terminal 2 - Trabalhador B (matemática)

    python worker_b.py
    
  6. Em um terceiro terminal, execute o cliente.

    python client.py
    
  7. Abra o painel do emulador em http://localhost:8082 para monitorar 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 então espera que ambas sejam concluídas. Em todos os terminais, você vê:

  • O Worker A processa apenas a orquestração de saudação e a atividade say_hello dela.
  • O trabalhador B processa apenas a orquestração matemática e a atividade add_numbers.
  • O cliente imprime o resultado de cada orquestração.

Esse comportamento confirma que a filtragem de item de trabalho roteia itens apenas para trabalhadores que registraram tipos de tarefa correspondentes.

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

Cada trabalhador registra apenas suas tarefas locais e chama use_work_item_filters() para participar da filtragem. O SDK gera os filtros de itens de trabalho a partir das tarefas registradas.

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 habilitar a filtragem. Os trabalhadores que não o chamarem receberão todos os tipos de itens de trabalho.

Por exemplo:

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

Quando um trabalhador se conecta ao Agendador de Tarefas Duráveis, o SDK envia sua lista de filtros. O agendador cria filas por filtro e roteia cada item de trabalho para a fila correspondente. Os trabalhadores nunca recebem tipos de item de trabalho que não registraram.

Para fornecer filtros explícitos em vez de gerá-los automaticamente a partir do registro, 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"),
    ],
))

Limpar os recursos

Pare o container local do emulador.

docker rm -f dts-emulator

Próximas Etapas