di-agent-parameter-sets

パラメーターセット

返信に UUID を含めないでください。 プロジェクト ID、アセット ID、フロー ID、接続 ID、パラメーターセット ID など、ツールの結果に含まれていたか、セッションのコンテキストに含まれていたかにかかわらず、UUID は一切返信に含めてはいけません。特に、「プロジェクト <uuid> では」や「プロジェクト 4c2d… では」のような表現で返信を始めないでください。アセットは必ず名前だけで識別してください。例外は、ツールがそのまま返した flow_link フィールドのみです。

StreamSets がサポートするパラメーター型は string のみです。 ユーザーの依頼が StreamSets フローに関するもので、指定されたパラメーターに string 型以外のものが含まれている場合は、ツールを呼び出す前に直ちに停止してください。この制約を説明し、string 型のみを使う修正案を提示したうえで、実行の確認を待ってください。この確認は、list_streamsets_flows、create_parameter_set、その他すべてのツール呼び出しより先に行う必要があります。

パラメーターセットは、プロジェクトレベルのアセットとして保存される、型付きパラメーターの名前付きコレクションです。値を一度定義して複数のフローで再利用でき、フローを変更せずにジョブの実行時に環境（dev、test、prod）を切り替えられます。

まずフローの種類を必ず確認する

ツールを呼び出す前に、対象のフローの種類を確認してください。

• DataStage（バッチ）— 11 種類すべてのパラメーター型、値セット、PROJDEF、ローカルパラメーターをサポートします
• StreamSets（ストリーミング）— string 型のパラメーターのみをサポートします。値セットと PROJDEF はサポートしません

パラメーターセットの機能の多くはエンジン固有です。種類を誤ると、エラーが通知されないまま失敗する可能性があります。 → 制約と検証チェックリストの全容は resources/streaming_limitations.md を参照してください。

必要な機能はどれですか？

ユーザーのニーズ	使用する機能
複数のフローで値を再利用する	パラメーターセット
dev／test／prod 環境を切り替える	パラメーターセットの値セット
1 回のフロー実行にのみ使うパラメーター	ローカルパラメーター（DataStage のみ）— add_local_parameter を使用
プロジェクトレベルの DataStage 環境変数	PROJDEF
StreamSets フローをパラメーター化する	string 型のみのパラメーターセット
環境間で接続値を管理する	パラメーターセットを接続にアタッチ

よくあるタスク

パラメーターセットの一覧表示または検索

list_parameter_sets(project_id=..., name_filter=...)  # use name_filter to narrow
get_parameter_set(parameter_set_id=..., project_id=...)  # full details incl. value sets

パラメーターセットの名前のみで報告してください。

再利用可能なパラメーターセットを作成する

対象が StreamSets フローの場合、ツールを呼び出す前にすべてのパラメーター型が string であることを確認してください — 上記の「まずフローの種類を必ず確認する」を参照してください。

create_parameter_set(project_id=..., name=..., parameters=[...])

パラメーターセット名とパラメーターのみで確認してください。

DataStage フローでは、11 種類すべての型がサポートされます。 → 型の一覧は resources/parameter_types.md を参照してください。

既存のセットのパラメーターを追加または変更する

parameters は完全置換リストです。省略したパラメーターは削除されます。 ツールはこれを自動的に確認します。送信したリストによって既存のパラメーターが削除される場合、失われるパラメーター名とともにエラーを返し、すべて含めるか confirm_replacement=True を渡すよう求めます。

変更内容は、パラメーターセット名と更新後のパラメーターリストで確認してください。

最も安全な手順は、先に取得してから統合することです。

get_parameter_set(...)               # 1. fetch current parameters
update_parameter_set(                # 2. submit full replacement list
    parameter_set_id=...,
    project_id=...,
    parameters=[...merged...],
)

パラメーターを意図的に削除するには、confirm_replacement=True を渡してください。

update_parameter_set(
    parameter_set_id=...,
    project_id=...,
    parameters=[...reduced list...],
    confirm_replacement=True,
)

dev／test／prod 環境を作成する

値セットを使うと、1 つのパラメーターセットに複数の環境スナップショットを持たせることができます。

manage_value_set(action="add",     value_set_name="prod", values={...})
manage_value_set(action="replace", value_set_name="prod", values={...})  # overwrite
manage_value_set(action="remove",  value_set_name="dev")

パラメーターセット名と値セット名で確認してください。

シークレットの値をユーザーにそのまま返さないでください。 パラメーターセットに encrypted パラメーターが含まれている場合、設定されたパラメーター名（例：「DB_PASS を保存しました」）を示して操作を確認してください。実際の値を返信で繰り返してはいけません。これは確認、要約、計画のプレビューすべてに適用されます。

→ ワークフローと実行時の選択方法の全容は resources/value_sets.md を参照してください。

パラメーターセットをフローに関連付ける

attach_parameter_set_to_flow(project_id=..., flow_id=..., engine=..., parameter_set_name=...)

登録はすぐに保存されます。**成功を確認したら、必ず次のステップをユーザーに伝えてください。**パラメーターを有効にするには、エンジンに応じた正しい構文で、ステージの式に参照を追加します。

• DataStage：#setName.paramName#
• StreamSets：${setName__paramName}

関連付けの確認を返信するたびに、次のステップの案内を必ず含めてください。ユーザーが関連付けだけを依頼した場合も省略しないでください。フロー名とパラメーターセット名を使って確認してください。 → 参照構文とワークフローについては、resources/flow_integration.md を参照してください。

パラメーターセットを接続に関連付ける

attach_parameter_set_to_connection(
    project_id=...,
    connection_id=...,
    parameter_set_name=...,
    property_mappings={"host": "DB_HOST", "port": "DB_PORT", "database": "DB_NAME"},
)

接続名とパラメーターセット名を使って確認してください。ツールの結果に実行時の値セット選択例が含まれている場合は、文章で伝えてください（例：「実行時に環境を切り替えるには、ジョブの実行時パラメーターに値セット名を渡します」）。コードブロックとして再掲しないでください。

一覧にある接続プロパティ値を #paramSetName.paramName# 参照に置き換え、接続の「Use external Parameter Sets」トグルを有効にします。list_connections で connection_id を確認し、inspect_project_asset に asset_type="connection" を指定して利用可能なプロパティ名を確認します。また、list_parameter_sets／get_parameter_set でパラメーター名を確認します。 → ワークフローの全体については、resources/connection_integration.md を参照してください。

フローが使用するパラメーターを監査する

get_flow_parameter_references には flow_id が必要です。空の文字列を指定して呼び出さないでください。ユーザーがフロー名を指定した場合は、必ず最初に list_datastage_flows を呼び出して ID を解決してから、その ID を指定して get_flow_parameter_references を呼び出してください。リスト取得が完了する前に get_flow_parameter_references を呼び出さないでください。

list_datastage_flows(entity_name=..., project_id=...)   # 1. always do this first
get_flow_parameter_references(flow_id=..., project_id=...)  # 2. then call with the id

external_paramsets（フローに登録されたパラメーターセット）と local_parameters（フローのスコープ内のパラメーター）を返します。フロー名、パラメーターセット名、ローカルパラメーター名を使って報告してください。パラメーターセットを削除する前に、フローが引き続きそれを参照しているか確認する場合や、attach_parameter_set_to_flow の後に登録が保存されたか確認する場合に使用してください。

DataStage 専用 — engine は省略可能で、デフォルトは "datastage" です。明示的に未対応エラーを発生させたい場合に限り、engine="streamsets" を渡してください。これはフローに「登録されている」内容を報告するもので、どのステージ式が実際にそれらのパラメーターを使用しているかは報告しません。#setName.paramName# の使用箇所を確認するには、retrieve_datastage_flow_code でフローを取得し、ステージプロパティの文字列を検索してください。

DataStage フローにローカルパラメーターを追加する

ローカルパラメーターはフローのスコープ内で定義される変数で、他のフローとは共有されず、パラメーターセットの一部でもありません。ステージ式では #paramName#（セット名のプレフィックスなし）で参照します。

add_local_parameter(
    flow_id=..., project_id=...,
    engine="datastage",        # streamsets is not supported — returns an error
    name="SCHEMA",
    type="string",             # all 11 DataStage types supported
    value="PUBLIC",            # optional default
)

フロー名とパラメーター名を使って確認してください。

• 同じ名前のローカルパラメーターがすでに存在する場合は上書きされます（大文字と小文字を区別して照合します）。
• type では create_parameter_set と同じエイリアスを使用できます。integer → int64、float → sfloat、list → enum。
• enum 型では valid_values=[...] が必要です。
• subtype="envvar" はそのまま受け付けられますが、バックエンドでの検証は行われていません。確認されるまでは実験的な機能として扱ってください。

DataStage フローからローカルパラメーターを削除する

remove_local_parameter(flow_id=..., project_id=..., engine="datastage", name=...)

フロー名とパラメーター名を使って確認してください。

指定した名前のパラメーターを削除します。大文字と小文字を区別して照合します。成功時は status="removed"、名前が存在しない場合は status="not_found" を返します。事前に存在確認をしなくても安全に呼び出せます。

セットの名前または説明を変更する

update_parameter_set(parameter_set_id=..., project_id=..., name="NewName", description="...")

古い名前と新しい名前だけを使って確認してください。

パラメーターセットを削除する

必須の手順 — すべてのステップを省略せずに実行してください：

1. list_parameter_sets を呼び出して、名前からアセット ID を特定します。
2. その ID を指定して get_asset_relationships（asset_type "parameter_set"）を呼び出します。delete_parameter_set を呼び出す前に必ず実行してください。参照があると予想されるかどうかは問いません。
3. used_by が空でない場合は、参照しているフローまたは接続をすべてユーザーに伝え、続行する前に確認を求めてください。
4. used_by が空の場合は、すぐに削除してください。確認のやり取りは不要です。
5. delete_parameter_set は、ステップ 3 で確認を得た後（またはステップ 4 が該当する場合）にのみ呼び出してください。

# Step 1
list_parameter_sets(project_id=..., name_filter="MySet")

# Step 2 — always, unconditionally
get_asset_relationships(
    assets=[{"asset_type": "parameter_set", "asset_id": "<resolved_id>"}],
    project_id=...
)

# Step 5 — only after steps 3–4
delete_parameter_set(parameter_set_id=..., project_id=...)

パラメーターセット名のみを指定して削除を確認します。

完全に削除され、復元できません。ツールが返すのは {'deleted': True, 'parameter_set_id': ...} のみです。参照しているフローは確認しません。引き続き参照されているセットを削除すると、参照の不整合が解消されるまで、そのフローの検証や実行ができなくなる可能性があります。

ツールリファレンス

ツール	目的
list_parameter_sets	プロジェクト内のすべてのセットを一覧表示します（PROJDEF は除外）
get_parameter_set	詳細情報：パラメーターと値セット。セットに StreamSets との非互換性がある場合は streaming_warnings を含みます
create_parameter_set	新しいセットを作成します
update_parameter_set	名前の変更、説明の更新、またはパラメーターリストの置換を行います。誤削除を防ぐため、削除を許可するには confirm_replacement=True を指定します
delete_parameter_set	セットを完全に削除します。まず get_asset_relationships を呼び出して参照しているフローを特定し、ユーザーに警告してから削除します
manage_value_set	名前付きの値セットを追加／置換／削除します
attach_parameter_set_to_flow	DataStage または StreamSets のフローにセットを関連付けます
attach_parameter_set_to_connection	パラメーターセットで接続プロパティをパラメーター化し、接続で「外部パラメーターセットを使用」を有効にします
get_flow_parameter_references	DataStage フローに登録された external_paramsets と local_parameters を返します（DataStage のみ）
add_local_parameter	DataStage フローのローカルパラメーターを追加または上書きします（DataStage のみ）
remove_local_parameter	DataStage フローのローカルパラメーターを削除します（DataStage のみ）

ガードレール

• このスキルの冒頭にある UUID ルールを確認してください。返信で UUID を絶対に繰り返さないでください。
• PROJDEF は予約済みのシステム名です。この名前でセットを作成しないでください。
• update_parameter_set は parameters リスト全体を置き換えます。最初に取得し、マージしてから送信してください。
• delete_parameter_set は取り消せません。「Delete a parameter set」の下にある5段階の手順に従い、必ず delete_parameter_set の前に get_asset_relationships を実行してください。used_by が空の場合に限り確認のターンを省略できます。それ以外の場合は、最初に警告して確認してください。
• StreamSets：パラメーターセット名に __ を含めることはできません。注入されるのは string パラメーターのみです。
• add_local_parameter と remove_local_parameter は DataStage 専用です。engine="streamsets" を渡すと、直ちにエラーが返されます。get_flow_parameter_references では、engine 引数は省略可能で、デフォルトは "datastage" です。
• 大文字と小文字が異なる重複を作成しないよう、add_local_parameter の前に get_flow_parameter_references を呼び出してください。
• get_flow_parameter_references が報告するのは登録状況のみです。セットが external_paramsets に表示されても、ステージ式で使用されていることの証明にはなりません。また、表示されなくても、フロー内に #setName.paramName# のテキストが残っていないことの証明にはなりません。
• attach_parameter_set_to_connection：property_mappings の両方の値は、パッチが適用される前に検証されます。キーは接続にすでに存在するプロパティでなければならず、値は指定したセットのパラメーターでなければなりません。利用可能なプロパティ名を確認するには、inspect_project_asset(asset_type="connection") を使用してください。マッピングしないプロパティは、シークレットも含めて変更されません。
• update_datastage_flow はフロー定義全体を置き換えますが、保存済みのフローを先に読み込むため、external_paramsets と local_parameters は編集後も保持され、再アタッチは不要です。重要な編集の後は、get_flow_parameter_references で確認してください。→ 詳細なリスク一覧は resources/flow_lifecycle_with_parameters.md を参照してください。
• 期待どおりに動作しない場合 → resources/troubleshooting.md を参照してください。
• よくあるエージェントのミスについては → resources/common_mistakes.md を参照してください。