راهنمای جامع Loop & Merge در n8n (۱۴۰۴): پردازش دستهای دادهها مثل یک حرفهای
فرض کنید یک وبهوک از ووکامرس با ۱۰۰ آیتم سفارش دریافت میکنید. آیا واقعاً میخواهید ۱۰۰ بار یک ورکفلو را تکرار کنید و به ازای هر تسک هزینه اضافی بپردازید؟
یا بدتر، با یک خطا در آیتم پنجاهم، کل فرآیند متوقف شود؟ این شکنندگی، دقیقاً نقطهای است که اتوماسیونهای خطی به بنبست میرسند.
اما در پلتفرم اتوماسیون n8n، ما با استفاده از Loop & Merge قواعد بازی را تغییر میدهیم. این قابلیت به شما اجازه میدهد تا از محدودیتهای ابزارهای ساده عبور کرده و یک سیستم مقیاسپذیر برای پردازش هزاران آیتم بسازید. این مقاله، راهنمای فنی شما برای پیادهسازی این معماری در سال ۲۰۲۶ است.
در دنیای مهندسی اتوماسیون، راهحل این مشکل، «پردازش دستهای» (Batch Processing) است. به جای اجرای صدبارهی یک فرآیند برای صد آیتم، ما یک بار فرآیند را برای یک بسته (Batch) صدتایی اجرا میکنیم. n8n با معماری دادهمحور خود، این قابلیت را به صورت نیتیو در هستهی خود دارد تا هزینهها را کنترل کنید و در برابر خطا مقاوم باشید.
Loop & Merge چیست و چه زمانی قاتل محدودیتهای Zapier میشود؟
به زبان فنی، Looping (حلقه) در n8n به معنای تکرار یک یا چند عملیات بر روی هر یک از آیتمهای موجود در یک آرایه (Array) از دادههاست.
n8n برخلاف ابزارهای دیگر که با یک آیتم داده کار میکنند، به صورت پیشفرض با لیستی از آیتمها کار میکند. هر «آیتم» در n8n یک شیء JSON است و خروجی یک نود، آرایهای از این اشیاء است.
وقتی یک نود، آرایهای با ۵ آیتم را به نود بعدی ارسال میکند، نود بعدی به صورت خودکار ۵ بار اجرا میشود، یک بار برای هر آیتم. این رفتار ذاتی، پایهی تمام حلقهها در n8n است.
Merge (ادغام) عملیات معکوس حلقه است. پس از اینکه پردازش روی آیتمهای مختلف در شاخههای موازی به پایان رسید، نود Merge نتایج این شاخههای پراکنده را دوباره در یک آرایه واحد و یکپارچه جمعآوری میکند.
این معماری، تضاد بنیادین Loop & Merge در n8n با مدل «یک ورودی -> یک خروجی» ابزارهایی مثل Zapier است. به بیان ساده:
⚠️ نکته امنیتی: اگر از Webhook برای شروع این فرآیند استفاده میکنید، حتماً در تنظیمات نود Webhook، گزینه Authentication را فعال کنید تا از ارسال دادههای مخرب یا فیک توسط رباتها جلوگیری شود.
دیاگرام زیر این تفاوت را به سادگی نمایش میدهد:
`mermaid
graph TD
subgraph “مدل Zapier (پردازش تکبهتک)”
direction LR
A1[Webhook: item1] –> B1[Zap Run #1];
A2[Webhook: item2] –> B2[Zap Run #2];
A3[Webhook: item3] –> B3[Zap Run #3];
end
subgraph “مدل n8n (پردازش دستهای)”
direction LR
C[Webhook: [item1, item2, item3]] –> D{Workflow Run #1};
D — Loop over items –> E1[Process item1];
D — Loop over items –> E2[Process item2];
D — Loop over items –> E3[Process item3];
end
`
این قابلیت زمانی به «قاتل محدودیتها» تبدیل میشود که:
ورکفلو آماده: همین حالا دانلود کنید
وقت خود را برای ساختن از صفر تلف نکنید. فایل JSON ورکفلو «خواندن از گوگل شیت و ارسال ایمیل» را دانلود کرده و مستقیماً در n8n خودتان ایمپورت کنید.
آموزش گامبهگام: ساخت اولین حلقه (Loop) در n8n
در این سناریو، میخواهیم لیستی از مشتریان جدید را از یک گوگل شیت بخوانیم و برای هر کدام یک ایمیل خوشامدگویی شخصیسازیشده ارسال کنیم. این سادهترین و رایجترین شکل یک حلقه در n8n است.
پیشنیازها:
1. یک گوگل شیت با سه ستون: name, email, product.
2. چند ردیف داده تستی در آن وارد کنید.
3. یک اکانت n8n (ترجیحاً نسخه داکر Self-hosted برای پایداری بیشتر یا نسخه Cloud).
4. اتصال (Credential) گوگل و SMTP (برای ارسال ایمیل) در n8n شما تنظیم شده باشد.
مرحله ۱: خواندن داده از Google Sheets
یک نود Google Sheets به ورکفلو اضافه کنید و آن را به شکل زیر تنظیم نمایید:
Read (یا Get Many در نسخههای جدید).A:C.First Row as Header به صورت خودکار فعال است. مطمئن شوید خروجی JSON کلیدهای معنادار دارد.ورکفلو را اجرا کنید. خروجی نود باید آرایهای از اشیاء JSON باشد، مشابه زیر:
`json
[
{
“name”: “آرش تقوی”,
“email”: “arash@example.com”,
“product”: “سرویس ابری”
},
{
“name”: “سارا محمدی”,
“email”: “sara@example.com”,
“product”: “پشتیبانی فنی”
},
{
“name”: “بهنام رضایی”,
“email”: “behnam@example.com”,
“product”: “مشاوره تخصصی”
}
]
`
شما ۳ آیتم در خروجی دارید. این یعنی هر نود بعدی به صورت خودکار ۳ بار اجرا خواهد شد.
مرحله ۲: ارسال ایمیل شخصیسازیشده
یک نود Send Email (یا نود SMTP خودتان) را به نود Google Sheets متصل کنید.
Add Expression را انتخاب کنید. سپس مقدار زیر را وارد کنید: {{ $json.email }}
این عبارت به n8n میگوید که برای هر بار اجرا، مقدار فیلد email از آیتم *جاری* را بردارد.
خوش آمدید، {{ $json.name }} عزیز! سلام {{ $json.name }}،
از علاقه شما به محصول «{{ $json.product }}» سپاسگزاریم.
مرحله ۳: اجرا و بررسی نتایج
کل ورکفلو را اجرا کنید. به Execution Log (گزارش اجرا) نگاه کنید. خواهید دید که نود Send Email سه بار اجرا شده و برای هر اجرا، ورودی و خروجی متفاوتی داشته است. این یعنی حلقه شما با موفقیت کار کرده و سه ایمیل مجزا ارسال شده است.
کد JSON ورکفلو:
شما میتوانید کد زیر را کپی کرده و مستقیماً در n8n خودتان Paste کنید تا این ورکفلو برایتان ساخته شود. (فراموش نکنید که Credential های خودتان را جایگزین کنید).
`json
{
“name”: “Loop Example: Google Sheets to Email”,
“nodes”: [
{
“parameters”: {},
“name”: “Start”,
“type”: “n8n-nodes-base.start”,
“typeVersion”: 1,
“position”: [
250,
300
]
},
{
“parameters”: {
“sheetId”: “YOUR_SHEET_ID”,
“options”: {
“key”: “name,email,product”
}
},
“name”: “Read Customer List”,
“type”: “n8n-nodes-base.googleSheets”,
“typeVersion”: 4,
“position”: [
450,
300
],
“credentials”: {
“googleSheetsOAuth2Api”: {
“id”: “YOUR_CREDENTIAL_ID”,
“name”: “Google Sheets account”
}
}
},
{
“parameters”: {
“to”: “={{ $json.email }}”,
“subject”: “خوش آمدید، {{ $json.name }} عزیز!”,
“html”: “سلام {{ $json.name }},
از علاقه شما به محصول «{{ $json.product }}» سپاسگزاریم.
تیم کارورا”
},
“name”: “Send Welcome Email”,
“type”: “n8n-nodes-base.emailSend”,
“typeVersion”: 2,
“position”: [
650,
300
],
“credentials”: {
“smtp”: {
“id”: “YOUR_SMTP_CREDENTIAL_ID”,
“name”: “SMTP account”
}
}
}
],
“connections”: {
“Start”: {
“main”: [
[
{
“node”: “Read Customer List”,
“type”: “main”,
“index”: 0
}
]
]
},
“Read Customer List”: {
“main”: [
[
{
“node”: “Send Welcome Email”,
“type”: “main”,
“index”: 0
}
]
]
}
}
}
`
ورکفلو آماده: همین حالا دانلود کنید
وقت خود را برای ساختن از صفر تلف نکنید. فایل JSON ورکفلو «خواندن از گوگل شیت و ارسال ایمیل» را دانلود کرده و مستقیماً در n8n خودتان ایمپورت کنید.
جعبه ابزار حرفهایها: نودهای کلیدی برای پیادهسازی Loop در n8n
حلقه ذاتی n8n برای شروع عالی است، اما در پروژههای واقعی، شما به کنترل بیشتری نیاز دارید. دو ابزار اصلی برای این کار وجود دارد: نود مدرن Loop Over Items (که جایگزین SplitInBatches قدیمی شده است) برای مدیریت دستهها، و نود Code (جایگزین Function) برای انعطافپذیری مطلق.
روش استاندارد: نود Loop Over Items (حالت Batching)
این نود قدرتمندترین ابزار برای مدیریت تکرار است. میتوانید آن را تنظیم کنید تا یک آرایه بزرگ را به چندین آرایه کوچکتر (دسته یا Batch) تقسیم کند.
چه زمانی استفاده کنیم؟
نحوه کار:
نود Loop Over Items را بعد از نودی که دادهها را تولید میکند قرار دهید. در تنظیمات آن، گزینه Batch Size را روی تعداد دلخواه (مثلاً ۵۰) تنظیم کنید. این نود به صورت خودکار خروجی را دسته به دسته به نودهای بعدی میفرستد و پس از اتمام پردازش هر دسته، به سراغ دسته بعدی میرود.
روش پیشرفته: نود Code و جاوااسکریپت
وقتی به منطق پیچیدهتری نیاز دارید که نودهای استاندارد پوشش نمیدهند، نود Code (که در نسخههای قدیمی Function نام داشت) راهحل شماست. با استفاده از جاوااسکریپت، میتوانید کنترل کاملی بر روی تغییر ساختار داده داشته باشید.
توصیه ما در کارورا: همیشه از نود Code استفاده کنید تا با استانداردهای جدید n8n سازگار باشید و از متدهای مدرن مثل .map() بهره ببرید.
مثال ۱: تبدیل و غنیسازی داده با .map()
فرض کنید میخواهید نام و نام خانوادگی را از ورودی ترکیب کرده و یک فیلد fullName بسازید.
`javascript
// ورودی به نود Code، متغیر $input.all() یا items است
// دسترسی به تمام آیتمهای ورودی:
const items = $input.all();
return items.map(item => {
const firstName = item.json.first_name;
const lastName = item.json.last_name;
// ایجاد یک آیتم جدید با ساختار دلخواه
return {
json: {
id: item.json.user_id,
fullName: ${firstName} ${lastName},
email: item.json.email,
processedAt: new Date().toISOString()
}
};
});
`
مثال ۲: منطق شرطی پیشرفته
در این مثال، ما روی آیتمها حلقه میزنیم و فقط آیتمهای واجد شرایط را عبور میدهیم.
`javascript
const items = $input.all();
const processedItems = [];
for (const item of items) {
// فرض کنید فقط کاربرانی که در ایران هستند را میخواهیم
if (item.json.country === ‘IR’) {
// یک عملیات روی داده انجام میدهیم
const enrichedData = {
…item.json,
status: ‘ReadyForProcessing’,
priority: 1
};
processedItems.push({ json: enrichedData });
}
}
return processedItems;
`
| ویژگی | نود Loop Over Items | نود Code (JS) |
|---|---|---|
| سهولت استفاده | بسیار ساده، رابط گرافیکی دارد. | نیاز به دانش جاوااسکریپت دارد. |
| انعطافپذیری | عالی برای دستهبندی و تکرار. | نامحدود. هر منطقی قابل پیادهسازی است. |
| مورد استفاده اصلی | مدیریت Rate Limit، کنترل حافظه. | تبدیل داده، فیلتر پیچیده، منطق سفارشی. |
هنر ادغام (Merge): چگونه دادههای پراکنده را دوباره به هم ببافیم؟
پس از اینکه یک حلقه اجرا شد یا ورکفلو شما به چند شاخه تقسیم شد، اغلب نیاز دارید که نتایج را دوباره در یک نقطه جمعآوری کنید. این کار وظیفه نود Merge است.
نود Merge دو ورودی (Input 1 و Input 2) دارد و بر اساس حالت (Mode) انتخابی، دادههای این دو ورودی را ترکیب میکند.
حالت Append: الحاق کردن دادهها
این رایجترین حالت است. نود Merge لیست آیتمهای ورودی دوم را به انتهای لیست آیتمهای ورودی اول اضافه میکند.
حالت Keep Key Matches: ترکیب دادهها بر اساس کلید مشترک
این حالت برای غنیسازی داده فوقالعاده قدرتمند است. نود دو لیست را بر اساس یک کلید مشترک (مثلاً id یا email) مقایسه میکند و اطلاعات آیتمهای منطبق را با هم ادغام میکند.
سناریوهای پیشرفته و پولساز با Loop & Merge
بیایید تئوری را به عمل تبدیل کنیم. در ادامه سه سناریوی واقعی که ارزش تجاری مستقیم دارند را بررسی میکنیم.
۱. همگامسازی محصولات ووکامرس با انبار از طریق فایل CSV
SKU و stock_quantity ارسال میکند. باید موجودی محصولات در ووکامرس به روز شود. `mermaid
graph TD
A[Cron Trigger: Daily at 2 AM] –> B[FTP/HTTP: Download CSV];
B –> C[Spreadsheet File: Read CSV Data];
C –> D[Loop Over Items: Batch Size = 50];
D –> E{Processing Loop};
E –> F[HTTP Request: PUT /wp-json/wc/v3/products/batch];
F –> G[Wait: 10 seconds];
G — Auto-Next Batch –> D;
D — Done –> H[Slack: Send “Sync Complete” message];
`
1. Spreadsheet File Node: فایل CSV را میخواند.
2. Loop Over Items Node: برای جلوگیری از فشار روی API، لیست ۱۰۰۰ محصولی را به دستههای ۵۰تایی تقسیم میکند.
3. HTTP Request Node: از اندپوینت batch ووکامرس استفاده میکند.
4. Wait Node: بین هر درخواست دستهای، یک تأخیر کوتاه ایجاد میکند.
۲. ساخت گزارش هفتگی از Google Analytics و ارسال به Slack
`mermaid
graph TD
A[Cron Trigger: Every Monday 9 AM] –> B(Get Traffic Data);
A –> C(Get Conversion Data);
B –> D{Merge: Mode Append};
C –> D;
D –> E[Code: Format Data with Markdown];
E –> F[Slack: Post Formatted Report];
`
1. Parallel Execution: دو نود Google Analytics به صورت موازی اجرا میشوند.
2. Merge Node (Append): نتایج ترکیب میشوند.
3. Code Node: دادهها را به متن فرمتشده برای Slack تبدیل میکند.
زره دفاعی ورکفلو: مدیریت خطا برای پایداری حداکثری
یکی از بزرگترین ریسکها در پردازش دستهای این است که خطا در یک آیتم، کل فرآیند را متوقف کند. در پروژههای واقعی، این غیرقابل قبول است.
تکنیک اصلی: Continue on Fail
در تنظیمات هر نودی که ممکن است با خطا مواجه شود، گزینه Continue on Fail (یا On Error: Continue) را فعال کنید.
با فعال کردن این گزینه، اگر آن نود در حین پردازش یک آیتم با خطا مواجه شود:
1. ورکفلو متوقف نمیشود.
2. پردازش به آیتم بعدی ادامه پیدا میکند.
3. n8n یک شیء error به خروجی اضافه میکند.
الگوی عملی برای لاگ کردن خطاها:
1. در نود HTTP Request، گزینه Continue on Fail را فعال کنید.
2. بعد از آن، یک نود IF قرار دهید.
3. شرط نود IF را بررسی وجود error قرار دهید.
4. خروجی true (خطا رخ داده): به یک نود Google Sheets متصل کنید تا خطا ثبت شود.
5. خروجی false (موفق): به ادامه مسیر عادی بروید.
این ساختار تضمین میکند که ورکفلو شما پایدار است و هیچ دادهای از دست نمیرود.
نتیجهگیری: Loop & Merge فقط یک ابزار نیست، یک طرز فکر برای مقیاسپذیری است
در این راهنما، از مفاهیم پایه تا تکنیکهای پیشرفته پردازش دستهای در n8n را پوشش دادیم. نکات کلیدی:
Loop Over Items برای دستهبندی و Code برای منطق خاص.Continue on Fail برای جلوگیری از توقف.تسلط بر این مفاهیم، مرز بین ساخت اتوماسیونهای ساده و طراحی سیستمهای مهندسیشده و قابل اعتماد است.
اتوماسیون شما میتواند یک دارایی استراتژیک باشد
پیادهسازی Loop & Merge، مدیریت خطا و ساختارهای مقیاسپذیر در سطح B2B پیچیده است. بیایید در یک جلسه استراتژی ۱۵ دقیقهای رایگان، چالشهای کسبوکار شما را بررسی کنیم و ببینیم چطور تیم کارورا میتواند زیرساخت اتوماسیون شما را متحول کند.
