mcpField
N
n8n-binary-and-data

n8n-binary-and-data

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

n8n-binary-and-data について

n8n-binary-and-dataは、n8nワークフローでのバイナリデータの扱いを説明するガイドです。`$binary`と`$json`の違い、エージェントツールのJSON境界、Mergeによるデータ保持、チャットで画像を表示する要件を扱います。

主な機能

  1. 01`$binary`と`$json`の区別
  2. 02Mergeによるバイナリデータの保持
  3. 03ストレージキーやURLでファイルを渡す方法
  4. 04エージェントツールのJSON限定の境界
  5. 05チャットでの画像URL要件

活用シーン

  1. 01ワークフロー内でファイルを読み取り・受け渡し
  2. 02アップロードファイルをエージェントツールで処理
  3. 03ツールが生成したファイルをエージェントに返す
  4. 04生成画像をチャットメッセージに表示

インストール

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

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

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

同梱ファイル

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

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

詳細

n8n Binary and Data

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

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

必ず守ること

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

基本的な推奨事項

  • Merge ノードを使うと、バイナリをコンテキスト内に保持できます。 サイド計算でバイナリが取り除かれた場合は、再取得するのではなく、マージして戻してください。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 を参照してください。

エージェントツールの取り扱い

エージェントツール（LangChain 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]
                      └─────────────────────────────────────┘

Merge でストリームを結合すると、バイナリが保持されます。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 スキルを参照してください。これは独立した機能で、固有の注意点があります（デフォルトの列、外部キーがないこと、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 対応