導入
Codeノードはn8nで最も強力なツールのひとつです。Set、Edit Fields、Split Inなどのビルトインノードで目的を満たせない場合、Codeノードを使ってリアルなJavaScriptを記述し、データを望む通り正確に変換できます。サンドボックス化されたNode.js環境で実行され、n8nのアイテム構造へ直接アクセスできるため、ワークフローのデータを完全にコントロールできます。
このレッスンは、実用的な3つのユースケースに焦点を当てます:配列の操作、文字列のフォーマット、既存のデータから新しいフィールドを計算すること。
Codeノードの仕組み
Codeノードは、ワークフローを通じて流れるitems配列上で動作します。各アイテムにはそのデータを保持するjsonと呼ばれるオブジェクトがあります。Codeノードを開くと、関数本体を記述します — n8nが自動的にラップしてくれるため、自分で関数を定義する必要はありません。
実行モードは2つあります。"All Itemsに対して1回実行"はitems変数経由で全アイテムに同時アクセスを提供します。"各アイテムに対して1回実行"は単一のアイテム変数を提供します。デフォルトで最も柔軟なモードは"All Itemsに対して1回実行"であり、本レッスンの焦点です。
このモードでは、コードは次の形のオブジェクトの配列を返す必要があります:
返された配列の各オブジェクトが1つの出力アイテムになります。空の配列を返す場合、0アイテムが前方へ渡されます。
Array Manipulation
上流ノードが注文のリストを渡し、それぞれのアイテムが products というオブジェクトの配列を持つ場合、各 product を独立したアイテムとして平坦化したい。
3つの注文アイテムから始まり、それぞれに4つの製品が含まれている場合、出力アイテムは12個になる。これは単純なケースに対して Split Out が可能だが、Code ノードを使えば親アイテムの計算済みコンテキストを同時に保持できる。
逆方向 — 複数のアイテムを1つにまとめる — を行うには reduce を使う。
String Formatting
String の変換は Code ノードを使う主な動機のひとつ。Expression エディターは簡単なケースを扱えるが、複数ステップのフォーマットはコードで行うときれいになる。
名前フィールドを正規化する例を示す。空白をトリムし、タイトルケースに変換し、表示ラベルを構築する。
spread operator ...item.json を使用すると、既存のすべてのフィールドを保持しつつ新しいフィールドをその上に追加するため、ダウンストリームのノードは元のデータを依然として見ることができる。
Computing New Fields
Code ノードは、新しいフィールドが複数の既存フィールドを跨ぐ計算に依存する場合に最適 — 合計値、誕生日からの年齢、ビジネスルールに基づくステータスフラグなど。
+value.toFixed(2) の使用に注意 — toFixed は文字列を返すため、単項の + で再び数値に変換する。これは、ダウンストリームのノードが数学や比較を行う場合、文字列と数値で挙動が異なるため重要である。
共通の間違い
出力を json に包むのを忘れることが最も頻繁なエラーです。 { name: 'Alice' } を返すのではなく { json: { name: 'Alice' } } と返すと、n8n がエラーを投げるかデータを黙って落とします。
item.json を直接変更して展開せずに変更すると、いくつかの n8n バージョンで予期しない副作用を引き起こす可能性があります — 常に新しいオブジェクトを作成してください。
await を、Code ノードを非同期対応としてマークせずに使用する:組み込みヘルパー like $node を呼び出したり、非同期操作を使う必要がある場合は、実行モードを考慮したロジックにしてください。上記の例のような標準の同期変換には特別な設定は不要です。
最後に、Code ノードは n8n Cloud では外部 npm パッケージにデフォルトでアクセスできません。セルフホストの n8n ではパッケージを許可リストに追加できますが、デプロイを自分で管理していない限り、コードをポータブルに書いてください。
要約
Code ノードは、組み込みノードでは表現できない変換を処理するための完全な JavaScript 環境を提供します。重要な習慣は、常に { json: ... } の配列を返すこと、追加したいフィールドだけを展開して既存のフィールドを保持することで、"全アイテムに対して一度だけ実行" を選択することです。
レッスンのチェックポイント
学んだ内容を復習し、回答へのフィードバックを受けましょう。