Adicionar marcadores a orquestrações e atividades no Durable Task Scheduler

Tags são pares de chave-valor que você pode associar a orquestrações, atividades e suborquestrações para adicionar metadados personalizados. Use tags para categorizar e correlacionar o trabalho enquanto ele é executado. Você também pode usar tags de orquestração para consultar instâncias de orquestração.

Você pode adicionar etiquetas a:

Instâncias de orquestração: quando você inicia uma nova orquestração do cliente.
Atividades – quando um orquestrador agenda uma atividade.
Suborquestrações: quando um orquestrador agenda uma orquestração filha.

Suporte a SDKs e extensões

SDK/Extensão	Tags de orquestração	Tags de atividade	Marcações de suborquestração	Leia tags de orquestração
SDK do .NET de Tarefa Durável (`durabletask-dotnet`)	✅	✅	✅	✅
SDK de JavaScript do Durable Task (`durabletask-js`)	✅	✅	✅	✅
SDK do Python para Durable Task (`durabletask-python`)	✅	✅	❌	❌ (não exibido em `OrchestrationState`)
SDK do Java de Tarefa Durável (`durabletask-java`)	✅ (v1.6.0+)	❌ (`TaskOptions` é apenas para repetição)	❌	✅
Durable Functions: .NET isolado	✅	✅	✅	✅
Durable Functions: em processo do .NET	❌	❌	❌	❌
Durable Functions: JavaScript	❌	❌	❌	❌
Durable Functions: Python	❌	❌	❌	❌
Durable Functions: Java	✅	❌	❌	✅

Como as etiquetas funcionam

Quando agendar uma orquestração, atividade ou suborquestração, você pode fornecer um dicionário de pares de chave-valor de cadeia de caracteres como marcações. O Durable Task Scheduler armazena e expõe as tags de forma diferente dependendo do que você etiqueta:

As tags de orquestração são armazenadas como metadados na instância de orquestração. As marcações que você fornece quando chama uma suborquestração tornam-se metadados da instância filho da orquestração. Você pode ler essas tags e filtrar as instâncias de orquestração por tag.
As marcações de atividade são armazenadas no evento programado da atividade no histórico de orquestração pai. Você pode inspecioná-las no histórico de orquestração, mas elas não estão indexadas nem disponíveis nas consultas de tags de orquestração. As etiquetas de atividade também não são transmitidas para a função de atividade.

Defina tags ao agendar a orquestração, a atividade ou a suborquestração. Você não pode mudar as tags depois.

Defina um nome de exibição personalizado

Use a conhecida marcação durabletask.displayName para dar a uma orquestração, suborquestração ou atividade um nome destinado às pessoas que que vejam uma execução. Quando essa marcação tem um valor não vazio, o painel do agendador de tarefas duráveis mostra esse valor em todos os lugares em que, de outra forma, mostraria o nome registrado, incluindo a lista de orquestrações, os modos de exibição de fluxo e de sequência e os painéis de detalhes.

O nome registrado não é descartado nem alterado. Ele permanece disponível no tooltip e nos detalhes do painel, e o nome de exibição personalizado não afeta o código executado. Se a tag estiver faltando ou vazia, o painel mostra o nome registrado normalmente.

Importante

O durabletask. prefixo é reservado para a plataforma. O painel esconde tags cujas chaves começam durabletask. com a lista normal de tags, então tags de plataforma, como durabletask.displayName, não aparecem tanto como metadados interpretados quanto como tags brutas. Não crie suas próprias chaves de tag com o prefixo durabletask..

Adicionar tags a uma instância de orquestração

var options = new StartOrchestrationOptions
{
    InstanceId = "order-12345",
    Tags = new Dictionary<string, string>
    {
        { "environment", "production" },
        { "tenant", "contoso" },
    },
};

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

const instanceId = await client.scheduleNewOrchestration(
    "ProcessOrderOrchestration",
    order,
    {
        instanceId: "order-12345",
        tags: {
            environment: "production",
            tenant: "contoso",
        },
    }
);

instance_id = client.schedule_new_orchestration(
    "process_order_orchestration",
    input=order,
    instance_id="order-12345",
    tags={
        "environment": "production",
        "tenant": "contoso",
    },
)

NewOrchestrationInstanceOptions options = new NewOrchestrationInstanceOptions()
    .setInstanceId("order-12345")
    .setTags(Map.of(
        "environment", "production",
        "tenant", "contoso"
    ));

String instanceId = client.scheduleNewOrchestrationInstance(
    "ProcessOrderOrchestration", order, options);

Adicionar etiquetas a uma atividade

var options = new TaskOptions(tags: new Dictionary<string, string>
{
    { "scheduleId", scheduleId },
});

await context.CallActivityAsync(nameof(CacheClearingActivity), options);

const result: string = yield ctx.callActivity(
    cacheClearingActivity,
    input,
    {
        tags: {
            scheduleId: scheduleId,
        },
    }
);

result = yield ctx.call_activity(
    "cache_clearing_activity",
    input=input_data,
    tags={
        "scheduleId": schedule_id,
    },
)

Adicionar marcas a uma sub-orquestração

var options = new SubOrchestrationOptions
{
    Tags = new Dictionary<string, string>
    {
        { "workflowType", "order-processing" },
    },
};

await context.CallSubOrchestratorAsync(
    "ValidateOrderOrchestration", input: order, options: options);

const result = yield ctx.callSubOrchestrator(
    validateOrderOrchestration,
    order,
    {
        tags: {
            workflowType: "order-processing",
        },
    }
);

Leia tags de orquestração

OrchestrationMetadata? instance = await client.GetInstanceAsync(instanceId);

if (instance is not null)
{
    foreach (KeyValuePair<string, string> tag in instance.Tags)
    {
        Console.WriteLine($"{tag.Key} = {tag.Value}");
    }
}

const state = await client.getOrchestrationState(instanceId);

if (state) {
    for (const [key, value] of Object.entries(state.tags)) {
        console.log(`${key} = ${value}`);
    }
}

OrchestrationMetadata metadata = client.getInstanceMetadata(instanceId, false);

if (metadata != null) {
    Map<String, String> tags = metadata.getTags();
    for (Map.Entry<String, String> tag : tags.entrySet()) {
        System.out.println(tag.getKey() + " = " + tag.getValue());
    }
}

Etiquetas de consulta

No painel do agendador de tarefas duráveis, use o filtro Marcação para filtrar as instâncias de orquestração por marcação de orquestração. O filtro corresponde à chave ou valor da marcação. A lista de orquestração também mostra as etiquetas de orquestração em uma coluna.

As marcações de atividade aparecem no evento agendado da atividade no histórico de orquestração. Elas não estão incluídas no filtro por tag da lista de orquestração.

Captura de tela do painel do Durable Task Scheduler mostrando o filtro de tag e a coluna de tags na lista de orquestrações.

Diretrizes para tags

Use chaves consistentes – Siga uma convenção de nomes para poder filtrar as instâncias de orquestração e correlacionar as atividades de forma confiável.
Mantenha tags significativas — Use valores que forneçam contexto.
Usar valores de cadeia de caracteres — chaves e valores são cadeias de caracteres.
Tamanho da tag de orquestração mental — O dicionário completo de tags de orquestração serializado em JSON pode ter até 1.000 bytes. Esse limite inclui todas as chaves e valores, e caracteres UTF-8 de múltiplos bytes contam como mais de um byte cada. As tags de atividades não usam esse limite de metadados da instância de orquestração, mas contribuem para o tamanho do histórico da orquestração.

Limitações

As marcações são imutáveis após a orquestração, atividade ou suborquestração ser agendada.
Chaves de marca e valores são cadeias de caracteres.
Você pode inspecionar as tags de atividade no histórico de orquestração, mas não pode consultá-las. Você também não pode passá-las para funções de atividade.

Próximas Etapas

Gerenciamento de instância

Comentários

Esta página foi útil?

Last updated on 2026-08-04