di-agent-flow-datastage

SDK を使用した DataStage フローの作成と編集

ルーティングは別の場所で行います。 リクエストをここで作成するか pyflow で作成するか、また新規作成か編集かは、di-agent-flow-lifecycle スキル（AUTHOR 状態）で決定します。このファイルは SDK のリファレンスであり、SDK の使用方法を説明しています。フローを扱う前に、di-agent-flow-lifecycle スキルを完全に理解する必要があります。ライフサイクルスキルを読み込む前に、SDK コードを書かないでください。

DataStage のバッチフローは SDK スタイルの Python コードで記述し、update_datastage_flow（既存のフローをその場で編集）または create_datastage_flow（新しいフローを作成）を使って送信します。認証、プロジェクトコンテキスト、永続化は自動的に処理されます。

SDK からは、pyflow ではフォームが用意されていないものも含め、エンジンの全体ステージカタログにアクセスできます。その代償として、ステージのタイプ、プロパティ名、列挙値を正確に指定する必要があります。そのため、ルーターではこれを既定の方法ではなく、最終手段として扱います。

どちらのツールも、呼び出しの一部としてフローをコンパイルします。 コンパイルに失敗すると、結果には status: "compile_error" と flow_id、flow_link、ステージごとの compile_errors リストが含まれます。フローは保存されたままです。同じ flow_id に対して update_datastage_flow を使って修正してください。新しいフローを作成したり、問題のあるフローを削除したりしないでください。編集対象を指定するために、その ID が必要です。

参照先

• SDK の規約（メソッドシグネチャ、ステージ設定、リンクスキーマ、列タイプ、接続のバインド、キーのルール、完全な例）→ references/sdk-conventions.md
• ステージの選択 → recommend_datastage_stages(subutterances=[...])
• ステージのプロパティ名と使用可能な値 → datastage_property_lookup(requests=[{"stage": "..."}])
• ステージごとの詳細 → di-agent-knowledge-engine-datastage スキル stages/
• フローの最適化 → di-agent-knowledge-engine-datastage スキル optimization/overview.md
• カスタムステージ（C/C++、Java） → BuildopStage.md、JavaIntegrationStage.md
• Transformer ステージの式 → di-agent-knowledge-engine-datastage スキルのリソース stages/TransformerStageFunctions/TransformerStageFunctionsOverview.md

編集

既存のフローの編集： 変更が、既存の構造上の式やステージプロパティに限定される場合は、インプレースの SDK 編集が適切です。retrieve_datastage_flow_code でフローを取得し、その SDK を変更して、update_datastage_flow で再送信します。検証済みで、すでに配線済みのコードに変更を加えるため、信頼性が高く、損失がなく、コストも低く抑えられます。

取得したコードを編集し、断片を手作業で作成しないでください。 update_datastage_flow の送信内容は、単独のスニペットではなく、retrieve_datastage_flow_code が返した完全な SDK に変更を組み込んだものでなければなりません。参照するステージ、リンク、スキーマはすべて、同じ送信内容内で先に変数として定義してください（取得したコードでは derive_seg、veh_in、fp などがすでに定義されているため、それらの変数名を再利用します）。フラット化された SDK 文法には、既存の要素を取得する方法がありません。flow.links["x"]、flow.stages["y"]、link.schema はすべて「Unsupported statement type」／「variable does not exist」として拒否されます。既存のリンクに列を追加するには、取得したコード内にある、そのリンクの既存の create_schema()／add_field(...) の行を編集してください。構造を追加するには、すでに定義済みの変数を参照する flow.add_stage(...)／stage.connect_output_to(...)／link.create_schema() ステートメントを追加してください。送信内容の検証に失敗した場合は、再送信するコード全体を修正してください。要素を再取得したり、最初から作り直したりしないでください。

変更によって構造（新しいソース、結合、異なる形状など）を追加または変更する場合は、ここで一から手作業で作成しないでください。これは SDK で最も信頼性の低い方法です。まず pyflow（di-agent-flow-pyflow）で新しい構造を作成し、次にここで生成された SDK を精密に編集して、pyflow では表現できないものを追加してください。中心となる形状を pyflow で忠実に表現できない場合は、pyflow で作成可能な最も近い形状を用意し、update_datastage_flow でここで目的の形状に変更してください。

バージョン管理とバックアップは、ライフサイクルルーターの RECOVER 状態（di-agent-flow-lifecycle/references/recover.md）が担当します。要点：update_datastage_flow はフローを上書きする前に自動でスナップショットを作成するため、事前に duplicate_asset を呼び出す必要はありません。呼び出すと不要なコピーが残るだけです。各フローにつき最大 5 個のスナップショットが保持され（最も古いものは削除されません）、デフォルトでは list_datastage_flows に表示されず、フローとともに削除されます。

ガードレール

• フローは flow_id で取得してください — retrieve_datastage_flow_code は flow_name も受け付けますが、その方法では名前検索で最初に一致したフローを一意性の確認なしに取得するため、名前が曖昧だと、別のフローのコードが気付かれないまま返されます
• ステージタイプ、プロパティ名、列挙値を推測しないでください — recommend_datastage_stages／datastage_property_lookup を使用してください
• 変更はすべて1回の送信にまとめてください — 連続して送信すると、互いの内容が上書きされます
• update_datastage_flow でフローが新規作成されることはありません — 指定したフローが存在しない場合はエラーになります。list_datastage_flows で名前を確認してください。作成には create_datastage_flow（または pyflow）を使用してください。どちらを使うかについては、ライフサイクルルーターを参照してください
• 更新に成功したら、ツールの結果で返された flow_link を、ユーザーが UI でフローを開けるクリック可能なリンクとして提示してください
• 文章で示すステージプロパティ名 — 内部識別子（nrecs）ではなく、datastage_property_lookup の User friendly name（例：「行数（パーティションごと）」）を使用してください。内部名を示すのは、コードブロック内か、ユーザーが SDK プロパティを求めた場合に限ります
• パラメーター化されたフロー： update_datastage_flow は再構築前に既存のフローを読み込むため、SDK 編集を行っても、パラメーターセットの登録とローカルパラメーターは保持されます。編集後にジョブから予期せずパラメーターのバインドが失われた場合は、get_flow_parameter_references を呼び出して登録内容を監査し、attach_parameter_set_to_flow／add_local_parameter を使って不足しているエントリーを復元してください