n8n-node-configuration

n8n ノードの設定

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

---

設定の考え方

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

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

• get_node_essentials は最もよく使われる探索パターンです
• 設定を編集する間隔は平均56秒です
• essentials に基づく設定の成功率は91.7%です

重要なポイント：ほとんどの設定で必要なのは、完全なスキーマではなく essentials だけです！

---

基本概念

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_essentials（成功率91.7%）

   • すばやく概要を把握
   • 必須フィールド
   • よく使われるオプション
   • 最初に使用 — ニーズの90%をカバーします

2. get_property_dependencies（複雑なノード向け）

   • どのフィールドがほかのフィールドに依存しているかを表示
   • 条件付きの必須項目を確認
   • essentials だけでは不十分な場合に使用

3. get_node_info（完全なスキーマ）

   • 完全なドキュメント
   • すべてのフィールド
   • essentials と依存関係だけでは不十分な場合に使用

---

設定ワークフロー

標準的な手順

1. Identify node type and operation
   ↓
2. Use get_node_essentials
   ↓
3. Configure required fields
   ↓
4. Validate configuration
   ↓
5. If dependencies unclear → get_property_dependencies
   ↓
6. Add optional fields as needed
   ↓
7. Validate again
   ↓
8. Deploy

例：HTTP Request の設定

ステップ1：必要な内容を特定します

// Goal: POST JSON to API

ステップ2：essentials を取得します

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

// Returns: method, url, sendBody, body, authentication required/optional

ステップ3：最小限の設定を行います

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

ステップ4：検証します

validate_node_operation({
  nodeType: "nodes-base.httpRequest",
  config,
  profile: "runtime"
});
// → Error: "sendBody required for POST"

ステップ5：必須フィールドを追加します

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

ステップ6：もう一度検証します

validate_node_operation({...});
// → Error: "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_operation({...});
// → Valid! ✅

---

get_node_essentials と get_node_info の比較

get_node_essentials を使用する場合：

✅ 設定を始めるとき（成功率91.7%）

get_node_essentials({
  nodeType: "nodes-base.slack"
});

返される情報：

• 必須フィールド
• よく使われるオプション
• 基本的な例
• 操作の一覧

高速：平均約18秒（検索から essentials の取得まで）

get_node_info を使用する場合：

✅ essentials だけでは不十分なとき

get_node_info({
  nodeType: "nodes-base.slack"
});

返される情報：

• 完全なスキーマ
• すべてのプロパティ
• 完全なドキュメント
• 高度なオプション

低速：処理するデータが多くなります

判断フローチャート

┌─────────────────────────────────┐
│ Starting new node config?       │
├─────────────────────────────────┤
│ YES → get_node_essentials       │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│ Essentials has what you need?   │
├─────────────────────────────────┤
│ YES → Configure with essentials │
│ NO  → Continue                  │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│ Need dependency info?           │
├─────────────────────────────────┤
│ YES → get_property_dependencies │
│ NO  → Continue                  │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│ Still need more details?        │
├─────────────────────────────────┤
│ YES → get_node_info             │
└─────────────────────────────────┘

---

プロパティの依存関係を詳しく見る

displayOptions の仕組み

フィールドには表示ルールがあります：

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

意味：「body」フィールドが表示される条件：

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

よくある依存関係のパターン

パターン1：ブール値の切り替え

例：HTTP Request の sendBody

// sendBody controls body visibility
{
  "sendBody": true   // → body field appears
}

パターン2：操作の切り替え

例：Slack のリソース／操作

// Different operations → different fields
{
  "resource": "message",
  "operation": "post"
  // → Shows: channel, text, attachments, etc.
}

{
  "resource": "message",
  "operation": "update"
  // → Shows: messageId, text (different fields!)
}

パターン3：タイプの選択

例：IF ノードの条件

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

{
  "type": "boolean",
  "operation": "equals"
  // → Shows: value1, value2, different operators
}

get_property_dependencies の使用

例：

const deps = get_property_dependencies({
  nodeType: "nodes-base.httpRequest"
});

// Returns dependency tree
{
  "dependencies": {
    "body": {
      "shows_when": {
        "sendBody": [true],
        "method": ["POST", "PUT", "PATCH", "DELETE"]
      }
    },
    "queryParameters": {
      "shows_when": {
        "sendQuery": [true]
      }
    }
  }
}

次の場合に使用します：検証に失敗し、フィールドが欠落または必須である理由がわからないとき

---

よくあるノードのパターン

パターン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_essentials を使って、操作ごとの必須項目を確認します
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" → 認証情報が必須です

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

例：Postgres、MySQL、MongoDB

構造：

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

依存関係：

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

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

例：IF、Switch、Merge

構造：

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

依存関係：

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

---

操作固有の設定

Slack ノードの例

メッセージの投稿

{
  "resource": "message",
  "operation": "post",
  "channel": "#general",      // Required
  "text": "Hello!",           // Required
  "attachments": [],          // Optional
  "blocks": []                // Optional
}

メッセージの更新

{
  "resource": "message",
  "operation": "update",
  "messageId": "1234567890",  // Required (different from post!)
  "text": "Updated!",         // Required
  "channel": "#general"       // Optional (can be inferred)
}

チャンネルの作成

{
  "resource": "channel",
  "operation": "create",
  "name": "new-channel",      // Required
  "isPrivate": false          // Optional
  // Note: text NOT required for this operation
}

HTTP Request ノードの例

GET リクエスト

{
  "method": "GET",
  "url": "https://api.example.com/users",
  "authentication": "predefinedCredentialType",
  "nodeCredentialType": "httpHeaderAuth",
  "sendQuery": true,                    // Optional
  "queryParameters": {                  // Shows when sendQuery=true
    "parameters": [
      {
        "name": "limit",
        "value": "100"
      }
    ]
  }
}

JSON を使用した POST

{
  "method": "POST",
  "url": "https://api.example.com/users",
  "authentication": "none",
  "sendBody": true,                     // Required for POST
  "body": {                             // Required when sendBody=true
    "contentType": "json",
    "content": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  }
}

IF ノードの例

文字列比較（二項）

{
  "conditions": {
    "string": [
      {
        "value1": "={{$json.status}}",
        "operation": "equals",
        "value2": "active"              // Binary: needs value2
      }
    ]
  }
}

空のチェック（単項）

{
  "conditions": {
    "string": [
      {
        "value1": "={{$json.email}}",
        "operation": "isEmpty",
        // No value2 - unary operator
        "singleValue": true             // Auto-added by sanitization
      }
    ]
  }
}

---

条件付き要件への対応

例：HTTP Request のボディ

シナリオ：body フィールドが必須ですが、必須なのは特定の場合のみです

ルール：

body is required when:
  - sendBody = true AND
  - method IN (POST, PUT, PATCH, DELETE)

確認方法：

// Option 1: Read validation error
validate_node_operation({...});
// Error: "body required when sendBody=true"

// Option 2: Check dependencies
get_property_dependencies({
  nodeType: "nodes-base.httpRequest"
});
// Shows: body → shows_when: sendBody=[true], method=[POST,PUT,PATCH,DELETE]

// Option 3: Try minimal config and iterate
// Start without body, validation will tell you if needed

例：IF ノードの singleValue

シナリオ：単項演算子では singleValue プロパティが表示されます

ルール：

singleValue should be true when:
  - operation IN (isEmpty, isNotEmpty, true, false)

朗報：自動サニタイズで修正されます！

手動での確認：

get_property_dependencies({
  nodeType: "nodes-base.if"
});
// Shows operator-specific dependencies

---

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

❌ やってはいけないこと：最初から設定しすぎる

悪い例：

// 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_operation({...});
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_essentials({
  nodeType: "nodes-base.slack"
});
// See what update operation needs (messageId, not channel)

---

ベストプラクティス

✅ やるべきこと

1. get_node_essentials から始める

   • 成功率 91.7%
   • get_node_info より高速
   • ほとんどの用途で十分です

2. 段階的に検証する

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

3. 行き詰まったらプロパティの依存関係を利用する

   • フィールドが見つからない場合は、依存関係を確認します
   • フィールドの表示を制御する要素を把握します
   • get_property_dependencies でルールを確認できます

4. 操作のコンテキストを尊重する

   • 操作が異なれば、要件も異なります
   • 操作を変更するときは、必ず essentials を確認します
   • 設定をそのまま別の操作に適用できると思い込まないでください

5. 自動サニタイズを信頼する

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

❌ やってはいけないこと

1. すぐに get_node_info に移行する

   • まず essentials を試します
   • 必要な場合にのみ、より詳細な情報を確認します
   • 完全なスキーマは情報量が多すぎます

2. 考えずに設定する

   • デプロイ前に必ず検証します
   • フィールドが必須である理由を把握します
   • 条件付きフィールドの依存関係を確認します

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

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

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

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

---

詳細なリファレンス

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

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

---

まとめ

設定の方針：

1. get_node_essentials から始めます（成功率 91.7%）
2. 操作に必要なフィールドを設定します
3. 設定を検証します
4. 行き詰まったら依存関係を確認します
5. 有効になるまで繰り返します（平均 2〜3 サイクル）
6. 自信を持ってデプロイします

重要な原則：

• 操作を考慮する：操作が異なれば、要件も異なります
• 段階的に情報を開示する：最小限から始め、必要に応じて追加します
• 依存関係を考慮する：フィールドの表示ルールを把握します
• 検証を重視する：検証結果を設定の指針にします

関連スキル：

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