n8n-expression-syntax

n8n の式構文

ワークフローで正しい n8n の式を書くためのエキスパートガイドです。

---

式の形式

n8n の動的コンテンツはすべて、二重中括弧を使用します。

{{expression}}

例：

✅ {{$json.email}}
✅ {{$json.body.name}}
✅ {{$node["HTTP Request"].json.data}}
❌ $json.email  (no braces - treated as literal text)
❌ {$json.email}  (single braces - invalid)

---

基本変数

$json - 現在のノードの出力

現在のノードのデータにアクセスします。

{{$json.fieldName}}
{{$json['field with spaces']}}
{{$json.nested.property}}
{{$json.items[0].name}}

$node - 他のノードを参照

前の任意のノードのデータにアクセスします。

{{$node["Node Name"].json.fieldName}}
{{$node["HTTP Request"].json.data}}
{{$node["Webhook"].json.body.email}}

重要：

• ノード名は必ず引用符で囲みます
• ノード名では大文字と小文字が区別されます
• ワークフロー内のノード名と完全に一致させる必要があります

$now - 現在のタイムスタンプ

現在の日付と時刻にアクセスします。

{{$now}}
{{$now.toFormat('yyyy-MM-dd')}}
{{$now.toFormat('HH:mm:ss')}}
{{$now.plus({days: 7})}}

$env - 環境変数

環境変数にアクセスします。

{{$env.API_KEY}}
{{$env.DATABASE_URL}}

---

🚨 重要：Webhook のデータ構造

最もよくある間違い：Webhook のデータはルートにありません！

Webhook ノードの出力構造

{
  "headers": {...},
  "params": {...},
  "query": {...},
  "body": {           // ⚠️ USER DATA IS HERE!
    "name": "John",
    "email": "[email protected]",
    "message": "Hello"
  }
}

Webhook データへの正しいアクセス方法

❌ WRONG: {{$json.name}}
❌ WRONG: {{$json.email}}

✅ CORRECT: {{$json.body.name}}
✅ CORRECT: {{$json.body.email}}
✅ CORRECT: {{$json.body.message}}

理由：Webhook ノードは、ヘッダー、パラメーター、クエリパラメーターを保持するため、受信データを .body プロパティの下に格納します。

---

よく使われるパターン

ネストされたフィールドへのアクセス

// Simple nesting
{{$json.user.email}}

// Array access
{{$json.data[0].name}}
{{$json.items[0].id}}

// Bracket notation for spaces
{{$json['field name']}}
{{$json['user data']['first name']}}

他のノードの参照

// Node without spaces
{{$node["Set"].json.value}}

// Node with spaces (common!)
{{$node["HTTP Request"].json.data}}
{{$node["Respond to Webhook"].json.message}}

// Webhook node
{{$node["Webhook"].json.body.email}}

変数の組み合わせ

// Concatenation (automatic)
Hello {{$json.body.name}}!

// In URLs
https://api.example.com/users/{{$json.body.user_id}}

// In object properties
{
  "name": "={{$json.body.name}}",
  "email": "={{$json.body.email}}"
}

---

式を使用しない場面

❌ コードノード

コードノードでは式ではなく、JavaScript で直接アクセスします！

// ❌ WRONG in Code node
const email = '={{$json.email}}';
const name = '{{$json.body.name}}';

// ✅ CORRECT in Code node
const email = $json.email;
const name = $json.body.name;

// Or using Code node API
const email = $input.item.json.email;
const allItems = $input.all();

❌ Webhook のパス

// ❌ WRONG
path: "{{$json.user_id}}/webhook"

// ✅ CORRECT
path: "user-webhook"  // Static paths only

❌ 認証情報フィールド

// ❌ WRONG
apiKey: "={{$env.API_KEY}}"

// ✅ CORRECT
Use n8n credential system, not expressions

---

検証ルール

1. 必ず {{}} を使用する

式は必ず二重中括弧で囲みます。

❌ $json.field
✅ {{$json.field}}

2. スペースには引用符を使用する

スペースを含むフィールド名やノード名には、ブラケット記法が必要です。

❌ {{$json.field name}}
✅ {{$json['field name']}}

❌ {{$node.HTTP Request.json}}
✅ {{$node["HTTP Request"].json}}

3. ノード名を正確に一致させる

ノード参照では大文字と小文字が区別されます。

❌ {{$node["http request"].json}}  // lowercase
❌ {{$node["Http Request"].json}}  // wrong case
✅ {{$node["HTTP Request"].json}}  // exact match

4. {{}} をネストしない

式を二重に囲まないでください。

❌ {{{$json.field}}}
✅ {{$json.field}}

---

よくある間違い

修正方法を含むエラーの完全な一覧については、COMMON_MISTAKES.md を参照してください。

簡単な修正方法

間違い	修正方法
$json.field	{{$json.field}}
{{$json.field name}}	{{$json['field name']}}
{{$node.HTTP Request}}	{{$node["HTTP Request"]}}
{{{$json.field}}}	{{$json.field}}
{{$json.name}}（Webhook）	{{$json.body.name}}
'={{$json.email}}'（コードノード）	$json.email

---

使用例

実際のワークフロー例については、EXAMPLES.md を参照してください。

例 1：Webhook から Slack へ

Webhook が受信するデータ：

{
  "body": {
    "name": "John Doe",
    "email": "[email protected]",
    "message": "Hello!"
  }
}

Slack ノードのテキストフィールドで：

New form submission!

Name: {{$json.body.name}}
Email: {{$json.body.email}}
Message: {{$json.body.message}}

例 2：HTTP Request からメールへ

HTTP Request が返すデータ：

{
  "data": {
    "items": [
      {"name": "Product 1", "price": 29.99}
    ]
  }
}

メールノードで（HTTP Request を参照）：

Product: {{$node["HTTP Request"].json.data.items[0].name}}
Price: ${{$node["HTTP Request"].json.data.items[0].price}}

例 3：タイムスタンプの書式設定

// Current date
{{$now.toFormat('yyyy-MM-dd')}}
// Result: 2025-10-20

// Time
{{$now.toFormat('HH:mm:ss')}}
// Result: 14:30:45

// Full datetime
{{$now.toFormat('yyyy-MM-dd HH:mm')}}
// Result: 2025-10-20 14:30

---

データ型の処理

配列

// First item
{{$json.users[0].email}}

// Array length
{{$json.users.length}}

// Last item
{{$json.users[$json.users.length - 1].name}}

オブジェクト

// Dot notation (no spaces)
{{$json.user.email}}

// Bracket notation (with spaces or dynamic)
{{$json['user data'].email}}

文字列

// Concatenation (automatic)
Hello {{$json.name}}!

// String methods
{{$json.email.toLowerCase()}}
{{$json.name.toUpperCase()}}

数値

// Direct use
{{$json.price}}

// Math operations
{{$json.price * 1.1}}  // Add 10%
{{$json.quantity + 5}}

---

高度なパターン

条件付きコンテンツ

// Ternary operator
{{$json.status === 'active' ? 'Active User' : 'Inactive User'}}

// Default values
{{$json.email || '[email protected]'}}

日付の操作

// Add days
{{$now.plus({days: 7}).toFormat('yyyy-MM-dd')}}

// Subtract hours
{{$now.minus({hours: 24}).toISO()}}

// Set specific date
{{DateTime.fromISO('2025-12-25').toFormat('MMMM dd, yyyy')}}

文字列の操作

// Substring
{{$json.email.substring(0, 5)}}

// Replace
{{$json.message.replace('old', 'new')}}

// Split and join
{{$json.tags.split(',').join(', ')}}

---

式のデバッグ

式エディターでテストする

1. 式を含むフィールドをクリックします
2. 式エディターを開きます（「fx」アイコンをクリック）
3. 結果のライブプレビューを確認します
4. 赤くハイライトされたエラーがないか確認します

よくあるエラーメッセージ

「Cannot read property 'X' of undefined」 → 親オブジェクトが存在しません → データパスを確認してください

「X is not a function」 → 関数ではないものに対してメソッドを呼び出そうとしています → 変数の型を確認してください

式がそのままテキストとして表示される → {{ }} がありません → 中括弧を追加してください

---

式のヘルパー

使用可能なメソッド

文字列：

• .toLowerCase()、.toUpperCase()
• .trim()、.replace()、.substring()
• .split()、.includes()

配列：

• .length、.map()、.filter()
• .find()、.join()、.slice()

日時（Luxon）：

• .toFormat()、.toISO()、.toLocal()
• .plus()、.minus()、.set()

数値：

• .toFixed()、.toString()
• 数学演算：+、-、*、/、%

---

ベストプラクティス

✅ 推奨事項

• 動的コンテンツには必ず {{ }} を使用します
• スペースを含むフィールド名にはブラケット記法を使用します
• Webhook データは .body から参照します
• 他のノードのデータには $node を使用します
• 式エディターで式をテストします

❌ 禁止事項

• Code ノードでは式を使用しないでください
• スペースを含むノード名は引用符で囲んでください
• 余分な {{ }} で二重に囲まないでください
• webhook データがルートにあると思い込まないでください（.body の下にあります！）
• webhook のパスや認証情報では式を使用しないでください

---

関連スキル

• n8n MCP Tools Expert：MCP ツールを使用した式の検証方法を学べます
• n8n Workflow Patterns：実際のワークフロー例で式を確認できます
• n8n Node Configuration：式が必要な場面を理解できます

---

まとめ

基本ルール：

1. 式は {{ }} で囲みます
2. webhook データは .body の下にあります
3. Code ノードでは {{ }} を使用しません
4. スペースを含むノード名は引用符で囲みます
5. ノード名では大文字と小文字が区別されます

よくある間違い：

• {{ }} がない → 波括弧を追加します
• webhook で {{$json.name}} を使用 → {{$json.body.name}} を使用します
• Code で {{$json.email}} を使用 → $json.email を使用します
• {{$node.HTTP Request}} → {{$node["HTTP Request"]}} を使用します

詳細については、以下を参照してください：

• COMMON_MISTAKES.md - エラー一覧
• EXAMPLES.md - 実際のワークフロー例

---

お困りですか？ n8n の式に関するドキュメントを参照するか、n8n-mcp の検証ツールを使用して式を確認してください。