نود FTP در N8N

نود FTP در N8N یکی از نودهای کاربردی برای کار با فایل‌ها روی سرورهای FTP و SFTP است. با این نود می‌توانید فایل‌ها را از سرور دانلود کنید، فایل جدید آپلود کنید، لیست فایل‌های یک مسیر را بگیرید، فایل‌ها را حذف کنید یا نام آن‌ها را تغییر دهید. اگر در پروژه‌های خود با فایل‌های خروجی سیستم‌های حسابداری، گزارش‌های روزانه، بکاپ‌ها، فایل‌های CSV، XML یا تصاویر سر و کار دارید، نود FTP می‌تواند یکی از اجزای اصلی ورکفلوهای اتوماسیون شما باشد.

معرفی نود در N8N

نود FTP در N8N برای اتصال به سرورهای فایل از طریق پروتکل‌های FTP و SFTP استفاده می‌شود. این نود به شما اجازه می‌دهد بدون نیاز به کدنویسی مستقیم، عملیات رایج مدیریت فایل را در یک ورکفلو انجام دهید.

نام نود: FTP
نوع نود: Integration / Action
کاربرد اصلی: مدیریت فایل روی سرورهای FTP و SFTP
مناسب برای: دانلود گزارش‌ها، آپلود فایل، انتقال فایل بین سرویس‌ها، پردازش فایل‌های CSV و XML، ساخت فرایندهای بکاپ و آرشیو

این نود Trigger نیست؛ یعنی به‌تنهایی منتظر تغییرات روی سرور FTP نمی‌ماند. معمولاً برای اجرای خودکار، آن را با نودهایی مثل Cron، Schedule Trigger، Webhook، Manual Trigger یا سایر نودهای پردازشی ترکیب می‌کنند.

موارد استفاده

دانلود خودکار گزارش‌های روزانه

فرض کنید یک نرم‌افزار فروشگاهی هر شب یک فایل CSV از سفارش‌ها را روی سرور FTP قرار می‌دهد. با ترکیب نود Schedule Trigger و FTP می‌توانید هر روز در ساعت مشخص فایل را دانلود کرده و سپس با نود Spreadsheet File یا Code آن را پردازش کنید.

Schedule Trigger: اجرای روزانه در ساعت مشخص
FTP: دانلود فایل CSV از مسیر مشخص
Spreadsheet File: تبدیل فایل CSV به JSON
Google Sheets یا Database: ذخیره داده‌ها

آپلود فایل خروجی به سرور مشتری

در بسیاری از پروژه‌ها لازم است فایل‌هایی مثل گزارش فروش، فاکتور، خروجی اکسل یا فایل XML بعد از تولید، روی FTP مشتری قرار بگیرد. نود FTP می‌تواند فایل باینری تولیدشده در مراحل قبلی ورکفلو را دریافت و روی مسیر موردنظر آپلود کند.

HTTP Request: دریافت داده از API
Code: ساختاردهی داده‌ها
Spreadsheet File: تولید فایل Excel یا CSV
FTP: آپلود فایل روی سرور مقصد

آرشیو فایل‌های قدیمی

می‌توانید فایل‌های موجود در یک پوشه FTP را لیست کنید، فایل‌هایی که تاریخ قدیمی‌تری دارند شناسایی کنید و سپس آن‌ها را به مسیر دیگری منتقل یا حذف کنید. برای این کار معمولاً از عملیات List، سپس IF و در نهایت Delete یا Rename استفاده می‌شود.

FTP List: دریافت لیست فایل‌ها
IF: بررسی تاریخ یا نام فایل
FTP Rename: انتقال فایل به پوشه آرشیو
FTP Delete: حذف فایل‌های غیرضروری

پردازش فایل‌های ورودی از یک سیستم خارجی

بسیاری از نرم‌افزارهای قدیمی یا سازمانی هنوز برای تبادل داده از FTP استفاده می‌کنند. مثلاً یک سیستم انبارداری ممکن است فایل XML موجودی کالا را روی FTP قرار دهد. N8N می‌تواند این فایل را دانلود کند، داده‌های آن را استخراج کند و به یک API مدرن ارسال کند.

FTP Download: دانلود فایل XML
XML: تبدیل XML به JSON
Set یا Code: آماده‌سازی داده
HTTP Request: ارسال اطلاعات به API

پارامترها و تنظیمات

تنظیمات اتصال و Credentials

قبل از استفاده از نود FTP باید اطلاعات اتصال به سرور را در بخش Credentials وارد کنید. این اطلاعات معمولاً از مدیر سرور یا سرویس‌دهنده هاست دریافت می‌شود.

Host / نوع داده: String / کاربرد: آدرس سرور FTP یا SFTP را مشخص می‌کند. مثال: ftp.example.com یا 192.168.1.20
Port / نوع داده: Number / کاربرد: پورت اتصال به سرور. برای FTP معمولاً 21 و برای SFTP معمولاً 22 است. مثال: 21
Username / نوع داده: String / کاربرد: نام کاربری حساب FTP یا SFTP. مثال: report_user
Password / نوع داده: String / کاربرد: رمز عبور حساب کاربری. مثال: رمز عبور ارائه‌شده توسط سرور
Protocol / نوع داده: Options / کاربرد: تعیین نوع اتصال؛ FTP یا SFTP. مثال: SFTP برای اتصال امن‌تر
Secure / نوع داده: Boolean / کاربرد: در برخی تنظیمات FTP برای استفاده از FTPS یا اتصال امن فعال می‌شود. مثال: true برای سرورهایی که اتصال امن نیاز دارند
Private Key / نوع داده: String / کاربرد: در اتصال SFTP ممکن است به‌جای رمز عبور از کلید خصوصی استفاده شود. مثال: محتوای کلید خصوصی SSH
Passphrase / نوع داده: String / کاربرد: اگر Private Key رمزنگاری شده باشد، عبارت عبور کلید در این بخش وارد می‌شود. مثال: passphrase مربوط به SSH key

نکته مهم: برای امنیت بیشتر، بهتر است از SFTP استفاده شود، چون FTP معمولی اطلاعات را به‌صورت رمزنگاری‌نشده منتقل می‌کند.

پارامتر Operation

پارامتر Operation مشخص می‌کند نود FTP چه کاری انجام دهد. عملیات‌های رایج در این نود شامل دانلود، آپلود، لیست کردن، حذف و تغییر نام فایل است.

Download / نوع داده: Option / کاربرد: دانلود یک فایل از سرور FTP یا SFTP. مثال: دانلود فایل /reports/orders.csv
Upload / نوع داده: Option / کاربرد: آپلود یک فایل باینری به سرور. مثال: آپلود فایل خروجی workflow روی مسیر /exports/report.csv
List / نوع داده: Option / کاربرد: دریافت لیست فایل‌ها و پوشه‌های یک مسیر. مثال: لیست فایل‌های مسیر /incoming
Delete / نوع داده: Option / کاربرد: حذف فایل از سرور. مثال: حذف فایل /temp/old-file.csv
Rename / نوع داده: Option / کاربرد: تغییر نام فایل یا انتقال فایل به مسیر جدید. مثال: تغییر مسیر /incoming/a.csv به /archive/a.csv

پارامتر Path

نام پارامتر: Path
نوع داده: String
کاربرد: مسیر فایل یا پوشه روی سرور FTP/SFTP را مشخص می‌کند.
مثال عملی: /reports/daily-sales.csv

در عملیات Download، Delete و Rename معمولاً Path مسیر فایل است. در عملیات List، Path مسیر پوشه است. در عملیات Upload، Path معمولاً مسیر نهایی فایلی است که قرار است روی سرور ذخیره شود.

پارامتر Binary Property

نام پارامتر: Binary Property
نوع داده: String
کاربرد: مشخص می‌کند فایل دانلودشده در کدام فیلد باینری ذخیره شود یا فایل آپلودی از کدام فیلد باینری خوانده شود.
مثال عملی: data

در N8N فایل‌ها معمولاً در بخش binary آیتم ذخیره می‌شوند. نام رایج برای این فیلد data است، اما می‌توانید نام‌های دیگری مثل file، attachment یا document نیز استفاده کنید؛ به شرطی که در مراحل بعدی یا قبلی ورکفلو همان نام را به‌درستی وارد کنید.

پارامتر Remote Path

نام پارامتر: Remote Path
نوع داده: String
کاربرد: مسیر مقصد روی سرور برای آپلود فایل یا مسیر فایل روی سرور برای دانلود و مدیریت فایل.
مثال عملی: /uploads/invoice-1001.pdf

در برخی نسخه‌ها یا حالت‌های تنظیمات، این پارامتر ممکن است با عنوان Path نمایش داده شود. هدف آن مشخص کردن مسیر فایل یا پوشه در سمت سرور است.

پارامتر New Path

نام پارامتر: New Path
نوع داده: String
کاربرد: در عملیات Rename استفاده می‌شود و مسیر یا نام جدید فایل را مشخص می‌کند.
مثال عملی: /archive/orders-2024-01-01.csv

با استفاده از Rename می‌توانید فقط نام فایل را تغییر دهید یا فایل را از یک پوشه به پوشه دیگر منتقل کنید. برای انتقال فایل، مسیر کامل مقصد را وارد کنید.

پارامتر Recursive

نام پارامتر: Recursive
نوع داده: Boolean
کاربرد: در برخی عملیات لیست کردن یا حذف، مشخص می‌کند آیا زیرپوشه‌ها نیز بررسی شوند یا خیر.
مثال عملی: true برای بررسی فایل‌های داخل پوشه‌های تو در تو

اگر پوشه‌ای تعداد زیادی فایل یا زیرپوشه داشته باشد، فعال کردن Recursive ممکن است زمان اجرای ورکفلو را افزایش دهد.

پارامتر File Name

نام پارامتر: File Name
نوع داده: String
کاربرد: در برخی سناریوهای آپلود برای تعیین نام فایل مقصد استفاده می‌شود.
مثال عملی: {{$json.customerId}}-invoice.pdf

استفاده از Expression در نام فایل بسیار کاربردی است. مثلاً می‌توانید نام فایل را بر اساس تاریخ، شناسه مشتری، شماره سفارش یا نوع گزارش بسازید.

پارامتر Options

بسته به نوع عملیات و نسخه N8N، ممکن است گزینه‌های تکمیلی در بخش Options وجود داشته باشد. این گزینه‌ها برای کنترل دقیق‌تر رفتار نود استفاده می‌شوند.

Continue On Fail / نوع داده: Boolean / کاربرد: اگر فعال باشد، در صورت خطا ورکفلو متوقف نمی‌شود و خطا در خروجی نود ثبت می‌شود. مثال: زمانی که حذف فایل اختیاری است.
Timeout / نوع داده: Number / کاربرد: مدت‌زمان انتظار برای پاسخ سرور. مثال: 60000 میلی‌ثانیه برای فایل‌های حجیم‌تر
Encoding / نوع داده: String / کاربرد: در برخی پردازش‌ها برای تعیین نوع کدگذاری فایل متنی استفاده می‌شود. مثال: utf8

نکات مهم هنگام پیکربندی

مسیرها را با دقت وارد کنید. در بیشتر سرورهای لینوکسی مسیرها به حروف بزرگ و کوچک حساس هستند.
اگر مسیر شامل فاصله یا کاراکتر خاص است، بهتر است ابتدا با یک مسیر ساده تست شود.
برای دانلود فایل، مسیر باید به فایل ختم شود، نه فقط پوشه.
برای عملیات List، مسیر معمولاً باید مسیر پوشه باشد.
در آپلود فایل، مطمئن شوید ورودی نود دارای داده باینری است.
اگر فایل حجیم است، محدودیت حافظه و زمان اجرای N8N را در نظر بگیرید.
در محیط‌های Production بهتر است از SFTP یا FTPS به‌جای FTP ساده استفاده شود.

ورودی‌ها و خروجی‌ها

ورودی نود FTP

ورودی نود FTP بسته به عملیات انتخاب‌شده متفاوت است. برای برخی عملیات مثل List یا Download ممکن است فقط مقدارهای متنی مثل مسیر فایل کافی باشد. اما برای Upload، ورودی باید شامل فایل باینری باشد.

نمونه ورودی برای دانلود فایل:

{  "filePath": "/reports/daily-sales.csv",  "date": "2024-05-01"}

در این حالت می‌توانید در فیلد Path از Expression زیر استفاده کنید:

{{$json.filePath}}

نمونه ورودی برای آپلود فایل معمولاً شامل بخش binary است:

{  "json": {    "fileName": "report.csv",    "remotePath": "/exports/report.csv"  },  "binary": {    "data": {      "fileName": "report.csv",      "mimeType": "text/csv",      "fileExtension": "csv"    }  }}

خروجی عملیات List

وقتی عملیات List اجرا می‌شود، خروجی معمولاً شامل اطلاعات فایل‌ها و پوشه‌های موجود در مسیر موردنظر است.

[  {    "name": "orders.csv",    "type": "file",    "path": "/incoming/orders.csv",    "size": 24580,    "modifyTime": "2024-05-01T08:30:00.000Z"  },  {    "name": "archive",    "type": "directory",    "path": "/incoming/archive"  }]

name: نام فایل یا پوشه
type: نوع آیتم، مثل file یا directory
path: مسیر کامل یا نسبی آیتم
size: اندازه فایل بر حسب بایت
modifyTime: زمان آخرین تغییر فایل، در صورت پشتیبانی سرور

خروجی عملیات Download

در عملیات Download، فایل دانلودشده در بخش binary خروجی ذخیره می‌شود. اگر Binary Property را برابر data قرار داده باشید، فایل در مسیر binary.data قرار می‌گیرد.

{  "json": {    "filePath": "/reports/daily-sales.csv"  },  "binary": {    "data": {      "fileName": "daily-sales.csv",      "mimeType": "text/csv",      "fileExtension": "csv"    }  }}

بعد از دانلود فایل می‌توانید آن را به نودهایی مثل Spreadsheet File، Read Binary File، Move Binary Data، HTTP Request، Email یا Google Drive منتقل کنید.

خروجی عملیات Upload

در عملیات Upload، خروجی معمولاً شامل وضعیت انجام عملیات و اطلاعات آیتم ورودی است. اگر آپلود موفق باشد، نود بدون خطا اجرا می‌شود و آیتم به مرحله بعد منتقل می‌شود.

{  "success": true,  "path": "/exports/report.csv"}

خروجی عملیات Delete

در عملیات Delete، اگر فایل با موفقیت حذف شود، خروجی می‌تواند شامل اطلاعات مسیر حذف‌شده یا آیتم ورودی باشد. در صورتی که فایل وجود نداشته باشد، بسته به تنظیمات، ممکن است خطا ایجاد شود.

{  "success": true,  "deletedPath": "/temp/old-report.csv"}

خروجی عملیات Rename

در عملیات Rename، خروجی معمولاً مسیر قبلی و مسیر جدید فایل را نشان می‌دهد یا آیتم ورودی را به مرحله بعد منتقل می‌کند.

{  "success": true,  "oldPath": "/incoming/orders.csv",  "newPath": "/archive/orders.csv"}

نکات پیشرفته و ترفندها

استفاده از Expression برای مسیرهای پویا

یکی از بهترین روش‌ها برای استفاده حرفه‌ای از نود FTP، ساخت مسیر فایل به‌صورت پویا با Expression است. مثلاً برای دانلود فایل روز جاری می‌توانید از تاریخ در نام فایل استفاده کنید.

/reports/sales-{{$now.format("yyyy-MM-dd")}}.csv

این روش برای گزارش‌های روزانه، فایل‌های بکاپ، خروجی‌های ماهانه و فایل‌های مشتریان مختلف بسیار مفید است.

پردازش چند فایل با Split In Batches

اگر با عملیات List چندین فایل دریافت کرده‌اید، می‌توانید فایل‌ها را یکی‌یکی پردازش کنید. این کار مخصوصاً برای فایل‌های حجیم یا تعداد زیاد فایل‌ها باعث کنترل بهتر اجرای ورکفلو می‌شود.

FTP List: گرفتن لیست فایل‌ها
IF: فیلتر فایل‌های موردنظر، مثلاً فقط فایل‌های csv
Split In Batches: پردازش مرحله‌ای فایل‌ها
FTP Download: دانلود هر فایل
FTP Rename: انتقال فایل پردازش‌شده به پوشه archive

فیلتر کردن فایل‌ها بر اساس پسوند

نود FTP به‌تنهایی برای فیلتر پیچیده فایل‌ها طراحی نشده است، اما می‌توانید بعد از List از نود IF یا Code استفاده کنید. برای مثال، فقط فایل‌هایی که پسوند csv دارند پردازش شوند.

{{$json.name.endsWith(".csv")}}

جلوگیری از پردازش دوباره فایل‌ها

یکی از مشکلات رایج در اتوماسیون FTP این است که یک فایل چندین بار پردازش شود. برای جلوگیری از این موضوع چند روش وجود دارد:

بعد از پردازش موفق، فایل را با Rename به پوشه archive منتقل کنید.
نام فایل پردازش‌شده را در دیتابیس یا Google Sheets ذخیره کنید.
از یک الگوی نام‌گذاری شامل تاریخ و شناسه یکتا استفاده کنید.
فایل‌های پردازش‌شده را با پسوند متفاوت ذخیره کنید؛ مثلاً orders.csv.processed

انتقال فایل بین دو سرور FTP

برای انتقال فایل از یک سرور FTP به سرور دیگر، می‌توانید از دو نود FTP استفاده کنید. نود اول فایل را دانلود می‌کند و نود دوم همان فایل باینری را روی سرور مقصد آپلود می‌کند.

FTP Source: دانلود فایل از سرور اول
FTP Destination: آپلود فایل روی سرور دوم

در این سناریو باید Binary Property در هر دو نود یکسان باشد؛ مثلاً data.

ترکیب با Email برای ارسال فایل‌های FTP

اگر فایلی روی FTP قرار دارد و باید برای افراد ارسال شود، می‌توانید ابتدا با FTP آن را دانلود کنید و سپس با نود Email Send همان فایل را به‌عنوان پیوست ارسال کنید.

FTP Download: دانلود فایل
Email Send: ارسال فایل به‌عنوان Attachment

ترکیب با Google Drive یا S3

برای تهیه نسخه پشتیبان از فایل‌های FTP می‌توانید فایل‌ها را دانلود کرده و در Google Drive، Amazon S3، Dropbox یا سرویس‌های ذخیره‌سازی دیگر آپلود کنید.

Schedule Trigger: اجرای زمان‌بندی‌شده
FTP List: دریافت لیست فایل‌ها
FTP Download: دانلود فایل‌ها
Google Drive یا S3: ذخیره نسخه پشتیبان

محدودیت‌ها و خطاها

محدودیت‌های نود FTP

نود FTP به‌صورت مستقیم Trigger نیست و تغییرات سرور را لحظه‌ای مانیتور نمی‌کند.
برای پردازش فایل‌های بسیار حجیم، باید محدودیت حافظه و زمان اجرای N8N بررسی شود.
برخی سرورهای FTP اطلاعات کامل مثل modifyTime یا size را برنمی‌گردانند.
FTP معمولی امن نیست و اطلاعات را رمزنگاری نمی‌کند.
در برخی سرورها، دسترسی به مسیرهای خاص محدود است و نیاز به مجوز دارد.
اگر اتصال Passive یا Active در سطح سرور محدود شده باشد، ممکن است اتصال FTP با مشکل مواجه شود.
در آپلود فایل، نود باید ورودی باینری معتبر داشته باشد؛ داده JSON به‌تنهایی برای آپلود فایل کافی نیست.

خطای Authentication Failed

این خطا زمانی رخ می‌دهد که نام کاربری، رمز عبور، کلید خصوصی یا نوع احراز هویت اشتباه باشد.

Username و Password را بررسی کنید.
اگر از SFTP با Private Key استفاده می‌کنید، فرمت کلید خصوصی را بررسی کنید.
اگر کلید دارای Passphrase است، مقدار آن را وارد کنید.
از فعال بودن حساب FTP/SFTP در سرور مطمئن شوید.

خطای Connection Timeout

این خطا معمولاً به دلیل عدم دسترسی به سرور، بسته بودن پورت، فایروال یا کندی شبکه رخ می‌دهد.

Host و Port را بررسی کنید.
از سرور N8N به مقصد FTP تست شبکه بگیرید.
فایروال سرور FTP و سرور N8N را بررسی کنید.
در صورت وجود تنظیم Timeout، مقدار آن را افزایش دهید.

خطای No Such File

این خطا یعنی مسیر فایل یا پوشه اشتباه است یا فایل موردنظر وجود ندارد.

مسیر فایل را با عملیات List بررسی کنید.
به حساس بودن حروف بزرگ و کوچک توجه کنید.
اگر مسیر با Expression ساخته می‌شود، خروجی نهایی Expression را بررسی کنید.
از وجود فایل در زمان اجرای ورکفلو مطمئن شوید.

خطای Permission Denied

این خطا زمانی رخ می‌دهد که حساب FTP/SFTP مجوز خواندن، نوشتن، حذف یا تغییر نام فایل را ندارد.

سطح دسترسی کاربر را روی سرور بررسی کنید.
برای Upload، مجوز نوشتن روی پوشه مقصد لازم است.
برای Delete، مجوز حذف فایل لازم است.
برای Rename یا انتقال فایل، مجوز تغییر نام و نوشتن در مسیر مقصد لازم است.

خطای Binary Data Not Found

این خطا معمولاً در عملیات Upload رخ می‌دهد و یعنی نود FTP نتوانسته فایل باینری را در ورودی پیدا کند.

نام Binary Property را بررسی کنید؛ مثلاً data.
مطمئن شوید نود قبلی واقعاً فایل باینری تولید کرده است.
اگر از نود Code استفاده کرده‌اید، بخش binary آیتم را حذف نکرده باشید.
در نودهای تبدیل فایل، خروجی باینری را بررسی کنید.

خطای File Already Exists

در برخی سرورها اگر فایلی با همان نام در مسیر مقصد وجود داشته باشد، عملیات آپلود یا تغییر نام با خطا مواجه می‌شود.

نام فایل را یکتا کنید؛ مثلاً با افزودن تاریخ و ساعت.
قبل از آپلود، با عملیات List بررسی کنید فایل وجود دارد یا نه.
در صورت نیاز، فایل قبلی را حذف یا به مسیر آرشیو منتقل کنید.

ایده ها

سیستم دریافت خودکار سفارش‌ها: دانلود فایل‌های CSV سفارش از FTP، تبدیل به JSON و ثبت سفارش‌ها در CRM یا دیتابیس.
بکاپ روزانه فایل‌های مهم: گرفتن لیست فایل‌های FTP، دانلود آن‌ها و ذخیره در Google Drive یا Amazon S3.
اتوماسیون گزارش مالی: تولید فایل Excel از داده‌های فروش و آپلود خودکار آن روی FTP واحد مالی.
پردازش فایل‌های XML تأمین‌کنندگان: دانلود XML موجودی کالا از FTP، تبدیل به JSON و به‌روزرسانی قیمت و موجودی در فروشگاه اینترنتی.
سیستم آرشیو هوشمند: شناسایی فایل‌های قدیمی روی FTP و انتقال آن‌ها به پوشه archive بر اساس تاریخ یا الگوی نام فایل.