MENU
Engineering Knowledge, Built as an Open World.
  1. HOME
  2. AI・自動化
  3. n8n
  4. n8nのData MappingとExpressionsを理解する｜動的な値を参照する基本

n8nのData MappingとExpressionsを理解する｜動的な値を参照する基本

n8n
「n8nのData MappingとExpressionsを理解する｜動的な値を参照する基本」の内容を表す技術イラスト

n8nでは、nodeを接続するだけでは自動化は完成しません。

前のnodeが出力したデータから必要なfieldを選び、次のnodeの設定へ正しく渡す必要があります。この値の受け渡しがData Mappingです。

前のnodeのOUTPUT
→ 必要なfieldを参照
→ 次のnodeのパラメーターへ設定

Data Mappingで使う中心的な仕組みがExpressionです。

Expressionを単なる記号として暗記するのではなく、「実行中のデータから値を取得する参照」として理解すると、Workflowが長くなってもデータの流れを追いやすくなります。

目次

今日の到達点

この記事を読み終えると、次の内容を説明できるようになります。

  • Data Mappingがnode間で果たす役割
  • Fixed値とExpressionの違い
  • $json.fieldが参照するデータ
  • INPUTからfieldをドラッグ＆ドロップする方法
  • 名前を指定して前のnodeを参照する方法
  • Expressionで値を取得できない場合の確認手順

Data Mappingとは何か

Data Mappingは、前段で取得または加工したデータを、後段nodeのパラメーターへ割り当てることです。

たとえば、前のnodeから次のJSONが渡されているとします。

{
  "name": "Pump A",
  "pressure_mpa": 10,
  "enabled": true
}

次のnodeで必要なのが機器名なら、nameだけを参照します。

{{ $json.name }}

圧力値が必要なら、次のように参照します。

{{ $json.pressure_mpa }}

Mappingは元データ全体をコピーする操作とは限りません。後段の処理に必要なfieldを選び、その値を適切なパラメーターへ結び付ける操作です。

Fixed値とExpressionの違い

n8nの多くの入力欄では、固定値とExpressionを切り替えて使用できます。

Fixed値

Fixed値は、Workflowを何回実行しても基本的に同じ値を使用します。

status = ready

3 itemsが入力されても、設定した値はすべて同じです。

[
  {
    "name": "Pump A",
    "status": "ready"
  },
  {
    "name": "Valve B",
    "status": "ready"
  }
]

通知先、固定ラベル、処理種別など、入力データに依存しない設定に適しています。

Expression

Expressionは、実行時のデータを参照して値を決めます。

{{ $json.name }}

複数itemsが入力される場合、現在処理しているitemに応じて結果が変わります。

item 1 → Pump A
item 2 → Valve B
item 3 → Cylinder C

使い分けの基準は単純です。

設定したい値選択
毎回同じ値Fixed
入力itemによって変わる値Expression
実行日時など実行ごとに変わる値Expression
前nodeの結果を利用する値Expression

Expressionの基本構造

Expressionは{{ }}の中に記述します。

{{ $json.name }}

公式のExpression referenceでは、$jsonは現在のinput itemに含まれるJSONデータ、$json.fieldNameはそのitem内のfieldとして定義されています。

現在のitemが次のデータなら、

{
  "machine": {
    "name": "Press A",
    "location": "Line 1"
  }
}

入れ子になったnameは次のように参照できます。

{{ $json.machine.name }}

field名に空白やハイフンなどが含まれる場合は、角括弧による表記も利用できます。

{{ $json["machine-name"] }}
{{ $json["machine info"]["location"] }}

Expressionでは簡単な計算や文字列処理も可能です。

{{ $json.pressure_mpa * 1000000 }}

ただし、複雑な処理を多数のパラメーターへ埋め込むとWorkflowを読みにくくします。n8n公式ドキュメントでは、データ変換が主目的ならEdit Fields（Set）nodeで先にデータを整える方法が推奨されています。

ドラッグ＆ドロップでMappingする

Expressionはすべて手入力する必要はありません。

前段nodeを実行して入力データを用意すると、後段nodeのINPUTパネルへfieldが表示されます。使用したいfieldを入力欄へドラッグ＆ドロップすると、n8nが対応するExpressionを作成します。

INPUTのname field
→ パラメーターへドラッグ
→ {{ $json.name }}

基本的な流れは次のとおりです。

  • 前段nodeを実行する
  • 後段nodeを開く
  • 対象パラメーターをExpressionモードへ切り替える
  • INPUTパネルからfieldをドラッグする
  • 生成されたExpressionとプレビュー結果を確認する

ここで重要なのは、ドラッグ＆ドロップとExpressionが別の機能ではないことです。

ドラッグ＆ドロップは、実際のINPUTデータを見ながらExpressionを組み立てるUI操作です。生成された式を読むと、「どのJSON pathを参照しているのか」を確認できます。

環境やn8nのバージョンにより、ボタン名やパネル配置が異なる場合があります。

$jsonは現在のitemを参照する

複数itemsが入力される場合、$jsonは固定された1件目ではなく、基本的に現在処理しているitemのJSONを参照します。

入力が次の3 itemsだとします。

[
  {
    "name": "Pump A",
    "pressure_mpa": 10
  },
  {
    "name": "Valve B",
    "pressure_mpa": 14
  },
  {
    "name": "Cylinder C",
    "pressure_mpa": 7
  }
]

次のExpressionを設定すると、

{{ $json.name }}

各itemではそれぞれ対応する値が取得されます。

Pump A
Valve B
Cylinder C

したがって、後段がメール送信やデータ登録を行うnodeなら、処理がitem数分発生する可能性があります。Expressionだけでなく、INPUTに何itemsあるかも確認してください。

名前を指定して前のnodeを参照する

$jsonは現在のnodeへ直接入力されているitemを参照するのに向いています。

一方、現在のINPUTではなく、特定の前段nodeのデータを明示的に取得したい場合は、node名を指定できます。

Source Dataというnodeに対応するitemを参照する例は次のとおりです。

{{ $('Source Data').item.json.name }}

公式Expression referenceでは、主に次の参照方法が示されています。

Expression参照対象
$("NodeName").item現在のitemに対応付けられたitem
$("NodeName").first()指定nodeの最初のitem
$("NodeName").last()指定nodeの最後のitem
$("NodeName").all()指定nodeの全items

最初のitemを明示的に取得する場合は、次のようになります。

{{ $('Source Data').first().json.name }}

.itemと.first()は同じ意味ではありません。

.itemはn8nのitem linkingを利用して、現在のitemに対応する上流itemを参照します。.first()は、対応関係にかかわらず指定nodeの最初のitemを取得します。

初心者の段階では、次の基準で十分です。

  • 直接入力された現在の値：$json
  • 特定のnodeを明示したい：$('Node Name').item
  • 本当に先頭の1件だけが必要：$('Node Name').first()

最小Workflowで確認する

3node以上を使い、Mappingの結果を観察します。

Manual Trigger
→ Code（3 itemsを作る）
→ Edit Fields（値を参照・加工する）

Code nodeでは、練習用データとして次のitemsを返します。

return [
  {
    json: {
      name: 'Pump A',
      pressure_mpa: 10
    }
  },
  {
    json: {
      name: 'Valve B',
      pressure_mpa: 14
    }
  },
  {
    json: {
      name: 'Cylinder C',
      pressure_mpa: 7
    }
  }
];

Edit Fields nodeで、まずFixed値を追加します。

status = ready

続いて、Expressionでlabelを追加します。

{{ $json.name + ' / ' + $json.pressure_mpa + ' MPa' }}

さらに、数値fieldとしてpressure_paを作ります。

{{ $json.pressure_mpa * 1000000 }}

期待するOUTPUTは次のような形です。

[
  {
    "name": "Pump A",
    "pressure_mpa": 10,
    "status": "ready",
    "label": "Pump A / 10 MPa",
    "pressure_pa": 10000000
  },
  {
    "name": "Valve B",
    "pressure_mpa": 14,
    "status": "ready",
    "label": "Valve B / 14 MPa",
    "pressure_pa": 14000000
  },
  {
    "name": "Cylinder C",
    "pressure_mpa": 7,
    "status": "ready",
    "label": "Cylinder C / 7 MPa",
    "pressure_pa": 7000000
  }
]

確認すべきなのは計算結果だけではありません。

  • 3 input itemsが3 output itemsになっているか
  • Fixed値のstatusが全itemsで同じか
  • Expressionの結果がitemごとに変化しているか
  • pressure_paがnumberとして出力されているか
  • ドラッグ操作で生成された式と手入力した式が一致するか

Mappingが壊れる代表的な原因

前段nodeを実行していない

Expressionが参照するデータをまだ取得していない場合、INPUTパネルへfieldが表示されなかったり、値のプレビューが得られなかったりします。

公式ドキュメントでは、Can't get data for expressionやReferenced node is unexecutedが表示される場合、参照対象nodeまでWorkflowを実行するよう案内されています。

JSON pathが違う

入力が次のような入れ子構造だとします。

{
  "machine": {
    "name": "Pump A"
  }
}

次の参照では値を取得できません。

{{ $json.name }}

実際のpathに合わせます。

{{ $json.machine.name }}

Table表示だけでは入れ子構造を読み違えることがあります。取得できない場合はJSON表示で{}と[]の位置を確認します。

Fixedモードのまま式を書いている

Fixedモードの入力欄へ{{ $json.name }}と入力すると、式ではなく文字列として扱われることがあります。

入力欄がExpressionモードになっているか、評価結果のプレビューが表示されているかを確認します。

node名を変更した

名前付きnode参照では、指定した名前と実際のnode名が対応している必要があります。

{{ $('Source Data').item.json.name }}

参照先のnode名を変更した場合は、Expression側の参照も確認します。node選択やINPUTからのドラッグを使うと、手入力による名前の間違いを減らせます。

すべてのitemsにfieldがあるとは限らない

外部APIやWebhookから受け取るデータでは、itemによってfieldが存在しない場合があります。

[
  {
    "name": "Pump A",
    "pressure_mpa": 10
  },
  {
    "name": "Valve B"
  }
]

2件目にはpressure_mpaがありません。プレビューで1件目が正常でも、別itemで未定義になる可能性があります。

本番でfieldが省略され得る場合は、前段で入力を検証するか、デフォルト値を設定する設計を検討します。

エラーを調べる順番

Mappingが期待どおりに動かない場合は、式を何度も書き換える前に、次の順番で確認します。

参照元nodeは実行されたか
→ INPUTに対象fieldがあるか
→ item数は何件か
→ JSON pathは正しいか
→ Expressionモードか
→ node名は一致しているか
→ 評価結果の型は正しいか

エラーが発生したnodeだけを見るのではなく、そのnodeへ実際に渡されたINPUTから調べることが重要です。

実務での使い分け

Expressionは、既存データをパラメーターへ割り当てたり、軽い計算や文字列整形を行ったりする場合に適しています。

{{ $json.first_name + ' ' + $json.last_name }}
{{ $json.price * $json.quantity }}

一方、複数のfieldをまとめて整形する場合は、Edit Fieldsで一度データを準備すると後段nodeが読みやすくなります。

入力データ
→ Edit Fieldsで業務用データへ整形
→ 通知・登録・API送信

配列全体の組み替え、複数itemsの集計、複雑なアルゴリズムが必要なら、専用のデータ変換nodeやCode nodeを検討します。

重要なのは「Expressionだけで書けるか」ではなく、後からWorkflowを見た人がデータの出所と変換内容を追跡できるかです。

今日の実習で確認すること

  • 3node以上を接続する
  • 前段nodeを実行してINPUTデータを表示する
  • fieldをドラッグ＆ドロップしてMappingする
  • 同じ参照をExpression editorへ手入力する
  • Fixed値とExpressionを切り替えて結果を比較する
  • $jsonと名前付きnode参照をそれぞれ試す
  • field名またはnode名を意図的に間違え、実際の表示を確認する

まとめ

Data Mappingは、前のnodeが出力したデータと、次のnodeが必要とするパラメーターを結び付ける操作です。

OUTPUTを見る
→ 必要なfieldを選ぶ
→ Expressionで参照する
→ 評価結果を確認する

Fixed値は毎回同じ値を使い、Expressionは実行中のデータから動的に値を取得します。

$json.fieldは現在のinput itemを参照し、$('Node Name').item.json.fieldは名前を指定した上流nodeの対応itemを参照します。INPUTからのドラッグ＆ドロップは、これらのExpressionを実データから作成する方法です。

構文を暗記することよりも、「どのnodeの、どのitemの、どのfieldを参照しているか」を説明できることが重要です。

参考資料

n8n
参考になったらシェアしてください
  • URLをコピーしました！
  • URLをコピーしました！

この記事を書いた人

ekplabzのアバター ekplabz

機械設計・油圧・CAD・Python・AIなど、ものづくりに関わる技術を扱っています。工学知識を整理・構造化し、設計や自動化に再利用できる形へ変えていくことを目指しています。

関連記事

目次