在 Durable Task Scheduler 中為編排與活動新增標籤

標籤是可以附加在編排、活動和子編排上的鍵值對，以加入自訂的元資料。在工作進行時，使用標籤來分類並關聯。你也可以用編排標籤來查詢編排實例。

你可以在以下平台新增標籤：

編排實例 ——當你從客戶端開始新的編排時。
活動 — 當協調器排程活動時。
子流程協調 — 當流程協調排程子系流程協調時。

SDK 與擴充套件支援

SDK 與擴充功能	協調標籤	活動標籤	子編曲標籤	閱讀編排標籤
Durable Task .NET SDK （`durabletask-dotnet`）	✅	✅	✅	✅
Durable Task JavaScript SDK （`durabletask-js`）	✅	✅	✅	✅
Durable Task Python SDK （`durabletask-python`）	✅	✅	❌	❌ （未顯示於 `OrchestrationState`）
Durable Task Java SDK （`durabletask-java`）	✅ （v1.6.0+）	❌（`TaskOptions` 僅供重試）	❌	✅
Durable Functions：.NET 隔離式方案	✅	✅	✅	✅
Durable Functions：.NET 進行中	❌	❌	❌	❌
Durable Functions：JavaScript	❌	❌	❌	❌
Durable Functions：Python	❌	❌	❌	❌
Durable Functions：Java	✅	❌	❌	✅

標籤的運作方式

當你排程編排、活動或子編曲時，你可以提供字串鍵值對的字典作為標籤。耐用任務排程器會根據你標記的標籤類型，以不同的方式儲存和暴露標籤：

編排標籤 會以中繼資料的形式儲存在編排實例上。你在呼叫子編排時提供的標籤會成為子調度實例的元資料。你可以閱讀這些標籤，並依標籤篩選編排實例。
活動標籤 會儲存在該活動排程事件的父程式編排歷史中。你可以在協調流程歷程記錄中查看它們，但它們不會被建立索引，也無法在協調流程標籤查詢中查詢到。活動標籤也不會傳遞給活動函式。

在排程編排、活動或子編曲時設定標籤。之後你不能再更改標籤。

設定自訂顯示名稱

使用眾所周知的 durabletask.displayName 標籤，為協調流程、子協調流程或活動指定一個名稱，供檢視執行情形的人員查看。當該標籤值非空時，Durable Task Scheduler 儀表板會在原本會顯示註冊名稱的地方顯示該值，包括協調清單、流程與序列視圖，以及詳細面板。

註冊名稱不會被丟棄或更改。它仍然存在儀表板工具提示和細節中，且自訂顯示名稱不會影響執行的程式碼。如果標籤遺失或空，儀表板會照常顯示註冊名稱。

Important

durabletask. 前綴為平台保留。儀表板會將鍵以開 durabletask. 頭的標籤從一般標籤列表中隱藏，因此平台標籤（如 durabletask.displayName，）不會同時以解譯元資料或原始標籤的形式出現。不要在 durabletask. 前綴下自行建立標籤鍵。

在編排實例中新增標籤

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

為活動新增標籤

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

新增標籤到子流程協調

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

閱讀編排標籤

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

查詢標籤

在 Durable Task Scheduler 儀表板中，使用 Tag 篩選 器，依照編排標籤篩選編排實例。篩選器會比對標籤鍵或值。編排清單也會以欄位顯示編排標籤。

活動標籤會出現在該活動排程事件的編排歷史中。它們不包含在編排清單的 標籤過濾器中。

Durable Task Scheduler 儀表板的截圖，顯示編排清單中標籤過濾器和標籤欄位。

標籤指引

使用一致的鍵—— 遵循命名慣例，以便可靠地過濾編排實例並關聯活動。
保持標籤有意義 — 使用能提供上下文的價值。
使用字串值 — 鍵值和值就是字串。
Mind 協調標籤大小 — 完整的 JSON 序列化協調標籤字典大小最多可達 1,000 位元組。此限制包含所有鍵和值，且每個多位元組 UTF-8 字元會計為一個以上的位元組。活動標籤不使用這個協調實例的元資料限制，但它們會增加編排歷史大小。

Limitations

在已排定編排、活動或子編排之後，標籤即不可變更。
標籤鍵和值是字串。
你可以檢查編排歷史中的活動標籤，但無法查詢它們。你也無法把它們傳給活動函數。

下一步

實例管理

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-07-24