mcpField
N
n8n-binary-and-data-official

n8n-binary-and-data-official

github.com/n8n-ioデータ・データベース5582.0k 回インストール2 週間前に更新
リポジトリ

n8n-binary-and-data-official について

n8n-binary-and-data-officialは、バイナリデータとJSONを扱うn8nワークフロー開発者向けのガイドです。それぞれの保存・受け渡し方法、エージェントツールのファイル制約、チャットでの表示要件を説明します。

主な機能

  1. 01$binaryと$jsonの区別
  2. 02バイナリデータの読み書き
  3. 03エージェントツールのファイル制約
  4. 04Mergeによるバイナリの保持
  5. 05チャット画像に必要なURL

活用シーン

  1. 01ワークフロー内でファイルを読み取り、受け渡す
  2. 02ストレージキー経由でエージェントツールにアップロードファイルを渡す
  3. 03JSON変換後もバイナリを保持する
  4. 04チャットメッセージに生成画像を表示する

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/n8n-io/skills --skill n8n-binary-and-data-official

インストール後、Claude Code で/n8n-binary-and-data-officialを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
AGENT_TOOL_BINARY.md
BINARY_BASICS.md
CDN_REQUIREMENT.md
MERGE_FOR_CONTEXT.md

詳細

n8n のバイナリとデータ

n8n では、JSON（$json 内）とバイナリ（$binary 内）の 2 種類のデータを並行して扱います。エージェントツール、ストレージ、表示コンテキスト（チャット画面、メッセージのレンダリング）では、バイナリの扱いに注意が必要です。

表形式ストレージ（Data Tables）については、n8n-data-tables-official スキルを参照してください。

必ず守ること

  1. バイナリは$jsonではなく$binaryにあります。 ファイルの内容を$jsonから読み取らないでください。
  2. バイナリは、どちらの方向にもエージェントツールの境界を越えられません。 ツールのパラメーターは JSON のみ（fromAi()経由）で、ツールの結果も JSON のみです。バイナリはあらかじめストレージに格納し、JSON 経由でキーや URL を渡してください。エージェントのpassthroughBinaryImages: trueを使うと、LLM はアップロードされた画像をビジョン用途で見ることができますが、ツールが画像を受け取れるようにはなりません。詳しくはreferences/AGENT_TOOL_BINARY.mdを参照してください。

推奨されるデフォルト

  • マージノードはバイナリをコンテキスト内に保持します。 途中の処理でバイナリが取り除かれた場合は、再取得するのではなく、マージして戻してください。詳しくはreferences/MERGE_FOR_CONTEXT.mdを参照してください。

バイナリの基本

n8n では、各アイテムに 2 つのスロットがあります。

{
    json: { ... },           // your data
    binary: {                // your files
        data: {              // 'data' is the typical key; can be any name
            data: '<base64>',
            mimeType: 'application/pdf',
            fileName: 'invoice.pdf',
            fileExtension: 'pdf',
        },
    },
}

$binary.<key>を使うと、指定したプロパティを読み取れます。ほとんどのファイル処理ノードには、$binary内のキーを指定するbinaryPropertyNameパラメーターがあります。

バイナリの設定

ファイルを生成するノード（バイナリレスポンスを使う HTTP Request、Read Files など）は、$binaryに自動的に値を設定します。Code ノードでバイナリを生成するには、次のようにします。

return [{
    json: { ... },
    binary: {
        data: {
            data: Buffer.from(content).toString('base64'),
            mimeType: 'text/plain',
            fileName: 'output.txt',
        },
    },
}]
バイナリの読み取り
// In a Code node
const buffer = await this.helpers.getBinaryDataBuffer(0, 'data')
const text = buffer.toString('utf-8')

ほとんどのワークフローでは、バイナリを直接読み取る必要はありません。コンシューマーノード（メール添付、ファイルのアップロードなど）にそのまま渡してください。

詳しくはreferences/BINARY_BASICS.mdを参照してください。

エージェントツールでのバイナリの扱い

エージェントツール（AI Agent ノードに接続されたサブワークフロー、ファーストクラスの n8n Agent、または MCP ツールとして公開されたワークフロー）には、パラメーターと結果をバイナリではなく JSON にするという制約があります。これは、どちらの方向にも当てはまります。

受信（ユーザーのアップロード → ツールで処理）： チャットトリガーからfiles[]が渡されます。エージェントでpassthroughBinaryImages: trueを設定するとビジョン用途で画像を扱えますが、fromAi()でバイナリをツールに渡すことはできません。そのため、次のようにします。

  1. アップロードされたファイルをあらかじめ格納します。キーをハッシュ化し、プライベートストレージにアップロードしてください。
  2. エージェントのシステムプロンプトにキーを挿入します。「渡されたファイル：[{originalFileName, fileName}]。ツールを呼び出す際は、fileNameフィールドを必ずそのまま使用してください。」
  3. ツールのfromAi('imageName', '...', 'string')でキーを受け取り、サブワークフローからストレージ上のファイルをダウンロードします。

送信（ツールで生成 → エージェントから返却）： ツールでファイルを生成しても、生のバイナリを返すことはできません。

  1. 内部でバイナリを生成します。
  2. ストレージにアップロードし、URL またはキーを取得します。
  3. JSON を返します：{ ok: true, file_id: '...', url: '...' }。
  4. エージェントの応答に URL を埋め込むか、別のツールでキーを使ってファイルを取得します。

時間のかかるツール向けの Webhook 経由の非同期処理パターンも含む全体の手順については、references/AGENT_TOOL_BINARY.mdを参照してください。

コンテキスト内でバイナリを保持するためのマージ

JSON のみを扱う操作（Edit Fields、Code、IF）では、アイテムからバイナリが取り除かれることがよくあります。保持するには、次のようにします。

[Source with binary] ─┬─→ [Edit Fields: transform JSON] ─┐
                      │                                    ├─→ [Merge: by position] ─→ [Email with attachment]
                      └─────────────────────────────────────┘

マージでストリームを結合すると、バイナリも保持されます。詳しくはreferences/MERGE_FOR_CONTEXT.mdを参照してください。

チャット画面での CDN の要件

ワークフローで画像を生成し、ユーザーがチャットメッセージ（Slack、Discord、Teams、Telegram、埋め込み型 Webhook チャットなど）内に表示したい場合：

  • アイテムにバイナリがあるだけでは不十分です。 チャット画面は$binaryを読み取りません。URL で画像を参照するメッセージをレンダリングするか、プラットフォーム固有のファイルアップロード API を使用します。
  • 画像を URL で取得できる場所に保存する必要があります。 まず CDN またはオブジェクトストレージにアップロードしてください。
  • このストレージはユーザーが設定します。 n8n に組み込まれているものではありません。

一般的な選択肢には、オブジェクトストレージ（S3、R2、GCS、Azure Blob、Vercel Blob、Supabase Storage）や、ドライブ型のサービス（Dropbox、Google Drive、OneDrive、Box）があります。S3 をデフォルトとせず、ユーザーが何を使っているか確認してください。

詳しくはreferences/CDN_REQUIREMENT.mdを参照してください。

Data Tables

Data Tables については、n8n-data-tables-official スキルを参照してください。他とは異なる仕様があり、独自の注意点（デフォルトの列、外部キーがないこと、JSON 列型がないこと、手動マッピング UI の挙動の癖）があります。

参考ファイル

ファイル読むタイミング
references/BINARY_BASICS.mdバイナリを初めて扱うとき、または$binaryスロットを読み書きするとき
references/AGENT_TOOL_BINARY.mdエージェントツールでユーザーがアップロードしたファイルが必要なとき、またはファイルを生成するとき（どちらの方向でも境界を越える場合）
references/MERGE_FOR_CONTEXT.mdJSON変換後にバイナリが失われ、再度結合する必要があるとき
references/CDN_REQUIREMENT.mdチャット画面など、URLで参照する画像が必要な場所に画像を表示するとき

アンチパターン

アンチパターン問題点対処法
$jsonからファイルの内容を読み取ろうとするバイナリは$jsonに含まれていません$binaryを使用します
バイナリを直接返すエージェントツールを作るツールの出力はJSONのみのため、バイナリは保持されませんストレージにアップロードし、JSONでキーまたはURLを返します（AGENT_TOOL_BINARY.mdを参照）
fromAiを介してアップロード済みのチャットファイルをツールに渡そうとするfromAiではバイナリが渡されないため、ツールは何も受け取りませんアップロードを事前にストレージに配置し、システムプロンプトにキーを挿入して、ツールがキーでダウンロードするようにします
passthroughBinaryImages: trueを設定すれば、ツールがファイルを参照できると思い込むこのフラグが影響するのはLLMに見える内容だけであり、ツールが受け取る内容には影響しませんツールには引き続き、アップロードしてキーを渡すパターンが必要です
JSON変換後にバイナリを失う変換後の出力アイテムにバイナリが含まれませんMergeを使用して、JSON出力とバイナリストリームを結合します
画像をn8nのバイナリに保存し、チャット画面に表示されることを期待するチャット画面で必要なのはURLからアクセスできる画像（またはプラットフォームネイティブのファイルアップロード）であり、生の$binaryではありませんCDNにアップロードし、URLを埋め込むか、プラットフォームのファイルAPIを使用します
Codeノードにバイナリのbase64をハードコードするワークフローJSONが大きくなり、処理が遅く、情報漏えいの原因になります$binaryでバイナリを適切に参照するか、ストレージにアップロードしてURLで参照します

コメント

Markdown 対応