n8n-node-configuration

n8n ノードの設定

プロパティの依存関係を考慮した、操作に応じたノード設定の専門的なガイダンスです。

---

設定の考え方

段階的な情報開示：最小限の設定から始め、必要に応じて複雑さを加えます。

設定のベストプラクティス：

• detail: "standard" を指定した get_node は、最もよく使われる探索パターンです。
• 設定編集の平均間隔は56秒です。
• 1～2Kトークンの応答で、ユースケースの95%をカバーします。

重要なポイント：ほとんどの設定で必要なのは標準の詳細度だけで、完全なスキーマは不要です！

---

基本概念

1. 操作に応じた設定

すべてのフィールドが常に必須とは限りません。操作によって異なります！

例：Slack ノード

// For operation='post'
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",  // Required for post
  "text": "Hello!"        // Required for post
}

// For operation='update'
{
  "resource": "message",
  "operation": "update",
  "messageId": "123",     // Required for update (different!)
  "text": "Updated!"      // Required for update
  // channel NOT required for update
}

ポイント：リソースと操作によって、必須フィールドが決まります！

2. プロパティの依存関係

ほかのフィールドの値に応じて、フィールドが表示されたり非表示になったりします

例：HTTP Request ノード

// When method='GET'
{
  "method": "GET",
  "url": "https://api.example.com"
  // sendBody not shown (GET doesn't have body)
}

// When method='POST'
{
  "method": "POST",
  "url": "https://api.example.com",
  "sendBody": true,       // Now visible!
  "body": {               // Required when sendBody=true
    "contentType": "json",
    "content": {...}
  }
}

仕組み：displayOptions がフィールドの表示を制御します。

3. 段階的な探索

適切な詳細度を使います：

1. get_node({detail: "standard"}) - デフォルト

   • すばやく概要を確認できます（約1～2Kトークン）。
   • 必須フィールドと一般的なオプションが含まれます。
   • 最初に使用します。必要な内容の95%をカバーします。

2. get_node({mode: "search_properties", propertyQuery: "..."})（特定のフィールドを探す場合）

   • 名前からプロパティを検索します。
   • 認証、本文、ヘッダーなどを探す場合に使用します。

3. get_node({detail: "full"})（完全なスキーマ）

   • すべてのプロパティが含まれます（約3～8Kトークン）。
   • 標準の詳細度では不十分な場合にのみ使用します。

---

設定ワークフロー

標準的な手順

1. ノードの種類と操作を特定します。
2. get_node を使います（標準の詳細度がデフォルトです）。
3. 必須フィールドを設定します。
4. 設定を検証します。
5. フィールドが不明な場合は、get_node({mode: "search_properties"}) を使います。
6. 必要に応じてオプションのフィールドを追加します。
7. もう一度検証します。
8. デプロイします。

例：HTTP Request の設定

検証を繰り返しながら設定する手順の例です。まずは最小限の設定（method、url、authentication）から始め、validate_node の各エラーに応じて次の必須フィールドを追加します（POST の場合は sendBody、続いて sendBody=true の場合は body）。詳細な手順は OPERATION_PATTERNS.md を参照してください。

---

get_node の詳細度

標準の詳細度（デフォルト - こちらを使用してください！）

✅ 設定の開始時

get_node({
  nodeType: "nodes-base.slack"
});
// detail="standard" is the default

返される内容（約1～2Kトークン）：

• 必須フィールド
• 一般的なオプション
• 操作の一覧
• メタデータ

用途：設定ニーズの95%をカバーします。

完全な詳細度（必要な場合のみ使用）

✅ 標準の詳細度では不十分な場合

get_node({
  nodeType: "nodes-base.slack",
  detail: "full"
});

返される内容（約3～8Kトークン）：

• 完全なスキーマ
• すべてのプロパティ
• すべてのネストされたオプション

注意：応答が大きいため、標準の詳細度では不十分な場合にのみ使用してください。

プロパティの検索モード

✅ 特定のフィールドを探す場合

get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "search_properties",
  propertyQuery: "auth"
});

用途：認証、ヘッダー、本文フィールドなどを検索します。

判断フロー

1. 新しいノード設定を始める場合 → get_node（標準）。
2. 標準の詳細度で必要な情報が得られた場合 → その情報を使って設定します。得られない場合は次に進みます。
3. 特定のフィールドを探している場合 → search_properties モードを使います。そうでない場合は次に進みます。
4. さらに情報が必要な場合 → get_node({detail: "full"}) を使います。

動的プロパティ：standard の詳細度でプロパティに dynamicOptions: {methodName, methodType, dependsOn} と示されている場合、その実際の値はバンドルされたドキュメントではなく、ライブの loadOptions／listSearch メソッドから取得されます。IDを推測しないでください。n8n_explore_node_resources（N8N_MCP_ACCESS_TOKEN が必要。n8n 2.34以降）で値を解決し、返された value を設定に指定してください。name は表示用のテキストにすぎません。

6つのパラメーターはすべて必須で、互いから推測されるものはありません。

n8n_explore_node_resources({
  nodeType: "n8n-nodes-base.googleSheets",  // LONG form
  version: 4.5,                              // the node typeVersion the method belongs to
  methodName: "getSheets",                   // copied verbatim from dynamicOptions
  methodType: "listSearch",                  // "listSearch" for resource locators, "loadOptions" for plain dropdowns
  credentialType: "googleSheetsOAuth2Api",
  credentialId: "c2",                        // from n8n_manage_credentials({action: "list"})
  currentNodeParameters: {                   // whatever dependsOn names, in its real shape
    documentId: {__rl: true, mode: "id", value: "1AbC…"}
  }
})

dependsOn は、メソッドの実行前に選択しておく必要があるパラメーターを指定します。それらを currentNodeParameters に渡してください。その際、リソースロケーターの値は {__rl: true, mode, value} の形式を維持してください。そうしないと、メソッドから有用な結果が返されません。methodName は大文字と小文字を区別し、nodeType と version の組み合わせごとに固有です。一致しない場合は、空のリストではなく OFFICIAL_MCP_ERROR が返されます。

プロパティ依存関係の詳細

フィールドには displayOptions の表示ルールがあります。複数の条件が AND で結合され、複数の値が OR で結合される show／hide ブロックです（例：sendBody=true かつ method IN (POST, PUT, PATCH) の場合に body が表示されます）。繰り返し登場するパターンは、ブール値の切り替え（sendBody → body）、操作の切り替え（post と update で異なるフィールドを表示）、型の選択（string と boolean の条件）の3つです。フィールドを制御しているものを確認するには、get_node({mode: "search_properties", propertyQuery: "..."}) または get_node({detail: "full"}) を使用してください。特に、検証で表示されていないフィールドが指摘された場合に役立ちます。

仕組みの詳細、4種類すべての依存関係パターン、複雑なフロー、ネストされた依存関係、トラブルシューティングについては、DEPENDENCIES.md（簡易リファレンスは クイックリファレンス：displayOptions と一般的な依存関係パターン）をご覧ください。

---

一般的なノードパターン

パターン 1：リソース／操作ノード

例：Slack、Google Sheets、Airtable

構造：

{
  "resource": "<entity>",      // What type of thing
  "operation": "<action>",     // What to do with it
  // ... operation-specific fields
}

設定方法：

1. リソースを選択します
2. 操作を選択します
3. get_node を使用して、操作ごとの要件を確認します
4. 必須フィールドを設定します

パターン 2：HTTP ベースのノード

例：HTTP Request、Webhook

構造：

{
  "method": "<HTTP_METHOD>",
  "url": "<endpoint>",
  "authentication": "<type>",
  // ... method-specific fields
}

依存関係：

• POST/PUT/PATCH → sendBody を使用できます
• sendBody=true → body が必須です
• authentication != "none" → 認証情報が必須です

重要：credentials ブロック、ノード ID、typeVersion

• プレースホルダーの認証情報 ID（例："id": "REPLACE_ME"）は絶対に設定しないでください。n8n の UI では、認識されない ID の認証情報セレクターが常に無効な状態で表示されます。実際の ID が不明な場合は credentials ブロックを省略してください。そうすると、通常のクリック可能なドロップダウンが表示されます。
• ノードの id は、読みやすいスラッグではなく UUID v4 である必要があります。フロントエンドはフォームと認証情報コンポーネントをこの ID に紐付けます。
• 古い typeVersion の値をハードコードしないでください。現在のバージョンを get_node で確認してください（httpRequest は 4.4+ です）。

パターン 3：データベースノード

例：Postgres、MySQL、MongoDB

構造：

{
  "operation": "<query|insert|update|delete>",
  // ... operation-specific fields
}

依存関係：

• operation="executeQuery" → query が必須です
• operation="insert" → table + values が必須です
• operation="update" → table + values + where が必須です

重要：書き込み操作では 0 件のアイテムが返される場合があります

• INSERT、UPDATE、DELETE では、ノードと操作によっては n8n の出力アイテムが 0 件になることがあります（クエリを直接実行した場合、結果行は常に 0 件になります。一部のデータベースノードでは、影響を受けた行が返されます）
• 後続のチェーンを維持するには、書き込み操作のノードで alwaysOutputData: true を設定します
• 後続ノードでデータが必要な場合は、$input の代わりに $('UpstreamNode').all() を使用してください

パターン 4：条件分岐ロジックノード

例：IF、Switch、Merge

構造：

{
  "conditions": {
    "<type>": [
      {
        "operation": "<operator>",
        "value1": "...",
        "value2": "..."  // Only for binary operators
      }
    ]
  }
}

依存関係：

• 二項演算子（equals、contains など）→ value1 + value2
• 単項演算子（isEmpty、isNotEmpty）→ value1 のみ + singleValue: true

---

操作ごとの設定

必須フィールドは、リソースと操作の組み合わせによって変わります。Slack の post には channel+text が必要ですが、update には messageId+text が必要です（channel は任意）。channel/create には name が必要です。HTTP の GET では sendQuery+queryParameters を使用し、POST では sendBody+body が必要です。IF の二項演算子（equals）には value1+value2 が必要です。単項演算子（isEmpty）では value1 のみが必要で、singleValue: true が自動的に追加されます。それぞれの具体的な最小設定例については、OPERATION_PATTERNS.md をご覧ください。

---

条件付き要件の扱い

一部のフィールドは、特定の条件下でのみ必須になります。HTTP の body は、sendBody=true かつ method IN (POST, PUT, PATCH, DELETE) の場合に必須です。また、演算子が単項演算子（isEmpty、isNotEmpty、true、false）の場合は、singleValue を true にする必要があります。これは自動サニタイズによって自動設定されます。条件付き要件を確認するには、検証エラーを読む、プロパティを検索する（get_node({mode: "search_properties"})）、または最小限の設定から反復して調整します。実際の確認例については、DEPENDENCIES.md を参照してください。

---

ノード固有の設定に関する注意事項

SplitInBatches v3

{
  "batchSize": 100,  // Number of items per batch
  "options": {}
}

出力の接続：

• main[0]（完了）→ 後続の処理に接続します（先に Limit 1 を追加します）
• main[1]（各バッチ）→ ループ本体に接続し、その後 SplitInBatches の入力にループバックします

詳細なループおよびネストされたループのパターンについては、n8n Workflow Patterns スキルを参照してください。

Google Sheets ノード

アイテムごとの実行：入力アイテムごとに個別の API 呼び出しが行われます。アイテムが 100 件あり、Google Sheets の「Append Row」ノードを使う場合、API 呼び出しは 100 回行われます。一括で書き込むには、まず Code ノードでアイテムを集約し、その後 Sheets API を使う単一の HTTP Request を使用します。

数式列：数式列があるシートでは、append を使用しないでください。数式が上書きされます。代わりに、googleApi 認証情報を使い、Google Sheets API の values.update（PUT）メソッドで HTTP Request を使用します。

---

設定におけるアンチパターン

❌ 避けること：最初から設定しすぎる

悪い例：

// Adding every possible field
{
  "method": "GET",
  "url": "...",
  "sendQuery": false,
  "sendHeaders": false,
  "sendBody": false,
  "timeout": 10000,
  "ignoreResponseCode": false,
  // ... 20 more optional fields
}

良い例：

// Start minimal
{
  "method": "GET",
  "url": "...",
  "authentication": "none"
}
// Add fields only when needed

❌ 避けること：検証を省略する

悪い例：

// Configure and deploy without validating
const config = {...};
n8n_update_partial_workflow({...});  // YOLO

良い例：

// Validate before deploying
const config = {...};
const result = validate_node({...});
if (result.valid) {
  n8n_update_partial_workflow({...});
}

❌ 避けること：操作のコンテキストを無視する

悪い例：

// Same config for all Slack operations
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",
  "text": "..."
}

// Then switching operation without updating config
{
  "resource": "message",
  "operation": "update",  // Changed
  "channel": "#general",  // Wrong field for update!
  "text": "..."
}

良い例：

// Check requirements when changing operation
get_node({
  nodeType: "nodes-base.slack"
});
// See what update operation needs (messageId, not channel)

---

patchNodeField によるフィールドのピンポイント編集

ノードフィールド全体を置き換えるのではなく、フィールド内の特定の文字列を編集する場合は、n8n_update_partial_workflow の patchNodeField を使用します。特に、次のような場合に便利です。

• コードブロック全体を再送信せずに、Code ノード内のコードを編集する
• 大きな HTML メールテンプレート内の URL やテキストを更新する
• JSON の本文や長いテキストフィールドの誤字を修正する

// Instead of replacing the entire jsCode field:
n8n_update_partial_workflow({
  id: "wf-123",
  operations: [{
    type: "patchNodeField",
    nodeName: "Code",
    fieldPath: "parameters.jsCode",
    patches: [{find: "const limit = 10;", replace: "const limit = 50;"}]
  }]
})

patchNodeField は厳密に動作します。検索文字列が見つからない場合、または複数箇所に一致する場合（replaceAll: true の場合を除く）、エラーになります。これにより、設定更新時の予期しない失敗を防ぎます。完全な構文と使用例については、n8n MCP Tools Expert スキルを参照してください。

---

ベストプラクティス

推奨事項

1. まず get_node（標準詳細）から始める

   • 応答は約 1～2K トークンです
   • 設定要件の 95% をカバーします
   • デフォルトの詳細レベルです

2. 反復的に検証する

   • 設定 → 検証 → 修正 → 繰り返し
   • 平均 2～3 回の反復は通常の範囲です
   • 検証エラーを注意深く読みます

3. 行き詰まったら search_properties モードを使う

   • フィールドが見つからないように思える場合は、検索します
   • フィールドの表示を制御するものを把握します
   • get_node({mode: "search_properties", propertyQuery: "..."})

4. 操作のコンテキストを考慮する

   • 操作によって要件は異なります
   • 操作を変更するときは、必ず get_node を確認します
   • 設定をそのまま別の操作に流用できると思い込まないでください

5. 自動サニタイズを活用する

   • 演算子の構造は自動的に修正されます
   • singleValue を手動で追加・削除しないでください
   • IF/Switch のメタデータは保存時に追加されます

❌ 避けること

1. いきなり detail="full" にする

   • まず標準の詳細レベルを試します
   • 必要な場合にのみ詳細レベルを上げます
   • 完全なスキーマは 3～8K トークンです

2. 確認せずに設定する

   • デプロイ前に必ず検証します
   • フィールドが必須である理由を把握します
   • 条件付きフィールドには search_properties を使用します

3. 内容を理解せずに設定をコピーする

   • 操作によって必要なフィールドは異なります
   • コピー後に検証します
   • 新しいコンテキストに合わせて調整します

4. 自動サニタイズの問題を手動で修正する

   • 演算子の構造は自動サニタイズに任せます
   • ビジネスロジックに集中します
   • 保存して、システムに構造を修正させます

---

ノードファミリー別のサイレント失敗の落とし穴

設定ミスの中には、validate_node と validate_workflow を問題なく通過し、エラーなしで実行されるものの、気づかないうちに誤った動作をするものがあります。get_node ではフィールドの存在は確認できますが、省略した場合に何が起きるかまではわかりません。特に多いものは次のとおりです。

• Switch — options.fallbackOutput がない場合 ⇒ 条件に一致しないアイテムは気づかないうちに破棄されます。
• Merge — numberOfInputs のデフォルト値は 2 です（追加のソースは破棄されます）。useDataOfInput は 1 始まりですが、connections.<src>.main[idx] のスロットは 0 始まりです（useDataOfInput: "N" → main[N-1]）。
• Database — parameters.query への {{ }} 補間は SQL インジェクションにつながります。$1/$2 プレースホルダーと options.queryReplacement を使用してください。
• Slack — Block Kit は ={{ { "blocks": ... } }} でラップする必要があります。そうしないと、プレーンテキストとして投稿されます。
• Webhook / Respond — エラー分岐でも、responseCode のデフォルト値は 200 です。
• Schedule Trigger — タイムゾーンはルールごとではなく、ワークフローレベル（Workflow Settings）で設定します。

症状・原因・修正方法の詳細（JSON と n8n_update_partial_workflow の用語を使用）は、NODE_FAMILY_GOTCHAS.md をご覧ください。

---

詳細なリファレンス

特定のトピックについて詳しくは、以下のガイドをご覧ください。

• DEPENDENCIES.md - プロパティの依存関係と displayOptions の詳細
• OPERATION_PATTERNS.md - ノードタイプ別の一般的な設定パターン
• NODE_FAMILY_GOTCHAS.md - ファミリー別のサイレントな実行時の落とし穴（Switch、Merge、Database、Slack、Webhook、Schedule）

---

まとめ

設定の進め方：

1. get_node から始めます（標準の詳細表示がデフォルトです）
2. 操作に必要なフィールドを設定します
3. 設定を検証します
4. 行き詰まったらプロパティを検索します
5. 有効になるまで繰り返します（平均 2～3 サイクル）
6. 安心してデプロイします

主な原則：

• 操作を考慮する：操作ごとに必要な項目は異なります
• 段階的に情報を開示する：最小限から始め、必要に応じて追加します
• 依存関係を考慮する：フィールドの表示ルールを理解します
• 検証を活用する：検証結果を設定の指針にします

関連スキル：

• n8n MCP Tools Expert - 検出ツールの正しい使い方
• n8n Validation Expert - 検証エラーの解釈
• n8n Expression Syntax - 式フィールドの設定
• n8n Workflow Patterns - 適切な設定でパターンを適用する