Dify入門_開発編_DXエンジニア向け

外部システム POST /workflows/run Dify入門 Dify Workflow LLM・コード・HTTP 【開発編】 DXエンジニア向け 設計 → 実装 → API連携 → 移行・運用 90分 社内API Bearer認証 実装担当 テックリード PM・顧客連携 結果をJSONで返却 うさうさ研修工房 ／ 公式docs確認日 2026-10-24 ／ 入門編の続き

今日のゴールと 3つの立場 開発編は「壊れない・移行できる・説明できる」を目標にします 実装担当 テックリード PM・顧客連携 ノードとAPIを実装する方 設計・レビュー・移行を担う方 顧客・社内と調整する方 ゴール ゴール ゴール 1. Code/HTTPノードで外部連携を実 装できる 1. 制約と既定値を根拠に設計判断で きる 1. 障害時の挙動とセキュリティを説明 できる 2. エラー処理とリトライを設定できる 2. DSLとCLIで開発→本番の移行を設 計できる 2. 移行・公開の手順とリスクを説明で きる 読み方 読み方 読み方 STEP3〜7を実装手順で STEP5〜8を設計根拠で STEP1・7・8を事実→提案で 出典: 講師設計（公式docsの章立てに基づく学習設計） 2

学習ロードマップ（ 8段階スロープ） 山場はSTEP7のAPI連携ワークフロー。前は部品、後は移行・運用 ★ 山場 7 6 5 4 3 8 2 1 Why What 部品 部品 設計 応用 山場 緩和 設計の前提 全体設計 Codeノード HTTPノード エラー・反復 Agent・ツール API連携構築 移行・運用 出典: 講師設計（うさうさ研修工房坂道型スロープ） 3

Why：開発編で押さえる 3つの数字 外部連携は「失敗する前提」で設計する。公式の上限値を知る 10 5000 10 最大リトライ回数 HTTP・コードノード 最大リトライ間隔（ms） イテレーション並列 同時処理の上限 設計の原則（講師見解） 失敗する前提で、リトライ・代替経路・ログを先に決める 公式の根拠：各ノードにリトライとエラー処理（代替パス）の設定がある。 実装 数字は暗記不要。設計の前提として 見る リード 出典: docs.dify.ai/en/self-host/use-dify/nodes/http-request ／ iteration ／ code 再試行は上限あり。超えたら業務側 で再実行設計 PM・顧客 障害時の挙動を数字で顧客に説明で きる 4

What：業務システムに組み込む全体設計 入口（API）→ 処理（ノード）→ 外部連携 → 運用 入口：Service API 処理：Workflow 連携：外部 POST /workflows/run Bearer APIキー LLM / コード / If-Else イテレーション / Agent HTTPリクエスト ツール / MCP 移行（DSL・CLI） セキュリティ 監視・ログ .ifpkgと difyctl で環境間移行 Secret環境変数・サンドボックス・ URL管 理 会話全文の保持と外部モニタリング連携 実装 入口は公開済みWorkflowのAPI。未 公開は呼べない リード 中は部品（LLM/コード/HTTP）の組合 せ 出典: docs.dify.ai/en/api-reference/workflow-runs/run-workflow ／ docs.dify.ai/en/self-host/use-dify/publish PM・顧客 運用は移行・監視・セキュリティの3点 で整理 5

Codeノード：整形と変換を書く
Python / JavaScript。戻り値は宣言した出力変数のdict

def main(items: list) -> dict:
# 入力変数を受け取り
# 宣言した出力変数名のキーで返す
return {"result": ...}

出力変数名とdictのキーが一致しないと値を受け取れない（要・手元検
証）

実装

入力を宣言→main→出力名のdictを
返す

出典: docs.dify.ai/en/self-host/use-dify/nodes/code

リード

文字列

ネスト深さ

最大400,000文字

最大5

小数精度

リトライ

20桁

最大10回／5000ms

注意：上限は既定値（API環境変数 CODE_MAX_*）。配列長・タイムアウトの
既定値は公式に記載なし。

上限値は環境変数。文字列40万字・
深さ5が既定

PM・顧客

サンドボックスのネットワークは自環
境で必ず確認

6

HTTPリクエストノード：社内 APIを呼ぶ 認証・本文・タイムアウト・SSLまで設定できる 1 メソッド GET・HEAD／POST・PUT ・PATCH／DELETE 2 3 なし／APIキー （Basic・Bearer・カスタム ヘッダー） タイムアウト 接続・読取・書込の3種。既定値は公式に記 載なし 実装 認証 APIキーはSecret型環境変数に入れ る（ログでマスク） 出典: docs.dify.ai/en/self-host/use-dify/nodes/http-request 本文 4 JSON・フォーム・バイナリ・ テキスト。変数は {{ }} で挿 入 出力 本文・ステータスコード・ヘッ ダー・ファイル・サイズ リトライ SSL検証 最大10回・間隔は最大5000ms ノード単位で設定（ssl_verify） リード 社内の自己署名証明書はssl_verify で対応 PM・顧客 応答はステータスコードで分岐できる 7

エラー処理： 3層で守る リトライ → 代替経路 → 最終的な失敗の扱い 1 リトライ 2 代替経路 3 最終の扱い 最大回数・間隔・バックオフ（ LLM）。 HTTP・Codeは最大10回／5000ms 失敗時に別のワークフロー経路へ。処 理を止めずに続行 LLMは既定値返却・エラー経路・代替 モデル。イテレーションは 3択 設計メモ（講師見解） 実装 再試行しても直らない失敗は、代替経路でユーザーに状況を返し、ログに残して後から再実行できるようにする。 リトライは一時障害向け。恒久障害は 代替経路で リード 出典: docs.dify.ai/en/self-host/use-dify/nodes/llm ／ http-request ／ code ／ iteration LLMは代替モデルへ切替できる（公 式） PM・顧客 顧客には「3層の守り」で障害時の挙 動を説明 8

イテレーション：配列を 1件ずつ処理 入力は配列。出力も常に配列 エラー処理の3択（公式） 入力：配列 [ 1, 2, 3 ] 各回：items（現在の要素）／ index（0始まり） 出力：配列（全結果） 1 2 順次（既定） 並列 順序を保つ。メモリ少。回答ノー ドで段階出力 最大10件同時。順序不問の独 立処理向け 実装 並列は順序不問の独立処理だけに 使う 出典: docs.dify.ai/en/self-host/use-dify/nodes/iteration リード 3 終了 エラーで停止しメッセージを返す エラーを無視して継続 失敗した要素は null：[r1, null, r3] 失敗結果を除外 成功のみ返す：[r1, r3] null混入と除外の違いを後続処理に 合わせて選ぶ PM・顧客 出力は配列。テキスト化は別ノードで 9

Agentノード：ツールを自律で選ぶ クラシックAgentの戦略は2つ。上限回数で暴走を防ぐ Function Calling ReAct • モデル標準の関数呼び出しにツール定義を渡す • 思考→行動→観察のサイクルで進める • 公式の推奨：GPT-4やClaude 3.5などのモデル • 関数呼び出し非対応のモデルや、推論過程を残したいとき • 標準対応のモデル向け • 追加の戦略は Marketplaceから導入可 最大反復 ツール メモリ 単純3〜5／複雑10〜15（目安） 認証・説明文・パラメータが必要 保持メッセージ数。増やすとコスト増 実装 固定フローで足りるならAgentを使わ ない（講師見解） 出典: docs.dify.ai/en/self-host/use-dify/nodes/agent リード 最大反復は必ず設定。目安3〜 5／10〜15 PM・顧客 新Agentノードはベータ。本番採用は 最新docsで確認 10

山場：問い合わせを社内 APIへ連携する 構造化抽出 → 社内API呼び出し → 整形 → 返却。この4ノードがゴール 開始 LLM HTTPリクエスト コード ユーザー入力（Workflow） 構造化出力（JSON） 社内API・Bearer 整形→出力 ★1 構造化出力を確認 JSON Schemaで項目を指定。JSON対応モ デルが安定 実装 4ノード。まず完成図を見る ★2 認証をSecretで APIキーをSecret環境変数に。ログではマス クされる リード Secret環境変数・出力変数名の一致 が要点 出典: docs.dify.ai/en/self-host/use-dify/nodes/llm ／ http-request ／ code ／ docs.dify.ai/ja/learn/tutorials/simple-chatbot ★3 戻り値を一致 Codeのdictキーを出力変数名に合わせ Previewで確認 PM・顧客 顧客デモは失敗時の代替経路も見 せる 11

ハンズオン手順とつまずき 7ステップ。止まったら右の「回復」を見る つまずきと回復 1 Workflowアプリを新規作成（空白から） 2 LLMノード：構造化出力を有効化しスキーマを設定 Codeの値が受け取れない 戻りdictのキーが宣言した出力変数名と一致しているか確認 3 環境変数にAPIキーをSecretで登録 4 HTTPリクエスト：URL・Bearer認証・本文に変数を挿入 APIが呼べない 公開済みか確認。未公開は invalid_param（公式） 5 Codeノード：入力変数宣言と main、出力変数を設定 6 出力ノードを接続しテスト実行 HTTPが失敗する 認証・タイムアウト・SSL設定を確認。代替経路を設定 7 公開し、APIで呼び出して確認 実装 手順は一緒に。揃うまで待つ リード 詰まったら入出力のキーを確認 出典: docs.dify.ai/ja/learn/tutorials/simple-chatbot ／ docs.dify.ai/en/self-host/use-dify/nodes/ PM・顧客 本番想定のキー管理とログ確認を習 慣に 12

Service API：ワークフローを呼ぶ
POST /workflows/run。Bearer認証、blocking／streaming

curl -X POST '{api_base_url}/workflows/run' \
-H 'Authorization: Bearer {API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"inputs": { ... },
"response_mode": "blocking",
"user": "user-001"
}'

inputs（必須）
入力変数のキーと値。ファイルは配列

user（必須）
アプリ内で一意の識別子

response_mode
blocking（既定）／streaming

files（任意）
Vision対応モデルのみ

実装

inputsとuserは必須。userは一意に

出典: docs.dify.ai/en/api-reference/workflow-runs/run-workflow

リード

APIキーはアプリ単位。コードに直書
きしない

PM・顧客

クライアントはstreamingのエラー処
理を忘れずに

13

レスポンスとエラーの設計 ステータス値とエラーコードを呼び出し側で分岐する data.status の値（公式） running failed unauthorized：APIキー不正 400 invalid_param など：未公開・ userなし ほか 403 トリガー開始の WorkflowはAPI不可 429 同時リクエスト上限／クラウド実行枠 500 internal_server_error succeeded stopped partial-succeeded paused ストリーミング注意： エラーはHTTP 200の本文内で届く。 workflow_finished／workflow_paused／errorで終了 実装 401 data.statusで成否を判定。failedは errorを確認 出典: docs.dify.ai/en/api-reference/workflow-runs/run-workflow リード 429は2種類。再試行の方針が異なる PM・顧客 ストリーミングはHTTP 200でもエラー が来る 14

プラグイン開発：自前のツールを足す dify CLIで雛形を作り、本体に接続してデバッグ プラグインの種類（公式 6種） # 雛形を作る dify plugin init # デバッグ用 .env（Pluginsのデバッグ画面の値） INSTALL_METHOD=remote REMOTE_INSTALL_URL=host:port REMOTE_INSTALL_KEY=<APIキー> ツール モデル 拡張 エージェント戦略 データソース トリガー # 実行 pip install -r requirements.txt python -m main 実装 まずHTTPノード、足りなければプラ グイン（講師見解） 出典: docs.dify.ai/en/develop-plugin/getting-started/cli リード 開発はPython 3.12＋CLI。リモート デバッグ可 PM・顧客 パッケージ化手順は公式で確認（未 確認） 15

移行：開発から本番へ .ifpkgで書き出し、difyctlで運用に乗せる difyctl（公式CLI） 含まれない（再設定が必要） • 利用中のインテグレーション（インポート時に導入可） • ナレッジベース • モデル・ツールの認証情報 • サービスAPIキー • ログ・アノテーション・過去バージョン difyctl get app difyctl describe app <id> difyctl run app <id> --inputs-file f.json difyctl export studio-app <id> -o app.yaml difyctl import studio-app --from-file app.yaml Secretの扱い：書き出し時の値は平文。パッケージもSecret同様に管理 実装 移行後に再設定するもの：ナレッジ・ 認証情報・Secret・APIキー リード Webアプリ設定は公開前に即反映。 事前確認を 出典: docs.dify.ai/en/self-host/use-dify/workspace/app-management ／ docs.dify.ai/en/cli/reference/apps PM・顧客 版差（1.18.0）に注意。事前に移行リ ハーサル 16

MCP公開とセキュリティ URLはAPIキー同様に扱う。Secret・サンドボックス・ログも点検 MCPサーバー Secret環境変数 コードサンドボックス ログ Access PointでMCP Server を有効化（既定は無効）。 URLが認証を兼ねる。漏え い時は再生成 APIキーはSecret型。ログで マスク。書き出し時の値の扱 いに注意 SANDBOX_*で制御。ネット ワークはSSRFプロキシ経 由。無効化も可（要自環境検 証） 会話全文が残る。保持期間 は環境変数で設定。機微情 報に注意 実装 MCP有効化→URL発行。漏えい時 は再生成 リード Secret環境変数・サンドボックス・ログ を点検 出典: docs.dify.ai/en/self-host/use-dify/publish/publish-mcp ／ nodes/code ／ monitor/logs PM・顧客 顧客には認証方式と再生成手順を明 示 17

設計レビューと顧客説明の型 事実 → 理由 → 提案。公式の根拠を添える Q. 障害のとき止まらない？ 事実（公式） リトライ最大10回、代替経路、 LLMは代 替モデルへ切替可 提案（講師見解） 失敗時の返却内容とログ、再実行手順 を先に設計 実装 レビューは「リトライ・代替経路・ログ」 で見る 出典: 講師設計（事実は各ページの公式docs。助言部分は講師見解） Q. 本番移行は安全？ 事実（公式） .ifpkgにナレッジ・認証・ APIキー・ログは 含まれない 提案（講師見解） 移行チェックリストと検証環境でのリハー サル リード 数字（10回／5000ms／10並列）を根 拠に使う Q. 鍵や情報漏えいは？ 事実（公式） Secret型はログでマスク／ MCPのURL は再生成可／ログは会話全文 提案（講師見解） 保持期間と権限を事前合意し、鍵の棚 卸しを運用化 PM・顧客 提案は段階導入（まず検証環境）が 通しやすい 18

まとめと公式リソース 確認日 2026-10-24。UI・既定値は版で変わるので最新docsで再確認 到達チェック Codeノードの入出力の契約を説明できる 公式リソース（ docs.dify.ai） /en/self-host/use-dify/nodes/（code・http-request・ iteration・agent・llm） HTTPノードの認証と Secretの扱いを言える /en/api-reference/workflow-runs/run-workflow /en/self-host/use-dify/publish/publish-mcp リトライ・代替経路・最終扱いを設計できる /en/self-host/use-dify/workspace/app-management /en/cli/reference/apps イテレーションの並列と順次を選べる /en/develop-plugin/getting-started/cli /ja/learn/tutorials/simple-chatbot Service APIを呼び、statusとエラーを扱える 移行で含まれないものを列挙できる 19