📚 suwa-sh / zenn-contents

← n8nガイド

第5章: 発展 - n8n を拡張する・深掘りする

第5章: 発展 - n8n を拡張する・深掘りする

この章では、n8n の基本機能をマスターしたユーザー向けに、より高度な使い方、カスタマイズ、そしてコミュニティとの関わり方について解説します。n8n の可能性をさらに広げましょう。

5.1. 高度なノードとテクニック

標準ノードの中でも特に強力な機能を持つノードや、それらを組み合わせた高度なテクニックを紹介します。

5.1.1. Function / Function Item ノードによるカスタムロジック

標準ノードだけでは実現できない、独自のデータ処理や複雑な条件分岐、外部ライブラリの利用などが必要な場合に活躍するのが Function ノード と Function Item ノード です。

  • Function ノード:

    • 入力された 全てのアイテム を一度に処理する JavaScript コードを記述できます。
    • アイテムの集計、全体的なデータの変換、複雑な API ロジックの実装などに適しています。
    • items という変数で入力アイテムの配列にアクセスできます。
    • 戻り値として新しいアイテムの配列を返す必要があります。

  • Function Item ノード:

    • 入力された 各アイテム に対して個別に JavaScript コードを実行します。
    • item という変数で現在のアイテムのデータ (item.json) にアクセスできます。
    • 各アイテムごとに処理を行い、その結果を返します。ループ処理 (SplitInBatches) と組み合わせずにアイテムごとのカスタム処理を行いたい場合に便利です。

例 (Function Item): アイテムの price と quantity を掛け合わせて total フィールドを追加する。

// Function Item ノードのコード例
item.json.total = item.json.price * item.json.quantity;
return item;

これらのノードを使いこなすことで、n8n の自動化能力は飛躍的に向上しますが、JavaScript の基本的な知識が必要になります。

5.1.2. HTTP Request ノードの高度な使い方

多くの Web サービスとの連携の基本となるノードです。基本的な GET/POST 以外にも様々な設定が可能です。

  • 認証: Basic Auth, OAuth1, OAuth2 など、様々な認証方式に対応した Credential を利用できます。
  • ヘッダー: カスタムヘッダー（Authorization, Content-Type, User-Agent など）を追加・変更できます。
  • ボディ:
    • Body Content Type: JSON, Form-Data URL Encoded, Raw, Binary Data など、送信するデータの形式を選択できます。
    • Body Parameters: Form-Data や JSON のキーと値を指定します。式も利用可能です。
    • Raw Data: XML やカスタムフォーマットのデータを直接入力できます。
  • オプション:
    • Split Into Items: レスポンスが配列の場合、各要素を個別のアイテムとして出力します。
    • Response Format: レスポンスが JSON 以外（XML, Text, File など）の場合に指定します。
    • Ignore Response Code: 特定の HTTP ステータスコード（例: 404 Not Found）をエラーとして扱わないように設定できます。
    • Timeout: リクエストのタイムアウト時間を設定します。

5.1.3. Wait ノード、Execute Workflow ノードなど

  • Wait ノード:
    • 指定した時間だけ待機 (Wait for Time)。
    • 特定の時刻まで待機 (Wait until Time)。
    • Webhook を待ち受けて、特定の条件を満たすリクエストが来るまで待機 (Wait for Webhook)。
    • API ポーリングの間隔調整や、外部プロセスの完了待ちなどに利用します。
  • Execute Workflow ノード:
    • 別のワークフローを呼び出し、その実行結果を受け取ることができます。
    • 共通処理をサブルーチンのように別ワークフローに切り出して再利用する際に便利です。
    • 同期実行（呼び出し元が完了を待つ）と非同期実行（呼び出し元は待たずに次へ進む）を選択できます。
  • Merge ノード: 複数の処理経路からのデータを結合する際に、キーに基づいて結合 (Merge By Key) したり、単純に連結 (Append) したりするモードを使い分けることで、複雑なデータフローを制御できます。
  • Switch ノード: IF ノードよりも多くの分岐条件を扱いたい場合に便利です。入力データの特定の値に基づいて、複数の出力パスに処理を振り分けます。

5.2. n8n API の活用

n8n は自身の機能を操作するための REST API を提供しています。これにより、外部のアプリケーションやスクリプトから n8n を制御できます。

5.2.1. API キーの生成と管理

  1. n8n UI の左下にあるユーザーアイコンをクリックし、「API Keys」を選択します。
  2. 「Create API Key」をクリックし、キーの名前を入力して生成します。
  3. 生成された API キーは 一度しか表示されません。必ず安全な場所にコピーして保管してください。
  4. この API キーを HTTP リクエストの X-N8N-API-KEY ヘッダーに含めることで、API への認証を行います。

5.2.2. API エンドポイント概要 (ワークフロー、実行履歴など)

n8n API では、以下のような操作が可能です（詳細は公式 API ドキュメントを参照）。

  • ワークフロー:
    • GET /api/v1/workflows: ワークフローの一覧を取得。
    • GET /api/v1/workflows/{id}: 特定のワークフロー定義を取得。
    • POST /api/v1/workflows: 新しいワークフローを作成。
    • PUT /api/v1/workflows/{id}: 既存のワークフローを更新。
    • DELETE /api/v1/workflows/{id}: ワークフローを削除。
    • POST /api/v1/workflows/{id}/activate: ワークフローをアクティブ化。
    • POST /api/v1/workflows/{id}/deactivate: ワークフローを非アクティブ化。
  • 実行:
    • POST /api/v1/workflows/{id}/run: ワークフローを手動で実行（同期実行）。
    • POST /api/v1/webhooks/{webhook-id}: Webhook トリガーを持つワークフローを実行（非同期実行）。
  • 実行履歴:
    • GET /api/v1/executions: 実行履歴の一覧を取得。
    • GET /api/v1/executions/{id}: 特定の実行の詳細を取得。
    • DELETE /api/v1/executions/{id}: 特定の実行履歴を削除。
  • 認証情報 (Credentials):
    • GET /api/v1/credentials: 認証情報の一覧を取得（実際のキーなどは含まれません）。
    • POST /api/v1/credentials: 新しい認証情報を作成。

5.2.3. 外部からのワークフロー実行・制御例

例: curl を使って Webhook トリガーを実行

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message": "APIからのテスト通知"}' \
  <YOUR_N8N_INSTANCE_URL>/webhook/<YOUR_WEBHOOK_ID>

例: Python スクリプトでワークフローをアクティブ化

import requests
import json

N8N_URL = "http://localhost:5678" # またはあなたの n8n インスタンス URL
API_KEY = "YOUR_N8N_API_KEY"
WORKFLOW_ID = "YOUR_WORKFLOW_ID" # アクティブ化したいワークフローのID

headers = {
    "Accept": "application/json",
    "X-N8N-API-KEY": API_KEY,
}

response = requests.post(f"{N8N_URL}/api/v1/workflows/{WORKFLOW_ID}/activate", headers=headers)

if response.status_code == 200:
    print("Workflow activated successfully.")
    print(response.json())
else:
    print(f"Error activating workflow: {response.status_code}")
    print(response.text)

n8n API を使うことで、CI/CD パイプラインでのワークフローのデプロイ、外部システムからの動的なワークフロー起動、運用管理タスクの自動化などが可能になります。

5.3. カスタムノード開発入門

n8n の大きな魅力の一つは、独自のノードを作成して機能を拡張できる点です。標準で提供されていないサービスとの連携や、特定の複雑な処理を再利用可能なノードとしてカプセル化したい場合に役立ちます。

5.3.1. 開発環境の準備

カスタムノード開発には、以下の環境が必要です。

  1. Node.js と npm: n8n 本体や開発ツールが Node.js で動作するため。
  2. n8n ソースコード: n8n の GitHub リポジトリをクローンまたはダウンロードします。
  3. 開発用 n8n インスタンス: 開発中のノードをテストするために、ローカルで n8n を起動します (npm run dev コマンドを使用)。
  4. テキストエディタ/IDE: Visual Studio Code など、TypeScript の開発に適したエディタ。

基本的な手順は、n8n のソースコード内の packages/nodes-base/nodes ディレクトリに、新しいノード用のディレクトリとファイルを作成し、開発を進めます。

5.3.2. ノードの基本構造と作成手順

カスタムノードは主に TypeScript で記述されます。基本的なファイル構成は以下のようになります。

  • YourNodeName.node.ts: ノードの定義ファイル。
    • ノードの名前、アイコン、カテゴリ、プロパティ（設定項目）、入力/出力などを定義します。
    • execute メソッド: ノードが実行されたときの主要なロジックを記述します。ここでデータの取得、加工、API 呼び出しなどを行います。
  • YourNodeName.node.json (任意): ノードのメタデータ（説明文など）。
  • icons/YourNodeName.png or .svg (任意): ノードのアイコンファイル。

作成手順の概要:

  1. n8n リポジトリのクローンとセットアップ:
    git clone [https://github.com/n8n-io/n8n.git](https://github.com/n8n-io/n8n.git)
cd n8n
npm install
npm run build
  2. ノード用ディレクトリ作成: packages/nodes-base/nodes/ 以下にサービス名などでディレクトリを作成 (例: MyService)。
  3. ノードファイル作成: 作成したディレクトリ内に MyService.node.ts ファイルを作成します。
  4. ノード定義: MyService.node.ts に、INodeType インターフェースを実装するクラスを定義します。description オブジェクトでノードの基本情報、プロパティ、実行メソッドを記述します。
  5. 実装: execute メソッド内にノードの処理ロジックを実装します。入力データを取得し、処理を行い、結果を n8n のデータ構造に合わせて返します。
  6. ビルド: n8n プロジェクトのルートで npm run build を実行して、TypeScript コードを JavaScript にコンパイルします。
  7. テスト: npm run dev で開発モードの n8n を起動し、エディタで作成したノードが表示されるか、意図通りに動作するかを確認します。

詳細は n8n の公式ドキュメントにある「Creating Nodes」セクションを参照してください。

5.3.3. コミュニティノードの利用

n8n コミュニティでは、多くのユーザーが独自に開発したカスタムノードを公開しています。

  • 探し方:
    • n8n 公式サイトの「Integrations」ページ。
    • n8n コミュニティフォーラム (community.n8n.io)。
    • npm レジストリで n8n-nodes- プレフィックスを持つパッケージを検索。
  • インストール方法 (Self-Hosted):
    • 環境変数: NODE_FUNCTION_ALLOW_EXTERNAL 環境変数にインストールしたい npm パッケージ名を追加します（例: NODE_FUNCTION_ALLOW_EXTERNAL=n8n-nodes-package-name）。
    • Docker: Dockerfile をカスタマイズして npm install -g n8n-nodes-package-name を実行するか、n8n コンテナ起動後にコンテナ内に入ってインストールします。
    • npm/npx: n8n をグローバルまたはローカルにインストールしている場合は、npm install n8n-nodes-package-name でインストールできます。
  • n8n Cloud: 現時点では、n8n Cloud 環境に任意のコミュニティノードを自由に追加することはできません。利用したいノードがあれば、n8n チームにリクエストするか、Self-Hosted 環境を検討する必要があります。

5.4. n8n の組み込み (Embedding)

n8n の機能を自身の Web アプリケーションやサービスに組み込むことができます。これにより、ユーザーに対してアプリケーション内で直接ワークフロー自動化機能を提供することが可能になります。

5.4.1. 組み込みのユースケースと方法

  • ユースケース:
    • SaaS プロダクトに、顧客が独自の連携を設定できる機能を追加する。
    • 社内ポータルに、特定の業務プロセスを自動化するワークフロー作成機能を提供する。
    • データ分析プラットフォームに、データ取得や加工のワークフローを組み込む。
  • 方法:
    • n8n-js-sdk: n8n が提供する JavaScript SDK を使用して、フロントエンドアプリケーションに n8n エディタやワークフローリストなどを埋め込むことができます。認証やデータの受け渡しなどを制御できます。
    • iFrame: よりシンプルな方法として、n8n の UI を iFrame を使って埋め込むことも可能ですが、カスタマイズ性や連携の自由度は SDK を使う場合に比べて低くなります。
    • API 連携: UI の組み込みは行わず、n8n API を通じてバックエンド間でワークフローの管理や実行を行う方法もあります。

組み込みには、認証やユーザー管理、データセキュリティなど、考慮すべき点が多くあります。詳細は n8n の公式ドキュメントや Enterprise プランの情報を参照してください。

5.5. コミュニティと学習リソース

n8n を効果的に活用するためには、公式ドキュメントや活発なコミュニティの利用が不可欠です。

5.5.1. 公式ドキュメントの歩き方

n8n の公式サイト (docs.n8n.io) には、非常に充実したドキュメントが用意されています。

  • Getting Started: インストール、基本操作、最初のワークフロー作成など。
  • Concepts: ワークフロー、ノード、データ構造、式などの基本概念の説明。
  • Nodes Reference: 各標準ノードの詳細な説明、パラメータ、使用例。連携したいサービス名で検索すると便利です。
  • How-to Guides: 特定のタスク（例: エラーハンドリング、ループ処理）を実現するための具体的な手順。
  • API: n8n API のエンドポイント、認証方法、リクエスト/レスポンス例。
  • Development: カスタムノード開発や n8n 本体への貢献に関する情報。

まずは「Getting Started」と「Concepts」を一読し、その後は必要に応じて「Nodes Reference」や「How-to Guides」を参照するのが効率的です。

5.5.2. コミュニティフォーラム活用術

n8n コミュニティフォーラム (community.n8n.io) は、ユーザー同士が質問したり、知識を共有したり、ワークフローのアイデアを交換したりする活発な場所です。

  • 検索: 質問する前に、類似の質問や問題が過去に投稿されていないか検索してみましょう。
  • 質問:
    • 具体的な状況（n8n のバージョン、実行環境、ワークフローの概要、エラーメッセージなど）を詳しく記述します。
    • 可能であれば、ワークフローの JSON (個人情報は削除したもの) を添付すると回答が得やすくなります。
    • 明確で簡潔なタイトルをつけましょう。
  • 情報収集: 他のユーザーが共有しているワークフロー例や Tips は非常に参考になります。
  • 貢献: 自分の知識や経験を共有し、他のユーザーの質問に答えることも歓迎されます。

5.5.3. n8n プロジェクトへの貢献方法

n8n はオープンソースプロジェクトであり、コミュニティからの貢献を歓迎しています。

  • バグ報告: GitHub Issues でバグの詳細を報告します。再現手順や環境情報を明確に記載することが重要です。
  • 機能リクエスト: コミュニティフォーラムの「Feature Requests」カテゴリで新しい機能や改善案を提案します。
  • ドキュメント改善: ドキュメントの誤りや分かりにくい箇所を見つけたら、GitHub 上で修正提案（Pull Request）を送ることができます。
  • コミュニティノード開発: 自分で作成した便利なノードを npm に公開し、コミュニティで共有します。
  • コードコントリビューション: n8n 本体のコード改善やバグ修正に貢献します（開発スキルが必要です）。

コミュニティへの参加は、n8n をより深く理解し、プロジェクトの発展を支援する素晴らしい方法です。