n8n-workflow-patterns

n8n ワークフローパターン

n8n ワークフローを構築するための、実績あるアーキテクチャパターンです。

---

6 つのコアパターン

実際のワークフローの利用状況を分析してまとめたパターンです。

1. Webhook 処理（最も一般的）

   • HTTP リクエストを受信 → 処理 → 出力
   • パターン：Webhook → 検証 → 変換 → 応答／通知

2. HTTP API 統合

   • REST API から取得 → 変換 → 保存／利用
   • パターン：トリガー → HTTP リクエスト → 変換 → アクション → エラーハンドラー

3. データベース操作

   • データベースのデータを読み取り／書き込み／同期
   • パターン：スケジュール → クエリ → 変換 → 書き込み → 検証

4. AI エージェントワークフロー

   • ツールとメモリを備えた AI エージェント
   • パターン：トリガー → AI エージェント（モデル + ツール + メモリ）→ 出力

5. スケジュールタスク

   • 定期的に実行する自動化ワークフロー
   • パターン：スケジュール → 取得 → 処理 → 配信 → ログ記録

6. バッチ処理（以下を参照）

   • API レート制限に対応しながら、大規模なデータセットを分割して処理
   • パターン：準備 → SplitInBatches → バッチごとに処理 → 蓄積 → 集約

---

パターン選択ガイド

各パターンを使う場面：

Webhook 処理 - 次のような場合に使います：

• 外部システムからデータを受信する
• インテグレーションを構築する（Slack コマンド、フォーム送信、GitHub webhooks）
• イベントに即座に応答する必要がある
• 例：「Stripe の決済 webhook を受信 → データベースを更新 → 確認を送信」

HTTP API 統合 - 次のような場合に使います：

• 外部 API からデータを取得する
• サードパーティサービスと同期する
• データパイプラインを構築する
• 例：「GitHub の issue を取得 → 変換 → Jira チケットを作成」

データベース操作 - 次のような場合に使います：

• データベース間で同期する
• スケジュールに従ってデータベースクエリを実行する
• ETL ワークフローを実行する
• 例：「Postgres のレコードを読み取り → 変換 → MySQL に書き込み」

AI エージェントワークフロー - 次のような場合に使います：

• 会話型 AI を構築する
• ツールにアクセスできる AI が必要
• 複数ステップの推論タスクを実行する
• 例：「ドキュメントの検索、データベースへのクエリ、メールの送信ができる AI とチャットする」

スケジュールタスク - 次のような場合に使います：

• レポートや要約を定期的に作成する
• データを定期的に取得する
• メンテナンスタスクを実行する
• 例：「毎日：分析データを取得 → レポートを生成 → チームにメールで送信」

バッチ処理 - 次のような場合に使います：

• API のバッチ制限を超える大規模なデータセットを処理する
• 複数の API 呼び出しにわたる結果を蓄積する必要がある
• ネストされたループを使う（例：複数のカテゴリ × カテゴリごとにページネーションされた API 呼び出し）
• 例：「4 つの市場の商品を取得（API 呼び出し 1 回につき 1000 件）→ すべての結果を集約」

---

よく使うワークフローコンポーネント

すべてのパターンで、次の構成要素を使います。

1. トリガー

• Webhook - HTTP エンドポイント（即時）
• スケジュール - Cron に基づくタイミング（定期的）
• 手動 - クリックして実行（テスト用）
• ポーリング - 変更を確認（一定間隔）

2. データソース

• HTTP Request - REST API
• データベースノード - Postgres、MySQL、MongoDB
• サービスノード - Slack、Google Sheets など
• Extract From File - ダウンロードまたはアップロードしたファイルから CSV／XLSX／PDF を抽出

3. 変換（まずはネイティブ機能を使用）

• Filter / IF / Switch - アイテムを除外、ルーティング
• Edit Fields (Set) - 名前付きステップ：定数アイテム、ペイロードオブジェクト、エラーアイテム、戻り値アイテム
• Summarize / Aggregate / Split Out - グループ化と合計、配列への収集、配列の展開
• Merge / Compare Datasets - 2 つのリストを結合、同期用に差分を比較
• Remove Duplicates / Sort / Limit - 重複を排除（実行間の重複も対象）、上位 N 件を取得
• Date & Time、XML、HTML、Crypto - 日付、マークアップ、ハッシュ、署名
• Code - 閉じた対象リストに限って使用します（ループや再帰を表現できるノードがない、実行間で状態を保持する必要がある、または対応するノードがない解析）。Why Code: の注記を添えてください。

using-n8n-mcp-skills のジョブとノードの対応表では、ジョブをこれらのノードに対応付けています。設定は n8n-node-configuration → NATIVE_NODES.md にあります。ネストされた API レスポンスからフィルタリングした部分を読み取り、1 つのフィールドを取得する場合は、そのフィールドに単一の {{ $jmespath($json, "…") }} を指定すればよく、追加のノードは不要です（引用符のルールについては n8n-expression-syntax を参照）。

4. 出力

• HTTP リクエスト - API を呼び出す
• データベース - データを書き込む
• コミュニケーション - メール、Slack、Discord
• ストレージ - ファイル、クラウドストレージ

5. エラー処理

• エラートリガー - ワークフローのエラーを捕捉する
• IF - エラー条件を確認する
• Stop and Error - 明示的に失敗させる
• 失敗時に続行 - ノードごとの設定

---

ワークフロー作成チェックリスト

ワークフローを作成するときは、必ずこのチェックリストに従ってください。

計画フェーズ

• パターンを特定する（Webhook、API、データベース、AI、スケジュール実行）
• 必要なノードを列挙する（search_nodes を使用）
• データフローを把握する（入力 → 変換 → 出力）
• エラー処理の方針を計画する

実装フェーズ

• 適切なトリガーを使ってワークフローを作成する
• データソースノードを追加する
• 認証情報／資格情報を設定する
• 変換ノードを追加する（まず標準ノードを使用：Filter、IF、Summarize、Merge…；Why Code: の注記がある場合に限り Code を使用する）
• 出力／アクションノードを追加する
• エラー処理を設定する

検証フェーズ

• 各ノードの設定を検証する（validate_node）
• ワークフロー全体を検証する（validate_workflow）
• サンプルデータでテストする
• エッジケース（データが空の場合、エラー）に対処する

デプロイフェーズ

• ワークフローの設定（実行順序、タイムアウト、エラー処理）を確認する
• activateWorkflow 操作を使ってワークフローを有効化する
• 最初の実行を監視する
• ワークフローの目的とデータフローを文書化する

---

ワークフローのライフサイクル：有効化の前に検証、確認、テストする

ノードの構築は始まりであり、終わりではありません。ワークフローを稼働させる前に、4 つのゲートを通してください。そして、重要なルールを覚えておいてください。検証に合格することは必要条件ですが、十分条件ではありません。 ワークフローは検証に問題なく合格しても、アイテムを取りこぼしたり、Merge の入力を誤って選択したり、Slack メッセージをプレーンテキストで投稿したりすることがあります。検証に問題なく合格したということは、形式 が正しいというだけで、ロジック が正しいとは限りません。

1. 検証する。 構築中は完全な JSON に対して validate_workflow を実行し、インスタンスにワークフローが存在する場合は n8n_validate_workflow({ id }) を実行します。すべてのエラーを修正してから再検証してください。これにより、スキーマ、ノード設定、式、参照に関するエラー、つまり構造上の問題を検出できます。
2. 接続を確認する。 n8n_get_workflow({ id }) でワークフローを取得し、connections オブジェクトを直接読み取ります。検証では接続が壊れていないことは確認できますが、正しいことまでは確認できません。ここで、Merge の useDataOfInput が接続スロットと一致していない、Switch のフォールバックが何にも接続されていない、ファンアウトの分岐が後続に接続されていない、エラー出力の接続先がない、といった有効ではあるが誤った配線を見つけます。（見落としやすい問題については、n8n Node Configuration スキルの NODE_FAMILY_GOTCHAS.md を参照してください。）
3. テストする。 n8n_test_workflow を実行し、n8n_executions で出力を確認します。出力の形式が利用側の想定と一致していること、すべてのファンアウト分岐でデータが生成されること、そして（Webhook API の場合）ステータス／本文／ヘッダーが正しいことを確認してください。テスト中も実際の副作用が発生します。書き込みは確定され、メッセージは送信され、外部 API が呼び出されます。ユーザーに見える副作用を持つノードがある場合は、実行前にユーザーの確認を得るか、まず安全なデータでテストしてください。
4. 最初の 3 つに合格した後に限り、activateWorkflow 操作を使って n8n_update_partial_workflow で有効化します。検証に問題なく合格しただけで有効化しないでください。データを取りこぼしたり二重送信したりする稼働中のワークフローは、起動しないワークフローよりも深刻です。

いずれかのゲートを省略すると、後で稼働中の、状態を持つ可能性があり、トラフィックを処理している可能性もあるワークフローのデバッグに時間を費やすことになります。数分を節約する価値はありません。

---

データフローパターン

リニアフロー

Trigger → Transform → Action → End

使用する場面：単一経路のシンプルなワークフロー

分岐フロー

Trigger → IF → [True Path]
             └→ [False Path]

使用する場面：条件に応じて異なるアクションを実行する場合

並列処理

Trigger → [Branch 1] → Merge
       └→ [Branch 2] ↗

使用する場面：同時に実行できる独立した処理

ループパターン

Trigger → Split in Batches → Process → Loop (until done)

使用する場面：大規模なデータセットを分割して処理する場合

エラーハンドラーパターン

Main Flow → [Success Path]
         └→ [Error Trigger → Error Handler]

使用する場面：エラー処理用に別のワークフローが必要な場合

---

バッチ処理パターン

SplitInBatches ループ

SplitInBatches ノードは、大規模なデータセットを処理しやすい小さなチャンクに分割します。出力を理解することが重要です。

• main[0] = 完了 — すべてのバッチが完了した後に1回だけ実行されます
• main[1] = 各バッチ — バッチごとに実行されます（これがループ本体です）

Prepare Items → SplitInBatches → [main[1]: Process Batch] → (loops back)
                                  [main[0]: Done] → Limit 1 → Aggregate

完了出力の後には、必ず Limit 1 ノードを追加してください。

batchSize の選び方（コストを左右する要素）

SplitInBatches ループは、反復ごとにループ本体全体を再実行します。エンジンのオーバーヘッドは反復ごとに約 0.8 ms で、これにループ本体自体のコストが加わります。そのため、合計はおよそ ⌈items / batchSize⌉ × (overhead + body) となります。batchSize は速度を直接調整できます。

• 実際の制約で許される最大のバッチサイズを選んでください（API のページサイズ、レート制限、メモリなど）。バッチが大きいほど反復回数が減り、オーバーヘッドも小さくなります。ループ本体にはすべてのアイテムが渡されます。
• batchSize: 1 は最もコストがかかります。アイテムごとにエンジン全体の処理が1回必要です。1つずつ処理する必要がある場合（ネストされたループの制御、または ID を1つだけ受け付ける API）に限って使用してください。
• 外部の制約がなく、単に「アイテムを順番に処理する」ためだけにループしている場合、ループは不要です。ソースを処理先に接続してください。アイテムごとの実行で処理され、ネイティブの変換ノードは1回の呼び出しですべてのアイテムを処理します。

反復をまたぐデータ

ループの後に $('Node Inside Loop').all() を呼び出すと、最後のバッチのアイテムのみが返されます。すべての反復にわたってデータを蓄積するには、ループ内の Code ノードで $getWorkflowStaticData('global') を使用してください。詳しいパターンについては、n8n Code JavaScript スキルを参照してください。

ネストされたループ

API にバッチ上限がある場合に、N 個のカテゴリ × カテゴリあたり M 個のアイテムを処理するとき：

Define Categories (N items)
  → Outer Loop (SplitInBatches, batchSize=1)
    → Prepare category data
    → Inner Loop (SplitInBatches, batchSize=1000)
      → API Call → Verify → (loops back to Inner Loop via main[1])
    → Inner done[0] → Rate Limit Delay → back to Outer Loop
  → Outer done[0] → Limit 1 → Final Aggregate

配線上の注意点：内側の done[0] は集約ノードではなく、外側のループ入力に接続する必要があります。外側の done[0] から最終的な集約ノードに接続します。

API のページネーション

1つのエンドポイントをページングする場合は、ループではなく HTTP Request のページネーションオプションを使います（ページ番号、オフセット、カーソル、次の URL を使用する API に対応し、ページ数の上限も設定できます。n8n-node-configuration → NATIVE_NODES.md を参照）。以下のループは、このオプションでは表現できない一括処理向けです。たとえば複数 ID による絞り込みができない API で、id_from と日付範囲を使って順に処理し、範囲ごとに個別のクエリを実行する場合です。

Schedule → Set Date Window → Fetch Page → Process
  → IF has more? → [true] Update id_from → Fetch Page (loop)
                  → [false] → Aggregate → Output

ドライラン／検証時の許容性

API 書き込みノードを無効にしてテストする場合（ドライラン）、後続の検証ノードにはレスポンスではなくリクエスト本文が渡されます。検証処理はどちらにも対応できるようにしてください。

// In verification Code node
const body = $input.first().json;
const looksLikeRequest = body.method && body.parameters && !body.status;
if (looksLikeRequest) {
  return [{ json: { status: 'SKIPPED', message: 'Upstream disabled for testing' }}];
}
// Normal response verification below...

---

クリティカルパスのパフォーマンス

I/O が少ない状態で数千件のアイテムを処理するワークフローでは、速度を左右するのは n8n がアイテムごと／反復ごとの境界を通過する回数です。境界を通過するたびに実行コンテキストが準備され、アイテムがコピーされます。主に次の4つのアーキテクチャ上の選択が影響します。

1. クリティカルな処理チェーンを1つの Code ノードにまとめるのは例外であり、標準ではありません。 ノード間の接続ごとにすべてのアイテムが再コピーされるため、実測したクリティカルパスで、実行あたり数千件のアイテムを処理し、I/O よりも変換処理が支配的な場合は、1つの All-Items Code ノードのほうが長いチェーンより高速になることがあります。これは許可リストにある「重い全アイテム処理」のケースです。ノードの Why Code: メモに記録してください。それ以外では、読みやすさの点でネイティブノードが優れています。
2. Code ノードを使う場合は、「Each Item」ではなく「Run Once for All Items」を使用してください。 Each Item ではアイテムごとにサンドボックス全体のコストがかかります。Each-Item の Code ノードを連ねるのは最悪のケースです。アイテムごとのコストがノード数に応じて増大するためです。
3. SplitInBatches ループの batchSize を最大化してください（上記のバッチ処理パターンを参照）。反復回数がコストになります。
4. 式を細かく最適化する必要はありません。複雑さにコストはかかりません。コストを左右するのはノード数と反復回数です。

ただし、まずはプロファイリングを行ってください。 本番ワークフローの多くは I/O がボトルネックです。逐次実行される HTTP／DB／Sheets の呼び出し（それぞれ数百 ms）が、上記すべての処理時間を上回ります。これらのルールが重要になるのは、変換処理が最低限の処理時間を決めている場合や、アンチパターン（Each-Item Code、batchSize 1、長いアイテム単位のチェーン）によって軽い処理が遅くなっている場合です。数百件未満であれば、どれも問題になりません。実測モデルの詳細は n8n Code JavaScript スキルに記載されています。

---

統合固有の注意点

Google Sheets

• 数式列があるシートでは、append は絶対に使用しないでください。数式が壊れます。googleApi 認証情報を使い、HTTP Request ノードから Google Sheets API の values.update（PUT）を使用してください。
• 数式に依存する列には、文字列ではなく数値を書き込んでください。文字列の「4.98」は ADD() 数式を壊します。列の式で変換してください：{{ $json.price.toNumber() }} または {{ parseFloat($json.price) }}
• アイテムごとの実行に関する注意点：Google Sheets ノードは入力アイテムごとに1回実行されます。1回の一括書き込みが必要な場合は、先に Aggregate ノードで行を1つのアイテムにまとめてください。
• UNFORMATTED_VALUE は、「N/A」のようなテキストではなく数値を返します。Filter ノードで明示的にフィルタリングしてください。

Google Drive

• convertToGoogleDocument: true は Google ドキュメント（テキスト）を作成します。Google Sheets ではありません。ダウンロード用に CSV をアップロードする場合は、このオプションを完全に省略してください。
• CSV のダウンロードリンク形式：https://drive.google.com/uc?id={fileId}&export=download — /view リンクの代わりに使用してください。

双方向のしきい値チェック

値（価格、数量、指標）を比較する場合は、必ず両方向をチェックしてください。

// ❌ Only catches increases
if (diff > threshold) { flag(); }

// ✅ Catches both spikes AND crashes — both are data-quality signals
if (Math.abs(diff) > threshold) { flag(); }

---

よくある注意点

1. Webhook のデータ構造

問題：Webhook のペイロードデータにアクセスできません。

解決策：データは $json.body の下にネストされています。

❌ {{$json.email}}
✅ {{$json.body.email}}

参照：n8n Expression Syntax スキル

2. 複数の入力アイテム

問題：ノードがすべての入力アイテムを処理しますが、1つだけ処理したいです。

解決策：「Execute Once」モードを使うか、最初のアイテムだけを処理してください。

{{$json[0].field}}  // First item only

3. 認証の問題

問題：API 呼び出しが 401/403 で失敗します。

解決策：

• 認証情報を正しく設定します。
• パラメーターではなく、「Credentials」セクションを使用します。
• ワークフローを有効にする前に、認証情報をテストします。

4. ノードの実行順序

問題：ノードが予想外の順序で実行されます。

解決策：ワークフローの設定 → Execution Order を確認します。

• v0：上から下（旧方式）
• v1：接続ベース（推奨）

5. 式のエラー

問題：式が文字列としてそのまま表示されます。

解決策：式を {{}} で囲みます。

• 詳細は n8n Expression Syntax スキルを参照してください。

---

他のスキルとの連携

これらのスキルは Workflow Patterns と連携して使用できます。

n8n MCP Tools Expert - 次の用途に使用します：

• パターンに使うノードを検索する（search_nodes）
• ノードの操作方法を理解する（get_node）
• ワークフローを作成する（n8n_create_workflow）
• テンプレートをデプロイする（n8n_deploy_template）
• AI パターンのガイダンスには tools_documentation({topic: "ai_agents_guide", depth: "full"}) を使用する
• n8n_manage_datatable でデータテーブルを管理する
• n8n_manage_folders でワークフローをフォルダーに整理する

n8n Expression Syntax - 次の用途に使用します：

• データ変換ノードで式を記述する
• Webhook データに正しくアクセスする（{{$json.body.field}}）
• 前のノードを参照する（{{$node["Node Name"].json.field}}）

n8n Node Configuration - 次の用途に使用します：

• パターン内のノードに特定の操作を設定する
• ノード固有の要件を理解する

n8n Validation Expert - 次の用途に使用します：

• ワークフローの構造を検証する
• 検証エラーを修正する
• デプロイ前にワークフローが正しいことを確認する

---

パターンの統計

一般的なワークフローパターン：

最も一般的なトリガー：

1. Webhook - 35%
2. Schedule（定期タスク） - 28%
3. Manual（テスト／管理） - 22%
4. サービストリガー（Slack、メールなど） - 15%

最も一般的な変換：

1. Set（フィールドのマッピング） - 68%
2. Code（カスタムロジック） - 42%
3. IF（条件分岐） - 38%
4. Switch（複数条件） - 18%

最も一般的な出力：

1. HTTP Request（API） - 45%
2. Slack - 32%
3. データベースへの書き込み - 28%
4. メール - 24%

ワークフローの平均的な複雑さ：

• シンプル（3～5ノード）：42%
• 中程度（6～10ノード）：38%
• 複雑（11ノード以上）：20%

---

クイックスタートの例

例1：シンプルな Webhook → Slack

1. Webhook (path: "form-submit", POST)
2. Slack (post message to #notifications; the text maps $json.body fields with expressions)

例2：スケジュール済みレポート

1. Schedule (daily at 9 AM)
2. HTTP Request (fetch analytics)
3. Summarize (totals per group)
4. Email (send formatted report)
5. Error Trigger → Slack (notify on failure)

例3：データベースの同期

1. Schedule (every 15 minutes)
2. Postgres (query new records)
3. IF (check if records exist)
4. MySQL (insert records)
5. Postgres (update sync timestamp)

例4：AI アシスタント

1. Webhook (receive chat message)
2. AI Agent
   ├─ OpenAI Chat Model (ai_languageModel)
   ├─ HTTP Request Tool (ai_tool)
   ├─ Database Tool (ai_tool)
   └─ Window Buffer Memory (ai_memory)
3. Webhook Response (send AI reply)

例5：API 連携

1. Manual Trigger (for testing)
2. HTTP Request (GET /api/users; pagination option if the API pages)
3. Postgres (upsert users; map the fields in the node's column slots)

ループも Set も不要です。Postgres がすべてのアイテムを処理し、列のスロットがマッピング式を受け取ります。

---

詳細なパターンファイル

各パターンの詳細なガイダンスについては、以下をご覧ください。

• webhook_processing.md - Webhook のパターン、データ構造、レスポンス処理
• http_api_integration.md - REST API、認証、ページネーション、リトライ
• database_operations.md - クエリ、同期、トランザクション、バッチ処理
• ai_agent_workflow.md - AI エージェント、ツール、メモリ、langchain ノード
• scheduled_tasks.md - Cron スケジュール、レポート、メンテナンスタスク

---

実際のテンプレート例

n8n テンプレートライブラリより：

テンプレート #2947：天気情報を Slack に送信

• パターン：スケジュールタスク
• ノード：スケジュール → HTTP Request（天気 API）→ Set → Slack
• 複雑さ：シンプル（4 ノード）

Webhook 処理：最も一般的なパターン

• 主な用途：フォーム送信、決済 Webhook、チャット連携

HTTP API：一般的なパターン

• 主な用途：データ取得、サードパーティとの連携

データベース操作：一般的なパターン

• 主な用途：ETL、データ同期、バックアップのワークフロー

AI エージェント：利用が増加しているパターン

• 主な用途：チャットボット、コンテンツ生成、データ分析

n8n-mcp ツールの search_templates と get_template を使って、例を見つけましょう！

---

ベストプラクティス

✅ すること

• 問題を解決できる最もシンプルなパターンから始める
• 構築前にワークフローの構成を計画する
• すべてのワークフローでエラー処理を使用する
• 有効化前にサンプルデータでテストする
• ワークフロー作成チェックリストに従う
• 説明的なノード名を使用する
• 複雑なワークフローをドキュメント化する（notes フィールド）
• デプロイ後にワークフローの実行を監視する

❌ しないこと

• ワークフローを一度で作り上げようとする（反復しましょう！編集間隔は平均 56 秒です）
• 有効化前の検証を省略する
• エラーが発生するケースを無視する
• シンプルなパターンで十分な場合に複雑なパターンを使う
• パラメーターに認証情報をハードコードする
• データが空の場合の処理を忘れる
• 明確な境界を設けずに複数のパターンを混在させる
• テストせずにデプロイする

---

まとめ

要点：

1. 6 つの主要なパターンでワークフローのユースケースの 90% 以上をカバーできます
2. Webhook 処理が最も一般的なパターンです
3. すべてのワークフローでワークフロー作成チェックリストを使用します
4. パターンを計画 → ノードを選択 → 構築 → 検証 → デプロイ
5. 他のスキルと連携して、ワークフロー開発を完成させます

次のステップ：

1. 自分のユースケースに合うパターンを特定する
2. 詳細なパターンファイルを読む
3. n8n MCP Tools Expert を使ってノードを探す
4. ワークフロー作成チェックリストに従う
5. n8n Validation Expert を使って検証する

関連スキル：

• n8n MCP Tools Expert - ノードを検索して設定する
• n8n Expression Syntax - 正しい式を書く
• n8n Validation Expert - エラーを検証して修正する
• n8n Node Configuration - 特定の操作を設定する