Lavorare con immagini, PDF, ZIP e allegati è diventato quotidiano anche per chi fa marketing. Ecco perché conoscere i dati binari n8n è fondamentale: ti permette di ricevere file via Webhook, trasformarli, comprimerli, estrarre informazioni e inviarli dove servono (Drive, S3, FTP, email) in modo affidabile e scalabile. In questa guida pratica vedrai come funziona la struttura binaria degli item, come usare i nodi chiave (Convert to File, Extract from File, Read/Write Files from Disk), come scaricare e caricare file con HTTP Request e Webhook, e come manipolare buffer/base64 nel Code node. Inoltre, configurerai lo storage dei binari (memoria vs filesystem vs S3) tramite variabili d’ambiente, con best practice su performance, sicurezza e scaling. Alla fine avrai una checklist operativa, ricette end‑to‑end e un troubleshooting rapido per sbloccare gli errori più comuni, così da integrare i file binari su n8n nei tuoi flussi senza stress.
Concetti base e struttura degli item binari
Per ogni passaggio del workflow, n8n tratta i dati come una lista di “item”. Ogni item ha due sezioni:
- json: i dati strutturati (campi, numeri, stringhe).
- binary: i file binari su n8n associati a quell’item.
Struttura degli item binari: proprietà
- data: contenuto in base64 (o riferimento esterno, a seconda della modalità di storage).
- mimeType: tipo MIME (es. image/png, application/pdf).
- fileName: nome del file (es. report.pdf).
- fileExtension: estensione (es. pdf, png).
- fileSize: dimensione in byte (se disponibile).
Differenza tra JSON e binario: quando convertire e perché
- Resta in JSON quando ti servono campi leggibili e manipolazioni testuali.
- Passa al binario quando lavori con file veri e propri, devi inviarli come allegati o salvarli su storage. Usa il nodo Convert to File di n8n per creare un file a partire da testo/base64, ed Extract from File n8n per ZIP/PDF quando vuoi estrarre contenuti e riconvertirli in JSON.
Referenziare i binari nelle espressioni
- Nel nodo consumatore indica la “binary property” che contiene il file (es. file). Assicurati che il nome sia coerente tra i nodi.
- Se rinomini la proprietà (es. da data a file), aggiorna tutti i nodi a valle che usano quel file.
Passaggio tra nodi e debugging
- Errore tipico: “binary property not found”. Controlla il nome della proprietà, ispeziona l’item in esecuzione e verifica che il nodo precedente produca davvero item.binary.
.
Lettura, scrittura e conversione: i nodi core per i file
Read/Write Files from Disk
- Per installazioni aggiornate, usa Read/Write Files from Disk per leggere/scrivere dal filesystem. È l’evoluzione dei nodi Read Binary File/Write Binary File.
- Tipico uso: leggere un PDF da una cartella condivisa per poi inviarlo via email; oppure salvare su disco file generati a runtime.
Convert to File | Extract from File
- Convert to File: prende in input testo/Base64 e genera un file binario con nome ed estensione corretti. Esempio: trasformare il contenuto HTML in un .html o un CSV stringa in .csv.
- Extract from File: prende in input un file binario e lo converte in JSON, o estrae file contenuti (per ZIP/PDF quando previsto), così puoi analizzarne il contenuto con nodi HTML/XML o trasformarlo.
Esempio Convert to File (config essenziale)
{
"name": "Convert to File",
"type": "n8n-nodes-base.convertToFile",
"typeVersion": 1,
"parameters": {
"operation": "textToFile",
"textInputField": "={{$json.report_markdown}}",
"outputFieldName": "file",
"fileName": "monthly-report.md",
"mimeType": "text/markdown"
}
}
Esempio Extract from File (estrazione testo da PDF/ZIP, flusso generico)
{
"name": "Extract from File",
"type": "n8n-nodes-base.extractFromFile",
"typeVersion": 1,
"parameters": {
"binaryPropertyName": "file",
"operation": "auto",
"outputFieldName": "extracted"
}
}
Lettura/Scrittura e trigger
- Local File Trigger e monitoraggio directory: utile per reagire a nuovi file in arrivo.
- FTP/SFTP per trasferimento file in n8n: scarica/carica file su server remoti come parte del flusso.
HTTP, Webhook ed Email: integrazione file in entrata/uscita
HTTP Request con payload binario in n8n (download)
- Imposta “Response format: File” e “Binary Property” (es. file) per scaricare immagini, PDF, audio.
Esempio:
{
"name": "Download File",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 1,
"parameters": {
"url": "https://example.com/files/{{$json.id}}.pdf",
"method": "GET",
"responseFormat": "file",
"binaryPropertyName": "file"
}
}
HTTP Request (upload)
- Usa form-data e imposta la proprietà binaria come file da caricare. Indica la “Binary Property” e il campo form.
{
"name": "Upload File",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 1,
"parameters": {
"url": "https://api.example.com/upload",
"method": "POST",
"sendBody": true,
"contentType": "multipart-form-data",
"bodyParametersUi": {
"parameter": [
{
"name": "file",
"value": "={{$binary.file}}",
"type": "formBinary"
}
]
}
}
}
Upload file con Webhook n8n
- Il Webhook riceve multipart/form-data e inserisce gli allegati in item.binary con il nome del campo usato nel form (es. upload). A valle puoi salvare o trasformare questi file.
Gestione allegati email in n8n
- I nodi email (es. Gmail/IMAP) possono esporre gli allegati in binary. Filtra i messaggi, estrai l’allegato e inoltralo (Drive/S3/FTP) o processalo (Extract from File).
Manipolazioni con Code: base64, buffer e metadati file
Il Code node è perfetto per operazioni su buffer/base64 e per impostare mimeType e fileName.
Creare un file binario da stringa
// Crea file .txt a partire da una stringa
const content = ($json.text || 'Hello n8n!');
const data = Buffer.from(content, 'utf8').toString('base64');
return [
{
json: $json,
binary: {
file: {
data,
mimeType: 'text/plain',
fileName: 'message.txt',
fileExtension: 'txt'
}
}
}
];
Leggere base64 da un binario e salvarlo in JSON
const b = $binary.file;
const base64 = b.data; // attenzione: può essere un riferimento se usi storage esterno
return [{ json: { ...$json, file_base64: base64, mimeType: b.mimeType, fileName: b.fileName } }];
Rinominare la binary property
const b = $binary.file;
return [{ json: $json, binary: { attachment: b } }];
Impostare mimeType e nome file in n8n
- Quando generi il binario (Convert to File/Code), valorizza sempre mimeType e fileName: semplifica invii HTTP/email e salvataggi su storage.
Storage dei binari: memoria vs filesystem vs S3 e variabili d’ambiente
Modalità disponibili e trade‑off
- Memoria (default): semplice, ma non adatta a file grandi e a cluster.
- Filesystem: salva sotto una directory locale; ottimo per file medi e per ridurre RAM. Richiede volumi condivisi tra worker in cluster.
- Storage esterno (S3/compatibile): ideale per carichi/cluster; centralizza e scala, con costi e latenza da valutare.
Variabili d’ambiente per lo storage dei file in n8n
- N8NAVAILABLEBINARYDATAMODES: elenco delle modalità disponibili (es. filesystem).
- N8NBINARYDATASTORAGEPATH: percorso dove n8n salva i file (default: N8NUSERFOLDER/binaryData).
- N8NDEFAULTBINARYDATAMODE: default mantiene i binari in memoria (“default”). Imposta “filesystem” per file su disco.
- NODES_EXCLUDE: per escludere nodi che leggono/scrivono binari (hardening).
Esempio (bash)
export N8N_AVAILABLE_BINARY_DATA_MODES=filesystem
export N8N_BINARY_DATA_STORAGE_PATH=/home/node/.n8n/binaryData
export N8N_DEFAULT_BINARY_DATA_MODE=filesystem
Cambio modalità e pruning
- La pulizia (pruning) agisce sulla modalità attiva. Se hai salvato in S3 e poi passi a filesystem, la pulizia riguarderà solo i file su filesystem. Pianifica eventuali migrazioni/bonifiche.
Sicurezza
- Usa varianti _FILE per gestire segreti via file/Secrets.
- Limita permessi sulla cartella binaria; definisci retention e job di pruning.
Performance, costi e scaling: linee guida pratiche
Limiti e performance
- Evita file enormi in memoria; preferisci filesystem o storage esterno.
- Comprimi prima di inviare/archiviare (compressione e archiviazione ZIP in n8n) per ridurre banda e storage.
Scaling e HA
- Con filesystem: monta volumi condivisi tra worker e nodi main/worker in queue mode per coerenza dei riferimenti.
- Con S3: semplifica il cluster eliminando il vincolo dei volumi condivisi; considera latenza e costi.
Ridurre peso e costi
- Cancella file temporanei dopo l’uso (pruning e pulizia dei file temporanei in n8n).
- Scegli formati efficienti (CSV per tabelle, WebP per immagini quando possibile).
Privacy e governance
- Se i file contengono PII, definisci retention policy e access control. Evita di replicare file sensibili in troppi step.
Ricette end‑to‑end
Ricevere upload via Webhook, validarlo e salvarlo
1) Webhook (POST multipart/form-data): riceve il file in binary.upload.
2) If: controlla mimeType/estensione consentiti.
3) Write Files from Disk: salva su path organizzati per data/cliente.
4) HTTP Request (facoltativo): invia metadati a un CRM/DB.
Scaricare immagine, creare ZIP e inviare via Email
1) HTTP Request (Response format: File, binaryPropertyName=file).
2) Compression: aggiungi file a un archivio .zip (binary property zip).
3) Email: allega il binario zip e invia al team.
Estrarre contenuti da ZIP e produrre CSV
1) Extract from File (binaryPropertyName=file): ottieni lista di file interni in JSON.
2) Code: parse e normalizza dati.
3) Convert to File: genera CSV (textToFile) in binary.csv.
4) HTTP Response/Webhook Reply: restituisci il CSV scaricabile.
Troubleshooting rapido
- “binary property not found”: verifica il nome della binary property nel nodo consumatore; controlla che il nodo precedente la produca davvero (ispeziona l’item).
- mimeType mancante/errato: imposta esplicitamente mimeType (Convert to File/Code) per evitare problemi con upload/email.
- Percorsi errati su disco: conferma N8NBINARYDATASTORAGEPATH e permessi; in cluster usa volumi condivisi.
- Time‑out di rete in upload/download: riduci dimensioni (compressione), aumenta time‑out del nodo HTTP, usa retry/backoff.
- File enormi in memoria: passa a N8NDEFAULTBINARYDATAMODE=filesystem o adotta storage esterno.
Quick Takeaways
- Pianifica la binary property e mantienila coerente tra i nodi per evitare errori di referenza.
- Usa Convert to File ed Extract from File per passare tra JSON e binario in modo sicuro e ripetibile.
- Per download/upload imposta HTTP Request su “Response format: File” e usa multipart/form-data per gli upload.
- Gestisci storage con N8NDEFAULTBINARYDATAMODE e N8NBINARYDATASTORAGEPATH; filesystem o S3 per produzione/scaling.
- Riduci costi e rischi: comprimi, cancella temporanei, applica retention e permessi stretti.
- In cluster, condividi i volumi (filesystem) o adotta storage esterno per evitare inconsistenze.
Conclusione
Portare file e allegati nei tuoi workflow amplia enormemente ciò che puoi automatizzare: dal ricevere asset via form alla generazione di report, fino a compressione, trasformazione e invio multi‑canale. Conoscere i dati binari n8n significa padroneggiare la struttura json/binary degli item, i nodi chiave per leggere/scrivere/convertire e le integrazioni HTTP/Webhook/Email. La configurazione corretta dello storage (memoria vs filesystem vs S3) tramite variabili d’ambiente rende i flussi più stabili, scalabili e sicuri, mentre le buone pratiche su performance, pruning e governance evitano costi e incidenti. Il modo migliore per iniziare? Scegli un caso d’uso concreto (upload via Webhook o download + ZIP + email), imposta la binary property, testa il flusso e passa gradualmente a storage persistente in produzione. In poco tempo porterai più file “nel circuito” delle tue automazioni, liberando tempo a te e al tuo team per attività a maggior valore.
FAQ
1) Come rappresento un file in un item n8n?
Un file vive in item.binary.
2) Come passo da testo a file e viceversa?
Usa il nodo Convert to File di n8n per generare un file (es. CSV/MD) da testo o base64; usa Extract from File n8n per ZIP/PDF quando vuoi estrarre contenuti e convertirli in JSON.
3) Come scaricare e caricare file via HTTP?
Per scaricare imposta HTTP Request con “Response format: File” e scegli la “Binary Property”. Per caricare usa multipart/form-data specificando la proprietà binaria come file.
4) Come configuro lo storage per grandi file?
Imposta N8NDEFAULTBINARYDATAMODE=filesystem e definisci N8NBINARYDATASTORAGEPATH. Valuta storage esterno (S3/compatibile) per cluster/HA. Ricorda che la pulizia (pruning) agisce sulla modalità attiva.
5) Come evito l’errore “binary property not found”?
Assicurati che il nodo produttore crei davvero item.binary.
Ci dai una mano?
Quale flusso creerai per primo: upload via Webhook con salvataggio su storage o estrazione ZIP→CSV con invio email? Condividilo e invita il tuo team: costruiamo insieme automazioni che trattano i file in modo semplice e sicuro!
Scopri la consulenza →