n8n ノード設定

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

---

設定の考え方

段階的な機能公開: 最小限から始めて、必要に応じて複雑さを追加する

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

• detail: "standard" を指定した get_node が最も一般的な検出パターン
• 設定編集間の平均時間は 56 秒
• 1-2K トークンのレスポンスでユースケースの 95% をカバー

重要な洞察: ほとんどの設定では、完全なスキーマではなく標準詳細度だけが必要!

---

中核的概念

1. 操作対応型設定

すべてのフィールドが常に必須というわけではなく、操作に依存します!

例: Slack ノード

// operation='post' の場合
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",  // post では必須
  "text": "Hello!"        // post では必須
}

// operation='update' の場合
{
  "resource": "message",
  "operation": "update",
  "messageId": "123",     // update では必須 (異なる!)
  "text": "Updated!"      // update では必須
  // channel は update では不要
}

重要: リソース + 操作により、どのフィールドが必須かが決定される!

2. プロパティ依存関係

フィールドは他のフィールド値に基づいて表示/非表示になります

例: HTTP Request ノード

// method='GET' の場合
{
  "method": "GET",
  "url": "https://api.example.com"
  // sendBody は表示されない (GET にはボディがない)
}

// method='POST' の場合
{
  "method": "POST",
  "url": "https://api.example.com",
  "sendBody": true,       // 今は表示される!
  "body": {               // 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 を使用 (詳細度のデフォルトは standard)
   ↓
3. 必須フィールドを設定
   ↓
4. 設定を検証
   ↓
5. フィールドが不明な場合 → get_node({mode: "search_properties"})
   ↓
6. 必要に応じてオプショナルフィールドを追加
   ↓
7. 再度検証
   ↓
8. デプロイ

例: HTTP Request の設定

ステップ 1: 必要なものを識別

// 目標: API に JSON を POST する

ステップ 2: ノード情報を取得

const info = get_node({
  nodeType: "nodes-base.httpRequest"
});

// 戻り値: method, url, sendBody, body, authentication required/optional

ステップ 3: 最小限の設定

{
  "method": "POST",
  "url": "https://api.example.com/create",
  "authentication": "none"
}

ステップ 4: 検証

validate_node({
  nodeType: "nodes-base.httpRequest",
  config,
  profile: "runtime"
});
// → エラー: "sendBody required for POST"

ステップ 5: 必須フィールドを追加

{
  "method": "POST",
  "url": "https://api.example.com/create",
  "authentication": "none",
  "sendBody": true
}

ステップ 6: 再度検証

validate_node({...});
// → エラー: "body required when sendBody=true"

ステップ 7: 設定を完成

{
  "method": "POST",
  "url": "https://api.example.com/create",
  "authentication": "none",
  "sendBody": true,
  "body": {
    "contentType": "json",
    "content": {
      "name": "={{$json.name}}",
      "email": "={{$json.email}}"
    }
  }
}

ステップ 8: 最終検証

validate_node({...});
// → 有効! ✅

---

get_node 詳細度レベル

標準詳細度 (デフォルト - これを使用!)

✅ 設定を開始する場合

get_node({
  nodeType: "nodes-base.slack"
});
// detail="standard" がデフォルト

戻り値 (~1-2K トークン):

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

用途: 設定ニーズの 95%

完全詳細度 (慎重に使用)

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

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

戻り値 (~3-8K トークン):

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

警告: レスポンスが大きいため、標準詳細度で十分でない場合のみ使用

プロパティ検索モード

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

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

用途: 認証、ヘッダー、ボディフィールドなどを検索

決定木

┌─────────────────────────────────┐
│ 新しいノード設定を開始?         │
├─────────────────────────────────┤
│ はい → get_node (standard)      │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│ 標準詳細度に必要な情報がある?   │
├─────────────────────────────────┤
│ はい → それで設定する           │
│ いいえ → 続行                   │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│ 特定フィールドを探している?     │
├─────────────────────────────────┤
│ はい → search_properties モード │
│ いいえ → 続行                   │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│ さらに詳細が必要?               │
├─────────────────────────────────┤
│ はい → get_node({detail: "full"})│
└─────────────────────────────────┘

---

プロパティ依存関係の深堀り

displayOptions メカニズム

フィールドには可視性ルールがある:

{
  "name": "body",
  "displayOptions": {
    "show": {
      "sendBody": [true],
      "method": ["POST", "PUT", "PATCH"]
    }
  }
}

翻訳: "body" フィールドは以下の場合に表示されます:

• sendBody = true かつ
• method = POST、PUT、または PATCH

一般的な依存関係パターン

パターン 1: ブール値トグル

例: HTTP Request sendBody

// sendBody が body の可視性を制御
{
  "sendBody": true   // → body フィールドが表示される
}

パターン 2: 操作スイッチ

例: Slack resource/operation

// 異なる操作 → 異なるフィールド
{
  "resource": "message",
  "operation": "post"
  // → 表示: channel, text, attachments など
}

{
  "resource": "message",
  "operation": "update"
  // → 表示: messageId, text (異なるフィールド!)
}

パターン 3: タイプ選択

例: IF ノード条件

{
  "type": "string",
  "operation": "contains"
  // → 表示: value1, value2
}

{
  "type": "boolean",
  "operation": "equals"
  // → 表示: value1, value2, 異なる演算子
}

プロパティ依存関係を検出

search_properties モードで get_node を使用:

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

// "body" に一致するプロパティパスと説明を戻す

または完全詳細度を使用:

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

// displayOptions ルール付きの完全なスキーマを戻す

使用する場合: 検証が失敗し、フィールドがなぜ失われた/必須なのかわからない場合

---

一般的なノードパターン

パターン 1: リソース/操作ノード

例: Slack、Google Sheets、Airtable

構造:

{
  "resource": "<entity>",      // 何のタイプ
  "operation": "<action>",     // それで何をするか
  // ... 操作固有のフィールド
}

設定方法:

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

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

例: HTTP Request、Webhook

構造:

{
  "method": "<HTTP_METHOD>",
  "url": "<endpoint>",
  "authentication": "<type>",
  // ... メソッド固有のフィールド
}

依存関係:

• POST/PUT/PATCH → sendBody が利用可能
• sendBody=true → body が必須
• authentication != "none" → 認証情報が必須

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

例: Postgres、MySQL、MongoDB

構造:

{
  "operation": "<query|insert|update|delete>",
  // ... 操作固有のフィールド
}

依存関係:

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

パターン 4: 条件付きロジックノード

例: IF、Switch、Merge

構造:

{
  "conditions": {
    "<type>": [
      {
        "operation": "<operator>",
        "value1": "...",
        "value2": "..."  // 二項演算子の場合のみ
      }
    ]
  }
}

依存関係:

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

---

操作固有の設定

Slack ノードの例

メッセージを投稿

{
  "resource": "message",
  "operation": "post",
  "channel": "#general",      // 必須
  "text": "Hello!",           // 必須
  "attachments": [],          // オプション
  "blocks": []                // オプション
}

メッセージを更新

{
  "resource": "message",
  "operation": "update",
  "messageId": "1234567890",  // 必須 (post と異なる!)
  "text": "Updated!",         // 必須
  "channel": "#general"       // オプション (推論可能)
}

チャンネルを作成

{
  "resource": "channel",
  "operation": "create",
  "name": "new-channel",      // 必須
  "isPrivate": false          // オプション
  // 注: この操作では text は不要
}

HTTP Request ノードの例

GET リクエスト

{
  "method": "GET",
  "url": "https://api.example.com/users",
  "authentication": "predefinedCredentialType",
  "nodeCredentialType": "httpHeaderAuth",
  "sendQuery": true,                    // オプション
  "queryParameters": {                  // sendQuery=true の場合に表示
    "parameters": [
      {
        "name": "limit",
        "value": "100"
      }
    ]
  }
}

JSON を使用した POST

{
  "method": "POST",
  "url": "https://api.example.com/users",
  "authentication": "none",
  "sendBody": true,                     // POST では必須
  "body": {                             // sendBody=true の場合は必須
    "contentType": "json",
    "content": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

IF ノードの例

文字列比較 (二項)

{
  "conditions": {
    "string": [
      {
        "value1": "={{$json.status}}",
        "operation": "equals",
        "value2": "active"              // 二項: value2 が必要
      }
    ]
  }
}

空チェック (単項)

{
  "conditions": {
    "string": [
      {
        "value1": "={{$json.email}}",
        "operation": "isEmpty",
        // value2 なし - 単項演算子
        "singleValue": true             // サニタイズで自動追加
      }
    ]
  }
}

---

条件付き要件の処理

例: HTTP Request ボディ

シナリオ: body フィールドが必須だが、常にではない

ルール:

body は以下の場合に必須:
  - sendBody = true かつ
  - method が (POST、PUT、PATCH、DELETE) に含まれる

検出方法:

// オプション 1: 検証エラーを読む
validate_node({...});
// エラー: "body required when sendBody=true"

// オプション 2: プロパティを検索
get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "search_properties",
  propertyQuery: "body"
});
// displayOptions ルール付きで body プロパティを表示

// オプション 3: 最小限の設定を試して反復
// body なしで始め、検証がそれが必要かどうかを教えてくれます

例: IF ノード singleValue

シナリオ: singleValue プロパティが単項演算子に表示される

ルール:

singleValue は以下の場合に true になるべき:
  - operation が (isEmpty、isNotEmpty、true、false) に含まれる

良いニュース: 自動サニタイズがこれを修正します!

手動チェック:

get_node({
  nodeType: "nodes-base.if",
  detail: "full"
});
// 演算子固有のルール付きの完全なスキーマを表示

---

ノード固有の設定上の注意

SplitInBatches v3

{
  "batchSize": 100,  // バッチあたりのアイテム数
  "options": {}
}

出力ワイヤリング:

• main[0] (done) → ダウンストリーム処理に接続 (最初に Limit 1 を追加)
• main[1] (each batch) → ループボディに接続し、SplitInBatches 入力にループバック

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

Google Sheets ノード

項目ごとの実行: 各入力項目が個別の API 呼び出しをトリガーします。100 個のアイテムがあり、Google Sheets の「行を追加」ノードを使用する場合、100 回の API 呼び出しが行われます。一括で書き込むには、最初に Code ノードでアイテムを集約してから、Sheets API を使用した単一の HTTP Request を使用します。

数式列: 数式列を含むシートで append を使用しないでください - 数式が上書きされます。代わりに、Google Sheets API values.update (PUT) メソッドと googleApi 認証情報で HTTP Request を使用してください。

---

設定のアンチパターン

❌ しないこと: 事前に過度に設定

悪い例:

// すべての可能なフィールドを追加
{
  "method": "GET",
  "url": "...",
  "sendQuery": false,
  "sendHeaders": false,
  "sendBody": false,
  "timeout": 10000,
  "ignoreResponseCode": false,
  // ... さらに 20 個のオプショナルフィールド
}

良い例:

// 最小限から始める
{
  "method": "GET",
  "url": "...",
  "authentication": "none"
}
// 必要な場合のみフィールドを追加

❌ しないこと: 検証をスキップ

悪い例:

// 検証なしで設定とデプロイ
const config = {...};
n8n_update_partial_workflow({...});  // 当てずっぽう

良い例:

// デプロイ前に検証
const config = {...};
const result = validate_node({...});
if (result.valid) {
  n8n_update_partial_workflow({...});
}

❌ しないこと: 操作コンテキストを無視

悪い例:

// すべての Slack 操作で同じ設定
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",
  "text": "..."
}

// その後、設定を更新せずに操作を切り替える
{
  "resource": "message",
  "operation": "update",  // 変更
  "channel": "#general",  // update には間違ったフィールド!
  "text": "..."
}

良い例:

// 操作を変更するときに要件を確認
get_node({
  nodeType: "nodes-base.slack"
});
// update 操作が何が必要かを確認 (channel ではなく messageId)

---

patchNodeField を使用した外科的フィールド編集

ノードフィールド全体を置き換えるのではなく、ノードフィールド内の特定の文字列を編集する必要がある場合は、n8n_update_partial_workflow で patchNodeField を使用してください。これは特に以下に役立ちます:

• Code ノード内のコード全体を再送信することなく、コード内の編集
• 大きな HTML メールテンプレート内の URL またはテキストの更新
• JSON ボディまたは長いテキストフィールド内のタイプミスの修正

// jsCode フィールド全体を置き換えるのではなく:
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 は厳密です - find 文字列が見つからないか複数回マッチした場合にエラーが発生します (replaceAll: true を指定しない限り)。これにより、設定更新中に予期しない静かな失敗を防止します。完全な構文と例については、n8n MCP Tools Expert スキルを参照してください。

---

ベストプラクティス

すべき こと

1. get_node (標準詳細度) から始める

   • ~1-2K トークンのレスポンス
   • 設定ニーズの 95% をカバー
   • デフォルトの詳細度

2. 反復的に検証

   • 設定 → 検証 → 修正 → 繰り返し
   • 平均 2-3 回の反復は正常
   • 検証エラーを注意深く読む

3. stuck したときは 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. 自動サニタイズの問題を手動で修正

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

---

詳細なリファレンス

特定のトピックに関する包括的なガイド:

• DEPENDENCIES.md - プロパティ依存関係と displayOptions の深堀り
• OPERATION_PATTERNS.md - ノードタイプ別の一般的な設定パターン

---

サマリー

設定戦略:

1. get_node で始める (詳細度のデフォルトは standard)
2. 操作の必須フィールドを設定
3. 設定を検証
4. stuck した場合はプロパティを検索
5. 有効になるまで反復 (平均 2-3 サイクル)
6. 自信を持ってデプロイ

重要な原則:

• 操作対応: 異なる操作 = 異なる要件
• 段階的な機能公開: 最小限から始めて、必要に応じて追加
• 依存関係対応: フィールド可視性ルールを理解
• 検証駆動: 検証に設定をガイドさせる

関連スキル:

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