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 Webhook など）
• イベントに即時応答する必要がある
• 例：「Stripe の決済 Webhook を受信 → データベースを更新 → 確認を送信」

HTTP API 統合 - 次の場合に使用します：

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

データベース操作 - 次の場合に使用します：

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

AI エージェントのワークフロー - 次の場合に使用します：

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

スケジュールタスク - 次の場合に使用します：

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

バッチ処理 - 次の場合に使用します：

• API のバッチ制限を超える大規模なデータセットを処理する
• 複数の API 呼び出しにまたがる結果を蓄積する必要がある
• 入れ子になったループを処理する（例：複数カテゴリ × カテゴリごとのページ分割された API 呼び出し）
• 例：「4 つの市場から商品を取得（API 呼び出しあたり 1000 件）→ すべての結果を集約」

---

よく使われるワークフローコンポーネント

すべてのパターンで、以下の構成要素を使用します。

1. トリガー

• Webhook - HTTP エンドポイント（即時）
• Schedule - Cron ベースのタイミング設定（定期実行）
• Manual - クリックして実行（テスト用）
• Polling - 変更を確認（一定間隔）

2. データソース

• HTTP Request - REST API
• データベースノード - Postgres、MySQL、MongoDB
• サービスノード - Slack、Google Sheets など
• Code - カスタム JavaScript／Python

3. 変換

• Set - フィールドのマッピング／変換
• Code - 複雑なロジック
• IF/Switch - 条件付きルーティング
• Merge - データストリームの結合

4. 出力

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

5. エラー処理

• Error Trigger - ワークフローのエラーを捕捉
• IF - エラー条件を確認
• Stop and Error - 明示的に失敗させる
• Continue On Fail - ノードごとの設定

---

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

あらゆるワークフローを構築する際は、以下のチェックリストに従ってください。

計画フェーズ

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

実装フェーズ

• 適切なトリガーを使ってワークフローを作成する
• データソースノードを追加する
• 認証情報を設定する
• 変換ノード（Set、Code、IF）を追加する
• 出力／アクションノードを追加する
• エラーハンドリングを設定する

検証フェーズ

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

デプロイフェーズ

• ワークフローの設定を確認する（実行順序、タイムアウト、エラーハンドリング）
• activateWorkflow オペレーションを使ってワークフローを有効化する
• 最初の実行を監視する
• ワークフローの目的とデータフローを文書化する

---

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

ノードの構築は始まりであり、完了ではありません。ワークフローを稼働させる前に、4つの関門を通してください。そして、重要なルールを覚えておいてください。検証に合格することは必要条件ですが、十分条件ではありません。 検証に問題がなくても、ワークフローでアイテムが失われたり、Merge の入力が誤って選ばれたり、Slack メッセージがプレーンテキストとして送信されたりする可能性があります。検証がクリーンであることは、構造が正しいことを意味するのであって、ロジックが正しいことを意味するのではありません。

1. 検証する。 構築中に完全な JSON に対して validate_workflow を実行するか、インスタンス上にワークフローが存在する場合は n8n_validate_workflow({ id }) を実行します。すべてのエラーを修正して再検証してください。これにより、スキーマ、ノード設定、式、参照に関するエラーなど、構造上の問題を検出できます。
2. 接続を確認する。 n8n_get_workflow({ id }) でワークフローを取得し、connections オブジェクトを直接確認します。検証で確認できるのは、接続が壊れていないことです。接続が正しいことまでは確認できません。ここで、有効ではあるものの誤った配線を検出します。たとえば、useDataOfInput が接続スロットと一致しない Merge、何にも接続されていない 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

使用するケース：経路が1つだけのシンプルなワークフロー

分岐フロー

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

• 実際の制約で許容される最大のバッチサイズを選んでください（API のページサイズ、レート制限、メモリなど）。バッチが大きいほど反復回数が減り、オーバーヘッドも小さくなります。本体では引き続きすべてのアイテムを処理します。
• batchSize: 1 は最もコストが高く、アイテムごとにエンジン全体の処理が1回発生します。アイテムを1つずつ処理する必要がある場合（ネストしたループの制御、またはIDを必ず1つだけ受け取るAPIなど）に限って使用してください。
• 外部の制約がなく、単にアイテムを「順に処理する」ためだけにループしている場合、通常はループは不要です。単一の All Items Code ノードで全体を処理すれば、はるかに低コストです。

反復をまたぐデータ

ループの後で $('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 のページネーション

複数 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. 長い変換チェーンより、ノード数が少なく一度に多く処理する All-Items ノードを優先してください。 ノード間を移動するたびにすべてのアイテムが再コピーされるため（ホップごとに約0.05 ms/アイテム）、Code／Set ノードを6つ連結すると、同じ処理をする All-Items Code ノード1つの約7倍のコストがかかります。ホットパスをまとめてください。
2. Code の「Each Item」ではなく「Run Once for All Items」を使用してください。処理コストは約0.02 ms/アイテム対約0.6 ms/アイテム（約25～30倍）です。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() 数式を壊します。Code ノードで parseFloat() を使用してください。
• アイテムごとの実行に関する注意点：Google Sheets ノードは入力アイテムごとに1回実行されます。単一の一括書き込みが必要な場合は、先に Code ノードでアイテムを集約してください。
• UNFORMATTED_VALUE は「N/A」のようなテキストではなく数値を返します。Code ノードで明示的にフィルタリングしてください。

Google Drive

• convertToGoogleDocument: true は Google ドキュメント（テキスト）を作成します。Google スプレッドシートではありません。ダウンロード用に 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. ノードの実行順序

問題：ノードが予期しない順序で実行される

解決策：ワークフローの設定 → 実行順序を確認します

• 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. スケジュール（定期タスク） - 28%
3. 手動（テスト／管理） - 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. Set (map form fields)
3. Slack (post message to #notifications)

例 2：スケジュールされたレポート

1. Schedule (daily at 9 AM)
2. HTTP Request (fetch analytics)
3. Code (aggregate data)
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)
3. Split In Batches (process 100 at a time)
4. Set (transform user data)
5. Postgres (upsert users)
6. Loop (back to step 3 until done)

---

詳細なパターンファイル

各パターンの詳しいガイダンスについては、次を参照してください。

• 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 に送信

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

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

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

HTTP API：一般的なパターン

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

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

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

AI エージェント：利用が増加中

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

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

---

ベストプラクティス

✅ 推奨事項

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

❌ 禁止事項

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

---

まとめ

重要なポイント：

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 - 特定の操作を設定します