Ajouter des étiquettes aux orchestrations et aux activités dans le planificateur de tâches durables

Les balises sont des paires clé-valeur que vous pouvez attacher à des orchestrations, activités et sous-orchestrations pour ajouter des métadonnées personnalisées. Utilisez des tags pour catégoriser et corréler le travail au fur et à mesure de son exécution. Vous pouvez aussi utiliser des balises d’orchestration pour interroger des instances d’orchestration.

Vous pouvez ajouter des balises à :

• Instances d’orchestration : lorsque vous démarrez une nouvelle orchestration à partir du client.
• Activités : lorsqu’un orchestrateur planifie une activité.
• Sous-orchestrations : lorsqu’un orchestrateur planifie une orchestration enfant.

Prise en charge du SDK et des extensions

Fonctionnement des balises

Lorsque vous planifiez une orchestration, une activité ou une sous-orchestration, vous pouvez fournir un dictionnaire de paires clé-valeur de chaînes sous forme de tags. Le Planificateur de Tâches Durable stocke et expose les tags différemment selon ce que vous identifiez :

• Les balises d’orchestration sont stockées comme métadonnées sur l’instance d’orchestration. Les balises que vous fournissez lors de l’appel d’une sous-orchestration deviennent des métadonnées sur l’instance d’orchestration enfant. Vous pouvez lire ces tags et filtrer les instances d’orchestration par tag.
• Les balises d’activité sont stockées sur l’événement programmé de l’activité dans l’historique d’orchestration parent. Vous pouvez les inspecter dans l’historique d’orchestration, mais ils ne sont pas indexés ni disponibles dans les requêtes des tags d’orchestration. Les balises d’activité ne sont pas non plus transmises à la fonction activité.

Définissez des balises lorsque vous planifiez l’orchestration, l’activité ou la sous-orchestration. Tu ne peux pas changer les tags après.

Définir un nom d’affichage personnalisé

Utilisez le tag bien connu durabletask.displayName pour donner un nom à une orchestration, une sous-orchestration ou une activité destinée aux personnes qui regardent une partie. Lorsque cette balise a une valeur non vide, le tableau de bord Durable Task Scheduler affiche cette valeur partout où il afficherait autrement le nom enregistré, y compris la liste d’orchestration, les vues flux et séquence, ainsi que les panneaux de détails.

Le nom enregistré n’est ni supprimé ni changé. Il reste disponible dans l’infobulle du tableau de bord et dans les détails, et le nom d’affichage personnalisé n’a aucune incidence sur le code exécuté. Si l’étiquette manque ou vide, le tableau de bord affiche le nom enregistré comme d’habitude.

Ajouter des balises à une instance d’orchestration

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

Ajouter des balises à une activité

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

Ajouter des balises à une sous-orchestration

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

Lire les tags d’orchestration

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

Balises de requête

Dans le tableau de bord Durable Task Scheduler, utilisez le filtre Tag pour filtrer les instances d’orchestration par tag d’orchestration. Le filtre correspond à la clé ou à la valeur du tag. La liste d’orchestration affiche également les balises d’orchestration sous forme de colonne.

Les balises d’activité apparaissent dans l’événement programmé de l’activité dans l’historique d’orchestration. Ils ne sont pas inclus dans le filtre Tag de la liste d’orchestration.

Consignes relatives aux balises

• Utilisez des tonalités cohérentes — Suivez une convention de nommage afin de pouvoir filtrer de manière fiable les instances d’orchestration et corréler les activités.
• Conserver les balises significatives : utilisez des valeurs qui fournissent un contexte.
• Utilisez des valeurs de chaîne : les clés et les valeurs sont des chaînes.
• Taille de l’étiquette d’orchestration mentale — Le dictionnaire complet des balises d’orchestration sérialisé en JSON peut atteindre jusqu’à 1 000 octets. Cette limite inclut toutes les clés et valeurs, et les caractères UTF-8 multioctets comptent pour plus d’un octet chacun. Les balises d’activité n’utilisent pas cette limite de métadonnées d’instance d’orchestration, mais elles contribuent à la taille de l’historique d’orchestration.

Limites

• Les balises sont immuables une fois l’orchestration, l’activité ou la sous-orchestration planifiée.
• Les clés et valeurs de balise sont des chaînes.
• Vous pouvez inspecter les balises d’activité dans l’historique d’orchestration, mais vous ne pouvez pas les interroger. Vous ne pouvez pas non plus les transmettre aux fonctions d’activité.

Étapes suivantes

• Développer avec le Durable Task Scheduler
• Données d’orchestration de purge automatique
• Exporter l’historique de l’orchestration