Agregar etiquetas a orquestaciones y actividades en el programador de tareas durables

Las etiquetas son pares clave-valor que puedes adjuntar a orquestaciones, actividades y suborquestaciones para añadir metadatos personalizados. Usa etiquetas para categorizar y correlacionar el trabajo mientras se ejecuta. También puedes usar etiquetas de orquestación para consultar instancias de orquestación.

Puede agregar etiquetas a:

• Instancias de orquestación : al iniciar una nueva orquestación desde el cliente.
• Actividades : cuando un orquestador programa una actividad.
• Suborquestaciones — cuando un orquestador inicia una orquestación secundaria.

Compatibilidad con el SDK y las extensiones

Funcionamiento de las etiquetas

Al programar una orquestación, una actividad o una suborquestación, puedes proporcionar un diccionario de pares clave-valor de tipo cadena como etiquetas. El Planificador de Tareas Duradero almacena y expone las etiquetas de forma diferente según lo que etiquetes:

• Las etiquetas de orquestación se almacenan como metadatos en la instancia de orquestación. Las etiquetas que proporciones al llamar a una suborquestación se convierten en metadatos de la instancia de orquestación secundaria. Puedes leer estas etiquetas y filtrar instancias de orquestación por etiqueta.
• Las etiquetas de actividad se almacenan en el evento programado de la actividad en el historial de orquestación principal. Puedes inspeccionarlas en el historial de orquestación, pero no están indexadas ni disponibles en consultas de etiquetas de orquestación. Las etiquetas de actividad tampoco se pasan a la función de actividad.

Establece etiquetas al programar la orquestación, la actividad o la suborquestación. No puedes cambiar las etiquetas después.

Establecer un nombre de visualización personalizado

Utiliza la conocida etiqueta durabletask.displayName para asignar a una orquestación, suborquestación o actividad un nombre destinado a las personas que visualizan una ejecución. Cuando esta etiqueta tiene un valor no vacío, el panel del Programador de tareas durables muestra ese valor en cualquier lugar donde, de otro modo, se mostraría el nombre registrado, incluida la lista de orquestaciones, las vistas de flujo y de secuencia, y los paneles de detalles.

El nombre registrado no se descarta ni se cambia. Este nombre permanece disponible en la información sobre herramientas y en los detalles del panel de control, y el nombre de visualización personalizado no afecta al código que se ejecuta. Si la etiqueta falta o está vacía, el panel muestra el nombre registrado como siempre.

Adición de etiquetas a una instancia de orquestación

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);

Adición de etiquetas a una actividad

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,
    },
)

Adición de etiquetas a una suborquestación

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",
        },
    }
);

Leer etiquetas de orquestación

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 búsqueda

En el panel de control de Durable Task Scheduler, utiliza el filtro Tag para filtrar instancias de orquestación por etiqueta de orquestación. El filtro se aplica según la clave o el valor de la etiqueta. La lista de orquestación también muestra las etiquetas de orquestación en una columna.

Las etiquetas de actividad aparecen en el evento programado de la actividad en el historial de la orquestación. No están incluidos en el filtro de etiquetas de la lista de orquestación.

Directrices de etiquetas

• Usa teclas consistentes — Sigue una convención de nombres para poder filtrar de forma fiable instancias de orquestación y correlacionar actividades.
• Mantener las etiquetas significativas : use valores que proporcionen contexto.
• Usar valores de cadena : las claves y los valores son cadenas.
• Tamaño de la etiqueta de orquestación mental — El diccionario completo de etiquetas de orquestación serializado en JSON puede tener hasta 1.000 bytes. Este límite incluye todas las claves y valores, y los caracteres UTF-8 de varios bytes cuentan como más de un byte cada uno. Las etiquetas de actividad no usan este límite de metadatos de instancias de orquestación, pero contribuyen al tamaño del historial de orquestación.

Limitaciones

• Las etiquetas son inmutables una vez programada la orquestación, la actividad o la suborquestación.
• Las claves de etiqueta y los valores son cadenas.
• Puedes inspeccionar las etiquetas de actividad en el historial de orquestación, pero no puedes consultarlas. Tampoco puedes pasarlos a funciones de actividad.

Pasos siguientes

• Desarrollo con Durable Task Scheduler
• Purgado automático de datos de orquestación
• Exportar historial de orquestación