n8n-code-python

Python コードノード（ベータ）

n8n の Code ノードで Python コードを記述するための専門的なガイダンスです。

---

⚠️ 重要：まずは JavaScript

推奨事項：ユースケースの 95% では JavaScript を使用してください。Python を使用するのは、次の場合に限ります。

• Python 標準ライブラリの特定の関数が必要な場合
• Python の構文のほうが大幅に使い慣れている場合
• Python により適したデータ変換を行う場合

JavaScript が推奨される理由：

• n8n のヘルパー関数をすべて使用できます（$helpers.httpRequest など）
• 高度な日付／時刻操作に使える Luxon DateTime ライブラリ
• 外部ライブラリに関する制限がありません
• n8n のドキュメントとコミュニティサポートが充実しています

---

クイックスタート

# Basic template for Python Code nodes
items = _input.all()

# Process data
processed = []
for item in items:
    processed.append({
        "json": {
            **item["json"],
            "processed": True,
            "timestamp": datetime.now().isoformat()
        }
    })

return processed

必須ルール

1. まず JavaScript を検討する - 必要な場合に限り Python を使用します
2. データにアクセスする：_input.all()、_input.first()、または _input.item
3. 重要：[{"json": {...}}] 形式で返す必要があります
4. 重要：Webhook データは _json 直下ではなく、_json["body"] の下にあります
5. 重大な制限：外部ライブラリは使用できません（requests、pandas、numpy など）
6. 標準ライブラリのみ：json、datetime、re、base64、hashlib、urllib.parse、math、random、statistics

---

モード選択ガイド

JavaScript と同様に、ユースケースに応じて選択します。

すべてのアイテムに対して 1 回実行（推奨 - デフォルト）

このモードの用途： ユースケースの 95%

• 動作：入力数に関係なく、コードを1 回実行します
• データアクセス：_input.all() または _items 配列（ネイティブモード）
• 最適な用途：集計、フィルタリング、バッチ処理、変換
• パフォーマンス：複数のアイテムを処理する場合に高速です（実行は 1 回）

# Example: Calculate total from all items
all_items = _input.all()
total = sum(item["json"].get("amount", 0) for item in all_items)

return [{
    "json": {
        "total": total,
        "count": len(all_items),
        "average": total / len(all_items) if all_items else 0
    }
}]

各アイテムに対して 1 回実行

このモードの用途： 特定のケースのみ

• 動作：入力アイテムごとにコードを個別に実行します
• データアクセス：_input.item または _item（ネイティブモード）
• 最適な用途：アイテム固有のロジック、個別の操作、アイテムごとの検証
• パフォーマンス：大規模なデータセットでは低速です（複数回実行）

# Example: Add processing timestamp to each item
item = _input.item

return [{
    "json": {
        **item["json"],
        "processed": True,
        "processed_at": datetime.now().isoformat()
    }
}]

---

Python モード：ベータ版とネイティブ

n8n には、Python の実行モードが 2 つあります。

Python（ベータ）- 推奨

• 使用するもの：_input、_json、_node のヘルパー構文
• 最適な用途：ほとんどの Python のユースケース
• 利用可能なヘルパー：_now、_today、_jmespath()
• インポート：from datetime import datetime

# Python (Beta) example
items = _input.all()
now = _now  # Built-in datetime object

return [{
    "json": {
        "count": len(items),
        "timestamp": now.isoformat()
    }
}]

Python（ネイティブ）（ベータ）

• 使用するもの：_items、_item 変数のみ
• ヘルパーなし：_input、_now などはありません
• 制限が多い：標準の Python のみ
• 使用する場面：n8n ヘルパーを使わず、純粋な Python が必要な場合

# Python (Native) example
processed = []

for item in _items:
    processed.append({
        "json": {
            "id": item["json"].get("id"),
            "processed": True
        }
    })

return processed

推奨事項：n8n との連携がより優れている Python（ベータ） を使用してください。

---

データアクセスパターン

パターン 1：_input.all() - 最も一般的

使用する場面：配列の処理、バッチ操作、集計

# Get all items from previous node
all_items = _input.all()

# Filter, transform as needed
valid = [item for item in all_items if item["json"].get("status") == "active"]

processed = []
for item in valid:
    processed.append({
        "json": {
            "id": item["json"]["id"],
            "name": item["json"]["name"]
        }
    })

return processed

パターン 2：_input.first() - よく使われる

使用する場面：単一のオブジェクト、API レスポンスを扱う場合

# Get first item only
first_item = _input.first()
data = first_item["json"]

return [{
    "json": {
        "result": process_data(data),
        "processed_at": datetime.now().isoformat()
    }
}]

パターン 3：_input.item - 各アイテムモードのみ

使用する場面：「各アイテムに対して 1 回実行」モードの場合

# Current item in loop (Each Item mode only)
current_item = _input.item

return [{
    "json": {
        **current_item["json"],
        "item_processed": True
    }
}]

パターン 4：_node - 他のノードを参照

使用する場面：ワークフロー内の特定のノードからデータが必要な場合

# Get output from specific node
webhook_data = _node["Webhook"]["json"]
http_data = _node["HTTP Request"]["json"]

return [{
    "json": {
        "combined": {
            "webhook": webhook_data,
            "api": http_data
        }
    }
}]

参照：DATA_ACCESS.md の包括的なガイド

---

重要：Webhook のデータ構造

最もよくある間違い：Webhook データは ["body"] の下にネストされています

# ❌ WRONG - Will raise KeyError
name = _json["name"]
email = _json["email"]

# ✅ CORRECT - Webhook data is under ["body"]
name = _json["body"]["name"]
email = _json["body"]["email"]

# ✅ SAFER - Use .get() for safe access
webhook_data = _json.get("body", {})
name = webhook_data.get("name")

理由：Webhook ノードは、リクエストデータ全体を body プロパティの下に格納します。これには POST データ、クエリパラメーター、JSON ペイロードが含まれます。

参照：Webhook のデータ構造の詳細は DATA_ACCESS.md をご覧ください

---

戻り値の形式に関する要件

重要なルール：必ず "json" キーを持つ辞書のリストを返してください

正しい戻り値の形式

# ✅ Single result
return [{
    "json": {
        "field1": value1,
        "field2": value2
    }
}]

# ✅ Multiple results
return [
    {"json": {"id": 1, "data": "first"}},
    {"json": {"id": 2, "data": "second"}}
]

# ✅ List comprehension
transformed = [
    {"json": {"id": item["json"]["id"], "processed": True}}
    for item in _input.all()
    if item["json"].get("valid")
]
return transformed

# ✅ Empty result (when no data to return)
return []

# ✅ Conditional return
if should_process:
    return [{"json": processed_data}]
else:
    return []

誤った戻り値の形式

# ❌ WRONG: Dictionary without list wrapper
return {
    "json": {"field": value}
}

# ❌ WRONG: List without json wrapper
return [{"field": value}]

# ❌ WRONG: Plain string
return "processed"

# ❌ WRONG: Incomplete structure
return [{"data": value}]  # Should be {"json": value}

重要な理由：後続のノードはリスト形式を想定しています。形式が誤っていると、ワークフローの実行に失敗します。

参照：詳しいエラー解決方法は ERROR_PATTERNS.md #2 をご覧ください

---

重大な制限：外部ライブラリは使用不可

Python の最も重要な制限：外部パッケージをインポートできません

使用できないもの

# ❌ NOT AVAILABLE - Will raise ModuleNotFoundError
import requests  # ❌ No
import pandas  # ❌ No
import numpy  # ❌ No
import scipy  # ❌ No
from bs4 import BeautifulSoup  # ❌ No
import lxml  # ❌ No

利用可能なもの（標準ライブラリ）

# ✅ AVAILABLE - Standard library only
import json  # ✅ JSON parsing
import datetime  # ✅ Date/time operations
import re  # ✅ Regular expressions
import base64  # ✅ Base64 encoding/decoding
import hashlib  # ✅ Hashing functions
import urllib.parse  # ✅ URL parsing
import math  # ✅ Math functions
import random  # ✅ Random numbers
import statistics  # ✅ Statistical functions

回避策

HTTP リクエストが必要ですか？

• ✅ Code ノードの前に HTTP Request ノードを使用します
• ✅ または JavaScriptに切り替えて $helpers.httpRequest() を使用します

データ分析（pandas/numpy）が必要ですか？

• ✅ 基本的な統計には Python の statistics モジュールを使用します
• ✅ または、ほとんどの操作は JavaScriptに切り替えて実行します
• ✅ リストと辞書を使って手動で計算します

ウェブスクレイピング（BeautifulSoup）が必要ですか？

• ✅ HTTP Request ノードとHTML Extract ノードを使用します
• ✅ または、正規表現や文字列メソッドを使う JavaScriptに切り替えます

参照：STANDARD_LIBRARY.mdで完全なリファレンスを確認してください

---

よく使うパターンの概要

本番ワークフローに基づく、最も便利な Python パターンを紹介します。

1. データ変換

リスト内包表記ですべてのアイテムを変換します

items = _input.all()

return [
    {
        "json": {
            "id": item["json"].get("id"),
            "name": item["json"].get("name", "Unknown").upper(),
            "processed": True
        }
    }
    for item in items
]

2. フィルタリングと集計

組み込み関数で合計、フィルタリング、カウントを行います

items = _input.all()
total = sum(item["json"].get("amount", 0) for item in items)
valid_items = [item for item in items if item["json"].get("amount", 0) > 0]

return [{
    "json": {
        "total": total,
        "count": len(valid_items)
    }
}]

3. 正規表現による文字列処理

テキストからパターンを抽出します

import re

items = _input.all()
email_pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'

all_emails = []
for item in items:
    text = item["json"].get("text", "")
    emails = re.findall(email_pattern, text)
    all_emails.extend(emails)

# Remove duplicates
unique_emails = list(set(all_emails))

return [{
    "json": {
        "emails": unique_emails,
        "count": len(unique_emails)
    }
}]

4. データ検証

データを検証して整えます

items = _input.all()
validated = []

for item in items:
    data = item["json"]
    errors = []

    # Validate fields
    if not data.get("email"):
        errors.append("Email required")
    if not data.get("name"):
        errors.append("Name required")

    validated.append({
        "json": {
            **data,
            "valid": len(errors) == 0,
            "errors": errors if errors else None
        }
    })

return validated

5. 統計分析

statistics モジュールで統計量を計算します

from statistics import mean, median, stdev

items = _input.all()
values = [item["json"].get("value", 0) for item in items if "value" in item["json"]]

if values:
    return [{
        "json": {
            "mean": mean(values),
            "median": median(values),
            "stdev": stdev(values) if len(values) > 1 else 0,
            "min": min(values),
            "max": max(values),
            "count": len(values)
        }
    }]
else:
    return [{"json": {"error": "No values found"}}]

参照：COMMON_PATTERNS.mdで、詳しい Python パターンを10種類確認してください

---

エラーの予防 — よくある間違いトップ5

#1：外部ライブラリのインポート（Python 固有！）

# ❌ WRONG: Trying to import external library
import requests  # ModuleNotFoundError!

# ✅ CORRECT: Use HTTP Request node or JavaScript
# Add HTTP Request node before Code node
# OR switch to JavaScript and use $helpers.httpRequest()

#2：コードが空、または return がない

# ❌ WRONG: No return statement
items = _input.all()
# Processing...
# Forgot to return!

# ✅ CORRECT: Always return data
items = _input.all()
# Processing...
return [{"json": item["json"]} for item in items]

#3：戻り値の形式が正しくない

# ❌ WRONG: Returning dict instead of list
return {"json": {"result": "success"}}

# ✅ CORRECT: List wrapper required
return [{"json": {"result": "success"}}]

#4：辞書へのアクセス時の KeyError

# ❌ WRONG: Direct access crashes if missing
name = _json["user"]["name"]  # KeyError!

# ✅ CORRECT: Use .get() for safe access
name = _json.get("user", {}).get("name", "Unknown")

#5：Webhook の本文のネスト

# ❌ WRONG: Direct access to webhook data
email = _json["email"]  # KeyError!

# ✅ CORRECT: Webhook data under ["body"]
email = _json["body"]["email"]

# ✅ BETTER: Safe access with .get()
email = _json.get("body", {}).get("email", "no-email")

参照：ERROR_PATTERNS.mdで、エラーに関する包括的なガイドを確認してください

---

標準ライブラリのリファレンス

最も便利なモジュール

# JSON operations
import json
data = json.loads(json_string)
json_output = json.dumps({"key": "value"})

# Date/time
from datetime import datetime, timedelta
now = datetime.now()
tomorrow = now + timedelta(days=1)
formatted = now.strftime("%Y-%m-%d")

# Regular expressions
import re
matches = re.findall(r'\d+', text)
cleaned = re.sub(r'[^\w\s]', '', text)

# Base64 encoding
import base64
encoded = base64.b64encode(data).decode()
decoded = base64.b64decode(encoded)

# Hashing
import hashlib
hash_value = hashlib.sha256(text.encode()).hexdigest()

# URL parsing
import urllib.parse
params = urllib.parse.urlencode({"key": "value"})
parsed = urllib.parse.urlparse(url)

# Statistics
from statistics import mean, median, stdev
average = mean([1, 2, 3, 4, 5])

参照：STANDARD_LIBRARY.mdで完全なリファレンスを確認してください

---

ベストプラクティス

1. 辞書へのアクセスには常に .get() を使用する

# ✅ SAFE: Won't crash if field missing
value = item["json"].get("field", "default")

# ❌ RISKY: Crashes if field doesn't exist
value = item["json"]["field"]

2. None/Null 値を明示的に処理する

# ✅ GOOD: Default to 0 if None
amount = item["json"].get("amount") or 0

# ✅ GOOD: Check for None explicitly
text = item["json"].get("text")
if text is None:
    text = ""

3. フィルタリングにはリスト内包表記を使用する

# ✅ PYTHONIC: List comprehension
valid = [item for item in items if item["json"].get("active")]

# ❌ VERBOSE: Manual loop
valid = []
for item in items:
    if item["json"].get("active"):
        valid.append(item)

4. 一貫した構造を返す

# ✅ CONSISTENT: Always list with "json" key
return [{"json": result}]  # Single result
return results  # Multiple results (already formatted)
return []  # No results

5. print() 文でデバッグする

# Debug statements appear in browser console (F12)
items = _input.all()
print(f"Processing {len(items)} items")
print(f"First item: {items[0] if items else 'None'}")

---

Python と JavaScript の使い分け

Python を使う場合：

• ✅ 統計処理に statistics モジュールが必要な場合
• ✅ Python の構文のほうが格段に使いやすい場合
• ✅ ロジックをリスト内包表記にうまく対応させられる場合
• ✅ 特定の標準ライブラリ関数が必要な場合

JavaScript を使う場合：

• ✅ HTTP リクエスト（$helpers.httpRequest()）が必要な場合
• ✅ 高度な日付／時刻機能（DateTime/Luxon）が必要な場合
• ✅ n8n との連携を強化したい場合
• ✅ ユースケースの95%で（推奨）

他のノードを検討する場合：

• ❌ 単純なフィールドのマッピング → Set ノードを使用します
• ❌ 基本的なフィルタリング → Filter ノードを使用します
• ❌ 単純な条件分岐 → IF または Switch ノードを使用します
• ❌ HTTP リクエストのみ → HTTP Request ノードを使用します

---

他のスキルとの連携

連携するもの：

n8n Expression Syntax：

• 他のノードでは {{ }} 構文で式を記述します
• Code ノードでは Python を直接使用します（{{ }} は不要です）
• 式とコードを使い分けるタイミング

n8n MCP Tools Expert：

• Code ノードの検索方法：search_nodes({query: "code"})
• 設定のヘルプの取得方法：get_node_essentials("nodes-base.code")
• コードの検証方法：validate_node_operation()

n8n Node Configuration：

• モードの選択（すべてのアイテム／各アイテム）
• 言語の選択（Python／JavaScript）
• プロパティの依存関係の理解

n8n Workflow Patterns：

• 変換ステップでの Code ノードの使用
• パターンで Python と JavaScript を使い分けるタイミング

n8n Validation Expert：

• Code ノードの設定を検証する
• 検証エラーに対処する
• よくある問題を自動修正する

n8n Code JavaScript：

• 代わりに JavaScript を使用するタイミング
• JavaScript と Python の機能の比較
• Python から JavaScript への移行

---

クイックリファレンスチェックリスト

Python Code ノードをデプロイする前に、以下を確認してください。

• まず JavaScript を検討しましたか - 必要な場合にのみ Python を使用します
• コードは空ではありませんか - 意味のあるロジックが必要です
• return 文がありますか - 辞書のリストを返す必要があります
• 戻り値の形式は適切ですか - 各項目は {"json": {...}} です
• データへのアクセス方法は正しいですか - _input.all()、_input.first()、または _input.item を使用します
• 外部インポートはありませんか - 標準ライブラリ（json、datetime、re など）のみを使用します
• 辞書へのアクセスは安全ですか - KeyError を防ぐために .get() を使用します
• Webhook データですか - Webhook からのデータの場合は ["body"] を介してアクセスします
• モードは適切に選択されていますか - ほとんどの場合は「All Items」を選択します
• 出力に一貫性はありますか - すべてのコードパスで同じ構造を返します

---

追加リソース

関連ファイル

• DATA_ACCESS.md - Python でのデータアクセスパターンの詳細
• COMMON_PATTERNS.md - n8n 向け Python パターン 10 選
• ERROR_PATTERNS.md - よくあるエラー 5 件と解決方法
• STANDARD_LIBRARY.md - 標準ライブラリの完全なリファレンス

n8n ドキュメント

• Code ノードガイド：https://docs.n8n.io/code/code-node/
• n8n での Python：https://docs.n8n.io/code/builtin/python-modules/

---

n8n の Code ノードで Python を使う準備はできています。ただし、まず JavaScript を検討してください！ 特定の要件がある場合に Python を使用し、よくあるミスを避けるためにエラーパターンガイドを参照して、標準ライブラリを効果的に活用してください。