このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。
作業をコーディングエージェントに任せるには、difyctl スキルでエージェントをセットアップ し、このページを渡してください。
前提条件#
-
エクスポート元のアプリと更新するアプリには、いずれもサービス API アクセスが必要です。
-
アプリが 2 つの Dify サーバーにまたがる場合は、
DIFY_CONFIG_DIRでサーバーごとに別のフォルダを指定して、それぞれにサインインします。次に、それぞれのフォルダを指定してdifyctl versionを実行し、どちらのサーバーのバージョンも手元のdifyctlと一致していることを確認します。Info各コマンドは、対象のアプリがあるサーバーのフォルダを指定して実行します。
-
Cloud アプリのワークスペースが別々なら、
difyctlのワークスペースを切り替えます。切り替え先は、更新するアプリのワークスペースです。もう一方のワークスペースのアプリも、--app-idを指定すればそのままエクスポートできます。その ID は、get console_appにもう一方のワークスペースの--workspace-idを付けて確認します。
アプリの更新#
ファイルから更新できるのは、Workflow アプリと Chatflow アプリだけです。ほかの種類のアプリは、代わりに ファイルからアプリを作成 してください。
更新しても、アプリの Web アプリ URL と API キーはそのまま残ります（ほかに残るもの）。インポートすると、まだ公開していない変更も含めて、アプリのドラフトが置き換わります。新しいワークフローは、公開した時点で有効になります。
これらの手順をパイプラインで実行する場合は、CI と自動化での difyctl の使用 もあわせて参照してください。ジョブのサインイン方法と、失敗時にジョブを止める方法を説明しています。
アプリ ID の確認
アプリを一覧表示し、更新するアプリと、ファイルのエクスポート元にするアプリの id を控えておきます：
このページの例では、本番用のアプリ「Order Status」を更新します。使うのは、テスト済みのコピー「Order Status (staging)」からエクスポートしたファイルです：
ファイルの取得
DSL ファイル がすでに Git にある場合は、手順 3 に進みます。ない場合は、更新するアプリのテスト済みコピーなど、別のアプリからエクスポートします。
まず、そのアプリで、タイトルなどの Web アプリ設定 を、ユーザーに見せる内容にしておきます。設定はファイルに含まれ、インポートするとすぐにユーザーに表示されます。
次に、そのアプリで公開中のバージョンをエクスポートします。get console_app version で current: true と表示されるバージョンです：
代わりに未公開の変更をエクスポートするには、--workflow-id を省略します。
エクスポートしたファイルでは、シークレットの値が空になります。更新するアプリのシークレットを、このアプリの値で置き換える場合に限り、--include-secret を付けます。この方法でエクスポートしたファイルには値が平文で含まれるため、Git や共有される場所には置かないでください。
更新するアプリが別のワークスペースや別のサーバーにある場合、インポートすると、各知識検索ノードはナレッジベースとの関連付けを失います。関連付けを保つには、ファイル内のノードの dataset_ids にある ID を、インポート先のナレッジベースの ID に置き換えてください。その ID は、インポート先で get knowledge_base を実行すると確認できます。
ファイルの検証
結果が valid: true であれば、そのファイルはインポートできます。そうでない場合は、severity が error の各問題を、loc が示すノードとフィールドで修正し、もう一度検証します。
severity が warning の問題があっても、インポートは止まりません。この問題は、認証情報やモデルが不足していることを示します。不足分は手順 5 で設定します。
ファイルのインポート
アプリのドラフトハッシュを取得し、そのハッシュを指定してファイルをインポートします。その間に誰かがドラフトを変更した場合、ハッシュを指定したインポートは拒否されます。その人の変更が上書きされることはありません。
インポートすると、公開しなくても、アプリの名前、説明、アイコン、Web アプリ設定がすぐにファイルの内容に置き換わります。
アプリの名前と説明を残すには、--name と --description で現在の値を渡します。ファイルのアイコンや Web アプリ設定がこのアプリに合わない場合は、インポートの直後に 変更します。
インポートに成功すると、status: completed が返されます。警告がある場合は completed-with-warnings が返されるので、先に進む前に警告を読んでください。それ以外の結果になった場合は、次のように対処します：
-
ハッシュを取得した後にドラフトが変更された場合、インポートは終了コード 1 で拒否され、
The draft changed after it was exported.と表示されます。スタジオで、ドラフトの変更内容を確認します。
- 変更を破棄してよい場合は、ハッシュを取得し直してインポートします。変更はインポートで置き換わります。
- 変更を残す必要がある場合は、ファイルかエクスポート元のアプリに同じ変更を加え、手順 2 からやり直します。
-
ファイルの DSL
versionがサーバーの対応範囲より新しい場合、statusはpendingになります。それでもインポートするには、confirm console_app dsl_importという ヒントを実行 します。 -
ファイルが無効な場合、インポートは終了コード 1 で拒否されます。手順 3 と同じようにファイルを検証し、報告された問題を修正してから、もう一度インポートします。
その他のエラーの対処方法については、トラブルシューティング を参照してください。
インポートしたワークフローを破棄するには、公開中のバージョンをドラフトに復元 します。そのバージョンはすでに公開中なので、公開し直す必要はありません。
不足している統合のインストール
ファイルで使われている統合がワークスペースになくても、検証とインポートは成功することがあります。不足している統合は、インポートから 10 分以内に一覧表示してください。10 分を過ぎると、空の一覧が返されます：
マーケットプレイスから統合をインストールするには、その ヒントを実行 します。認証情報が必要な統合があれば、手順 7 でテストする前に、スタジオで追加しておきます。
環境変数の設定
インポートにより、アプリの環境変数にはファイルの値が設定されています。呼び出す API のアドレスなど、このアプリで別の値にすべきものを設定し直します。
アプリの環境変数を一覧表示します。このアプリの値が残っているシークレットはアスタリスクの列で、空のシークレットは "" で表示されます：
変更が必要な値を、空のシークレットも含めてそれぞれ設定します。変数の id を --env-id に指定します：
ドラフトのテスト
典型的な入力で、ドラフトを 1 回実行します。テストでは、本番の API キーなど、このアプリの環境変数が使われます。実際に実行しても問題のない入力を選んでください。describe console_app を実行すると、アプリが受け取る入力 を確認できます。
Chatflow アプリでは、代わりに test console_app advanced_chat を使います。
実行が完了すると status: ended に、失敗すると status: failed になります。失敗の理由は error.message で確認できます。ファイルかエクスポート元のアプリでワークフローを修正し、手順 2 からやり直します。
DSL バージョンの新しいファイルがこのサーバーで動作しない場合は、代わりに 公開中のバージョンをドラフトに復元 します。そのバージョンはすでに公開中なので、公開する必要はありません。
公開準備の確認
ready: true は、ドラフトが有効で、直近のテストに合格したことを表します。
ready が false の場合は、ヒントに従って 対処し、もう一度確認します。
テストを再実行しても ready が false のままなら、テスト中にノードが失敗しています。そのノードの 例外処理 の設定により、実行はそのまま完了しています。失敗したノードを特定するには、run_id を使って テストの実行を調査 します。
- そのノードが本来失敗しないはずなら、ファイルかエクスポート元のアプリでノードを修正し、手順 2 からやり直します。
- その失敗を処理するようにワークフローを設計している場合は、どのノードも失敗しない入力でテストします。
公開する前に、changes で公開済みのバージョンとの違いを確認します。
公開
更新のロールバック#
公開した更新に問題がある場合は、アプリの公開済みバージョンを一覧表示し、以前のバージョンを id で指定してドラフトに復元してから公開します。そのバージョンは以前に公開されていたものなので、テストと公開準備の確認は省略できます。
復元すると、ドラフトが置き換わります。ドラフトを残すには、先に --workflow-id を付けずにエクスポートしておきます。
環境変数は、そのバージョンの値に戻ります。名前、説明、アイコン、Web アプリ設定は、インポートで設定されたままです。これらも元に戻すには、設定し直してください。
DSL ファイルからのアプリの作成#
--app-id を付けずにファイルをインポートすると、ファイルと同じ種類のアプリが新しく作成されます。アプリ名は --name で指定します：
以降のコマンドでは、結果の app_id を --app-id に指定します。
作成したアプリでは、Web アプリのタイトルに --name ではなくファイルの値が使われます。そのタイトルをユーザーに見せたくない場合は、変更してください。
Workflow アプリや Chatflow アプリを仕上げるには、アプリの更新 の手順 5 から 9 を行います。ほかの種類のアプリに必要なのは、手順 5 だけです。
アプリパッケージのインポート#
スタジオからエクスポートした アプリパッケージ（.ifpkg）をインポートするには、パッケージを展開し、中にある app.yaml を DSL ファイルとして使います。アップロードしたアイコンは引き継がれません。インポート後に 設定し直してください。
Web アプリとアプリ情報の変更#
タイトルなどの Web アプリ設定を変更するには、set webapp を使います。アプリの名前、説明、アイコンを変更するには、set app_info を使います。変更されるのは、渡したフィールドだけです。
Workflow アプリ以外のアプリでは、difyctl help set webapp または difyctl help set app_info を実行して、対応するコマンドを確認します。