DSL ファイルからのアプリの作成と更新

このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版を参照してください。

作業をコーディングエージェントに任せるには、difyctl スキルでエージェントをセットアップし、このページを渡してください。

前提条件

エクスポート元のアプリと更新するアプリには、いずれもサービス API アクセスが必要です。
アプリが 2 つの Dify サーバーにまたがる場合は、DIFY_CONFIG_DIR でサーバーごとに別のフォルダを指定して、それぞれにサインインします。次に、それぞれのフォルダを指定して difyctl version を実行し、どちらのサーバーのバージョンも手元の difyctl と一致していることを確認します。
各コマンドは、対象のアプリがあるサーバーのフォルダを指定して実行します。
Cloud アプリのワークスペースが別々なら、difyctl のワークスペースを切り替えます。切り替え先は、更新するアプリのワークスペースです。もう一方のワークスペースのアプリも、--app-id を指定すればそのままエクスポートできます。その ID は、get console_app にもう一方のワークスペースの --workspace-id を付けて確認します。

アプリの更新

ファイルから更新できるのは、Workflow アプリと Chatflow アプリだけです。ほかの種類のアプリは、代わりにファイルからアプリを作成してください。更新しても、アプリの Web アプリ URL と API キーはそのまま残ります（ほかに残るもの）。インポートすると、まだ公開していない変更も含めて、アプリのドラフトが置き換わります。新しいワークフローは、公開した時点で有効になります。

これらの手順をパイプラインで実行する場合は、CI と自動化での difyctl の使用もあわせて参照してください。ジョブのサインイン方法と、失敗時にジョブを止める方法を説明しています。

アプリ ID の確認

アプリを一覧表示し、更新するアプリと、ファイルのエクスポート元にするアプリの id を控えておきます：

difyctl get console_app

このページの例では、本番用のアプリ「Order Status」を更新します。使うのは、テスト済みのコピー「Order Status (staging)」からエクスポートしたファイルです：

{
  "data": [
    {
      "id": "9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d",
      "name": "Order Status",
      "mode": "workflow",
      …
    },
    {
      "id": "5c1e8f2a-7b3d-4e9a-8f6c-2d4b1a9e7c3f",
      "name": "Order Status (staging)",
      "mode": "workflow",
      …
    },
    …
  ],
  …
}

ファイルの取得

DSL ファイルがすでに Git にある場合は、手順 3 に進みます。ない場合は、更新するアプリのテスト済みコピーなど、別のアプリからエクスポートします。まず、そのアプリで、タイトルなどの Web アプリ設定を、ユーザーに見せる内容にしておきます。設定はファイルに含まれ、インポートするとすぐにユーザーに表示されます。次に、そのアプリで公開中のバージョンをエクスポートします。get console_app version で current: true と表示されるバージョンです：

V=$(difyctl get console_app version --app-id 5c1e8f2a-7b3d-4e9a-8f6c-2d4b1a9e7c3f | jq -r '.data[] | select(.current) | .id')
difyctl export console_app dsl --app-id 5c1e8f2a-7b3d-4e9a-8f6c-2d4b1a9e7c3f --workflow-id $V | jq -r .data > order-status.yml

代わりに未公開の変更をエクスポートするには、--workflow-id を省略します。エクスポートしたファイルでは、シークレットの値が空になります。更新するアプリのシークレットを、このアプリの値で置き換える場合に限り、--include-secret を付けます。この方法でエクスポートしたファイルには値が平文で含まれるため、Git や共有される場所には置かないでください。更新するアプリが別のワークスペースや別のサーバーにある場合、インポートすると、各知識検索ノードはナレッジベースとの関連付けを失います。関連付けを保つには、ファイル内のノードの dataset_ids にある ID を、インポート先のナレッジベースの ID に置き換えてください。その ID は、インポート先で get knowledge_base を実行すると確認できます。

ファイルの検証

difyctl check console_app dsl --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d --yaml-content "$(cat order-status.yml)"

結果が valid: true であれば、そのファイルはインポートできます。そうでない場合は、severity が error の各問題を、loc が示すノードとフィールドで修正し、もう一度検証します。severity が warning の問題があっても、インポートは止まりません。この問題は、認証情報やモデルが不足していることを示します。不足分は手順 5 で設定します。

ファイルのインポート

アプリのドラフトハッシュを取得し、そのハッシュを指定してファイルをインポートします。その間に誰かがドラフトを変更した場合、ハッシュを指定したインポートは拒否されます。その人の変更が上書きされることはありません。

インポートすると、公開しなくても、アプリの名前、説明、アイコン、Web アプリ設定がすぐにファイルの内容に置き換わります。

アプリの名前と説明を残すには、--name と --description で現在の値を渡します。ファイルのアイコンや Web アプリ設定がこのアプリに合わない場合は、インポートの直後に変更します。

H=$(difyctl export console_app dsl --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d | jq -r .draft_hash)
difyctl import console_app dsl --mode yaml-content --yaml-content "$(cat order-status.yml)" \
  --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d --draft-hash $H --name "Order Status" --description "注文のステータスをまとめます。"

インポートに成功すると、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 分を過ぎると、空の一覧が返されます：

difyctl check console_app dependency --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d

マーケットプレイスから統合をインストールするには、そのヒントを実行します。認証情報が必要な統合があれば、手順 7 でテストする前に、スタジオで追加しておきます。

環境変数の設定

インポートにより、アプリの環境変数にはファイルの値が設定されています。呼び出す API のアドレスなど、このアプリで別の値にすべきものを設定し直します。アプリの環境変数を一覧表示します。このアプリの値が残っているシークレットはアスタリスクの列で、空のシークレットは "" で表示されます：

difyctl get console_app env --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d

変更が必要な値を、空のシークレットも含めてそれぞれ設定します。変数の id を --env-id に指定します：

# シークレット。シェルの履歴に残らないよう、シェル変数から読み込む
difyctl set console_app env --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d --env-id 2a7c4e9b-6d1f-4b3a-9e8c-5f0d1a2b3c4d --name ORDERS_API_KEY --value "$ORDERS_API_KEY" --value-type secret

# 通常の値
difyctl set console_app env --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d --env-id 6f3b8d1e-4c2a-4e7f-a9b5-0d8c7e6f5a4b --name API_BASE_URL --value "https://orders.example.com/api" --value-type string

ドラフトのテスト

典型的な入力で、ドラフトを 1 回実行します。テストでは、本番の API キーなど、このアプリの環境変数が使われます。実際に実行しても問題のない入力を選んでください。describe console_app を実行すると、アプリが受け取る入力を確認できます。

difyctl test console_app workflow --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d --inputs '{"topic": "order 1042"}'

Chatflow アプリでは、代わりに test console_app advanced_chat を使います。実行が完了すると status: ended に、失敗すると status: failed になります。失敗の理由は error.message で確認できます。ファイルかエクスポート元のアプリでワークフローを修正し、手順 2 からやり直します。DSL バージョンの新しいファイルがこのサーバーで動作しない場合は、代わりに公開中のバージョンをドラフトに復元します。そのバージョンはすでに公開中なので、公開する必要はありません。

公開準備の確認

difyctl check console_app release --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d

ready: true は、ドラフトが有効で、直近のテストに合格したことを表します。ready が false の場合は、ヒントに従って対処し、もう一度確認します。テストを再実行しても ready が false のままなら、テスト中にノードが失敗しています。そのノードの 例外処理 の設定により、実行はそのまま完了しています。失敗したノードを特定するには、run_id を使ってテストの実行を調査します。

そのノードが本来失敗しないはずなら、ファイルかエクスポート元のアプリでノードを修正し、手順 2 からやり直します。
その失敗を処理するようにワークフローを設計している場合は、どのノードも失敗しない入力でテストします。

公開する前に、changes で公開済みのバージョンとの違いを確認します。

公開

difyctl publish console_app --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d --marked-name v2

更新のロールバック

公開した更新に問題がある場合は、アプリの公開済みバージョンを一覧表示し、以前のバージョンを id で指定してドラフトに復元してから公開します。そのバージョンは以前に公開されていたものなので、テストと公開準備の確認は省略できます。復元すると、ドラフトが置き換わります。ドラフトを残すには、先に --workflow-id を付けずにエクスポートしておきます。

difyctl get console_app version --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d

difyctl restore console_app version --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d --version-id 8e1d3c5a-2b4f-4a6e-9c7d-1f0b2a3c4d5e

difyctl publish console_app --app-id 9b4d2e7c-1a6f-4c8e-b3d5-7e2a9f1c4b6d

環境変数は、そのバージョンの値に戻ります。名前、説明、アイコン、Web アプリ設定は、インポートで設定されたままです。これらも元に戻すには、設定し直してください。