Adicionar Etiquetas a Orquestrações e Atividades no Durable Task Scheduler

As etiquetas são pares de chave-valor que podem ser anexados a orquestrações, atividades e suborquestrações para adicionar metadados personalizados. Use etiquetas para categorizar e correlacionar o trabalho à medida que é executado. Também pode usar etiquetas de orquestração para consultar instâncias de orquestração.

Pode adicionar etiquetas a:

• Instâncias de orquestração — quando inicias uma nova orquestração a partir do cliente.
• Atividades — quando um orquestrador agenda uma atividade.
• Sub-orquestrações — quando um orquestrador agenda uma orquestração infantil.

Suporte a SDK e extensões

Como funcionam as tags

Quando agendas uma orquestração, atividade ou suborquestração, podes fornecer um dicionário de pares chave-valor de cordas como etiquetas. O Durable Task Scheduler armazena e expõe as etiquetas de forma diferente dependendo do que etiquetas:

• As etiquetas de orquestração são armazenadas como metadados na instância de orquestração. As etiquetas que fornece ao chamar uma suborquestração tornam-se metadados na instância de orquestração filha. Pode ler estas etiquetas e filtrar as instâncias de orquestração por etiqueta.
• As etiquetas de atividade são armazenadas no evento agendado da atividade no histórico de orquestração principal. Podes inspecioná-los no histórico de orquestração, mas não estão indexados nem disponíveis nas consultas de etiquetas de orquestração. As etiquetas de atividade também não são passadas para a função de atividade.

Defina etiquetas ao agendar a orquestração, a atividade ou a suborquestração. Não podes mudar as etiquetas depois.

Defina um nome de exibição personalizado

Use a conhecida durabletask.displayName etiqueta para dar a uma orquestração, suborquestração ou atividade um nome destinado a pessoas que assistem a uma execução. Quando esta tag tem um valor não vazio, o painel do Durable Task Scheduler mostra esse valor em qualquer local onde, de outra forma, mostraria o nome registado, incluindo na lista de orquestrações, nas vistas de fluxo e de sequência e nos painéis de detalhes.

O nome registado não é descartado nem alterado. Continua disponível na dica de ferramentas do painel e nos detalhes, e o nome de visualização personalizado não afeta o código executado. Se a etiqueta estiver em falta ou vazia, o painel mostra o nome registado como habitual.

Adicionar etiquetas 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 etiquetas a uma suborquestraçã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",
        },
    }
);

Ler etiquetas 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());
    }
}

Tags de consulta

No painel do Durable Task Scheduler, utilize o filtro de Etiqueta para filtrar instâncias de orquestração por etiqueta de orquestração. O filtro corresponde à chave ou valor da etiqueta. A lista de orquestração também mostra os marcadores de orquestração numa coluna.

As etiquetas de atividade aparecem no evento agendado da atividade no histórico de orquestração. Elas não estão incluídas no filtro de Etiquetas da lista de orquestração.

Diretrizes para etiquetas

• Use chaves consistentes — Siga uma convenção de nomenclatura para poder filtrar as instâncias de orquestração de modo fiável e correlacionar atividades.
• Mantenha as etiquetas significativas — Use valores que forneçam contexto.
• Use valores de cadeias — Chaves e valores são cadeias.
• Tamanho da etiqueta de orquestração mental — O dicionário completo de etiquetas de orquestração serializado em JSON pode ter até 1.000 bytes. Este limite inclui todas as chaves e valores, e os caracteres UTF-8 de múltiplos bytes contam como mais de um byte cada. As tags de atividade não estão sujeitas a este limite de metadados da instância de orquestração, mas contribuem para o tamanho do histórico de orquestração.

Limitações

• As etiquetas são imutáveis depois de a orquestração, a atividade ou a suborquestração serem programadas.
• As chaves e os valores das tags são cadeias de caracteres.
• Podes inspecionar as etiquetas de atividade no histórico de orquestração, mas não as podes consultar. Também não podes passá-los para funções de atividade.

Passos seguintes

• Desenvolva com o Durable Task Scheduler
• Dados de orquestração com purga automática
• Histórico de orquestração de exportação