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

タグのしくみ

オーケストレーション、アクティビティ、またはサブオーケストレーションをスケジュールする際には、文字列のキー・値ペアの辞書をタグとして提供できます。 Durable Task Schedulerは、タグ付けするタグによって異なる方法でタグを保存・公開します:

  • オーケストレーションタグは オーケストレーションインスタンスにメタデータとして格納されます。 サブオーケストレーションを呼び出す際に提供したタグは、子オーケストレーションインスタンスのメタデータとなります。 これらのタグを読み、オーケストレーションインスタンスをタグごとにフィルタリングできます。
  • アクティビティタグ は親オーケストレーション履歴のアクティビティのスケジュールされたイベントに保存されます。 オーケストレーション履歴で検査はできますが、インデックス化されておらず、オーケストレーションタグクエリには利用できません。 アクティビティタグもアクティビティ関数には渡されません。

オーケストレーション、アクティビティ、またはサブオーケストレーションをスケジュールする際にタグを設定しましょう。 その後タグは変更できません。

カスタム表示名を設定する

よく知られた 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);

アクティビティにタグを追加する

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

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

サブオーケストレーションにタグを追加する

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

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

オーケストレーションタグを読む

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

クエリ タグ

Durable Task Schedulerダッシュボードで、Tagフィルターを使ってオーケストレーションインスタンスをオーケストレーションタグでフィルタリングします。 フィルターはタグのキーまたは値に基づいて一致します。 オーケストレーションリストにはまた、オーケストレーションタグが列として表示されます。

アクティビティタグはオーケストレーション履歴のスケジュールされたイベントに表示されます。 オーケストレーションリストの タグフィルターには含まれていません。

オーケストレーション一覧のタグ フィルターとタグ列を示す Durable Task Scheduler ダッシュボードのスクリーンショット。

タグのガイドライン

  • 一貫したキーを使う — オーケストレーションのインスタンスやアクティビティの相関を確実にフィルタリングできるように、命名規則に従ってください。
  • タグを意味のあるものにする - コンテキストを提供する値を使用します。
  • 文字列値を使用する — キーと値は文字列です。
  • マインドオーケストレーションタグサイズ — JSONシリアライズされたタグ辞書は最大 1,000バイトまで可能です。 この制限はすべてのキーと値を含み、マルチバイトのUTF-8文字はそれぞれ1バイト以上とカウントされます。 アクティビティタグはこのオーケストレーションインスタンスのメタデータ制限を使いませんが、オーケストレーション履歴のサイズに寄与します。

Limitations

  • オーケストレーション、アクティビティ、またはサブオーケストレーションがスケジュールされた後はタグは不変です。
  • タグ キーと値は文字列です。
  • オーケストレーション履歴でアクティビティタグは検査できますが、クエリはできません。 また、アクティビティ関数に渡すこともできません。

次のステップ