نود Loop Over Items در N8N

نود Loop Over Items در N8N

نود Loop Over Items یکی از نودهای مهم و کاربردی در N8N برای اجرای مرحله‌به‌مرحله روی آیتم‌ها است. زمانی که تعداد زیادی داده دارید و می‌خواهید آن‌ها را به‌صورت تکی یا دسته‌ای پردازش کنید، این نود به شما کمک می‌کند کنترل بیشتری روی جریان اجرای ورکفلو داشته باشید.

برای مثال اگر ۵۰۰ ردیف از Google Sheets دریافت کرده‌اید و می‌خواهید برای هر ردیف یک درخواست HTTP ارسال کنید، یا اگر قصد دارید اطلاعات کاربران را یکی‌یکی بررسی و در یک سرویس دیگر ثبت کنید، نود Loop Over Items انتخاب بسیار مناسبی است.

معرفی نود در N8N

نود Loop Over Items برای پیمایش روی آیتم‌های ورودی در N8N استفاده می‌شود. این نود داده‌های ورودی را به بخش‌های کوچک‌تر تقسیم می‌کند و در هر بار اجرا، یک آیتم یا یک دسته از آیتم‌ها را به خروجی Loop می‌فرستد. پس از پایان پردازش همه آیتم‌ها، خروجی Done فعال می‌شود.

• نام نود: Loop Over Items
• نوع نود: Core Node
• دسته‌بندی کاربردی: Function / Flow Control
• کاربرد اصلی: اجرای عملیات تکراری روی آیتم‌ها به‌صورت تکی یا دسته‌ای
• نام قدیمی‌تر در برخی نسخه‌ها: Split In Batches

در N8N بسیاری از نودها می‌توانند چند آیتم را به‌صورت هم‌زمان پردازش کنند، اما همیشه این حالت مناسب نیست. گاهی لازم است آیتم‌ها یکی‌یکی پردازش شوند؛ برای مثال زمانی که API مقصد محدودیت نرخ درخواست دارد، یا زمانی که باید بین هر درخواست کمی تأخیر ایجاد شود. در چنین شرایطی Loop Over Items باعث می‌شود اجرای ورکفلو قابل‌کنترل‌تر، پایدارتر و قابل‌پیش‌بینی‌تر شود.

Loop و Done در این نود چه معنایی دارند؟

نود Loop Over Items معمولاً دو خروجی اصلی دارد:

• Loop: خروجی‌ای که آیتم یا دسته فعلی را برای پردازش ارسال می‌کند.
• Done: خروجی‌ای که بعد از تمام شدن همه آیتم‌ها فعال می‌شود.

الگوی رایج استفاده از این نود به این شکل است که خروجی Loop به نودهای پردازشی وصل می‌شود و آخرین نود پردازشی دوباره به ورودی Loop Over Items برمی‌گردد. وقتی همه آیتم‌ها پردازش شدند، خروجی Done ادامه ورکفلو را اجرا می‌کند.

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

نود Loop Over Items در بسیاری از سناریوهای واقعی اتوماسیون کاربرد دارد. هرجا لازم باشد داده‌ها به‌صورت کنترل‌شده و مرحله‌به‌مرحله پردازش شوند، این نود می‌تواند بخش اصلی طراحی ورکفلو باشد.

۱. ارسال درخواست API برای هر آیتم

فرض کنید لیستی از کاربران را از Google Sheets دریافت کرده‌اید و باید برای هر کاربر یک درخواست به یک API خارجی ارسال کنید. اگر همه درخواست‌ها هم‌زمان ارسال شوند، ممکن است با خطای Rate Limit یا محدودیت تعداد درخواست مواجه شوید. با Loop Over Items می‌توانید هر کاربر را جداگانه پردازش کنید.

• Google Sheets: دریافت لیست کاربران
• Loop Over Items: پردازش کاربران یکی‌یکی
• HTTP Request: ارسال اطلاعات هر کاربر به API
• Loop Over Items: برگشت برای دریافت آیتم بعدی
• Done: اجرای مرحله نهایی پس از پایان همه کاربران

۲. پردازش سفارش‌های فروشگاه

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

• دریافت سفارش‌ها از WooCommerce یا Shopify
• Loop Over Items برای بررسی هر سفارش
• IF برای تشخیص وضعیت پرداخت
• Email یا Telegram برای ارسال پیام
• Database برای ثبت نتیجه پردازش

۳. مدیریت محدودیت Rate Limit در APIها

بسیاری از سرویس‌ها مانند OpenAI، Slack، Telegram، Notion، HubSpot و سایر APIها محدودیت تعداد درخواست در دقیقه دارند. با Loop Over Items و نود Wait می‌توان بین پردازش هر آیتم فاصله ایجاد کرد.

• Loop Over Items با Batch Size برابر 1
• HTTP Request برای ارسال درخواست
• Wait برای ایجاد تأخیر مثلاً ۲ ثانیه
• اتصال دوباره به Loop Over Items

۴. ارسال ایمیل‌های شخصی‌سازی‌شده

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

• Google Sheets یا Airtable برای دریافت مخاطبان
• Loop Over Items برای پردازش هر مخاطب
• Set برای آماده‌سازی متن ایمیل
• Gmail یا SMTP برای ارسال ایمیل
• Wait برای جلوگیری از ارسال بیش از حد سریع

۵. پردازش فایل‌ها و رکوردهای حجیم

اگر تعداد زیادی فایل، تصویر، رکورد دیتابیس یا داده JSON دارید، اجرای همه آن‌ها به‌صورت هم‌زمان ممکن است باعث مصرف زیاد حافظه یا کندی ورکفلو شود. Loop Over Items امکان پردازش مرحله‌ای را فراهم می‌کند.

• دریافت لیست فایل‌ها از Google Drive یا S3
• Loop Over Items برای انتخاب هر فایل
• دانلود فایل
• پردازش یا تبدیل فایل
• آپلود نتیجه در مقصد جدید

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

نود Loop Over Items تنظیمات ساده‌ای دارد، اما درک درست همین تنظیمات برای طراحی ورکفلوهای پایدار بسیار مهم است. مهم‌ترین پارامتر این نود، اندازه دسته یا Batch Size است.

لیست پارامترها

Batch Size

پارامتر Batch Size مشخص می‌کند در هر تکرار حلقه چند آیتم به خروجی Loop ارسال شود. این مقدار به‌صورت عددی تنظیم می‌شود.

• Batch Size = 1: پردازش کاملاً آیتم‌به‌آیتم
• Batch Size = 5: پردازش ۵ آیتم در هر مرحله
• Batch Size = 100: مناسب برای پردازش دسته‌ای رکوردها، در صورتی که سرویس مقصد توانایی دریافت حجم بیشتری از داده را داشته باشد

انتخاب مقدار مناسب برای Batch Size به نوع عملیات، محدودیت API، حجم داده و منابع سرور بستگی دارد.

نمونه انتخاب Batch Size در سناریوهای مختلف

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

• اگر API مقصد محدودیت دارد، مقدار Batch Size را پایین نگه دارید.
• برای پردازش‌های سنگین مانند دانلود فایل، تبدیل تصویر یا پردازش متن‌های طولانی، Batch Size برابر 1 معمولاً امن‌تر است.
• اگر نودهای بعدی از پردازش چند آیتم هم‌زمان پشتیبانی می‌کنند، می‌توانید Batch Size را بالاتر ببرید.
• در حلقه‌های طولانی، بهتر است از نود Wait برای ایجاد فاصله زمانی بین تکرارها استفاده شود.
• آخرین نود داخل حلقه باید دوباره به ورودی Loop Over Items وصل شود تا آیتم بعدی پردازش شود.
• خروجی Done فقط زمانی اجرا می‌شود که همه آیتم‌ها پردازش شده باشند.
• اگر اتصال برگشتی به نود Loop Over Items را فراموش کنید، فقط اولین دسته پردازش می‌شود و حلقه ادامه پیدا نمی‌کند.

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

نود Loop Over Items با آیتم‌های استاندارد N8N کار می‌کند. در N8N داده‌ها معمولاً به شکل آرایه‌ای از آیتم‌ها هستند که هر آیتم یک بخش json دارد. این نود آیتم‌های ورودی را دریافت می‌کند، آن‌ها را بر اساس Batch Size تقسیم می‌کند و در هر تکرار بخشی از داده را به خروجی Loop می‌فرستد.

ساختار ورودی

ورودی نود معمولاً آرایه‌ای از آیتم‌ها است. هر آیتم می‌تواند شامل اطلاعاتی مانند نام کاربر، ایمیل، شناسه سفارش، قیمت، وضعیت یا هر داده دیگری باشد.

[  {    "json": {      "id": 1,      "name": "Ali",      "email": "ali@example.com"    }  },  {    "json": {      "id": 2,      "name": "Sara",      "email": "sara@example.com"    }  },  {    "json": {      "id": 3,      "name": "Reza",      "email": "reza@example.com"    }  }]

اگر Batch Size برابر 1 باشد، نود در هر تکرار فقط یک آیتم را از خروجی Loop ارسال می‌کند.

خروجی Loop

خروجی Loop شامل آیتم یا دسته فعلی است. برای مثال اگر Batch Size برابر 1 باشد، در اولین تکرار خروجی به شکل زیر خواهد بود:

[  {    "json": {      "id": 1,      "name": "Ali",      "email": "ali@example.com"    }  }]

در تکرار دوم، آیتم بعدی ارسال می‌شود:

[  {    "json": {      "id": 2,      "name": "Sara",      "email": "sara@example.com"    }  }]

خروجی Done

خروجی Done زمانی فعال می‌شود که همه آیتم‌ها پردازش شده باشند. این خروجی برای اجرای مراحل نهایی استفاده می‌شود؛ مانند ارسال گزارش، ذخیره نتیجه نهایی، اطلاع‌رسانی به مدیر یا ثبت لاگ کلی.

اگر داخل حلقه داده‌ها تغییر داده شوند، خروجی Done معمولاً شامل داده‌هایی است که در طول حلقه پردازش شده‌اند. بنابراین اگر می‌خواهید نتیجه نهایی کامل و قابل‌استفاده باشد، باید مطمئن شوید نودهای داخل حلقه داده‌های موردنیاز را به خروجی برمی‌گردانند.

نمونه ساختار خروجی پردازش‌شده

[  {    "json": {      "id": 1,      "name": "Ali",      "email": "ali@example.com",      "status": "sent"    }  },  {    "json": {      "id": 2,      "name": "Sara",      "email": "sara@example.com",      "status": "sent"    }  },  {    "json": {      "id": 3,      "name": "Reza",      "email": "reza@example.com",      "status": "failed"    }  }]

مثال ساده جریان داده

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

۱. ترکیب Loop Over Items با Wait برای کنترل سرعت اجرا

یکی از رایج‌ترین ترفندها، استفاده از نود Wait داخل حلقه است. این کار باعث می‌شود بین پردازش هر آیتم فاصله ایجاد شود. این روش برای APIهایی که محدودیت Rate Limit دارند بسیار مفید است.

• Loop Over Items با Batch Size برابر 1
• HTTP Request برای ارسال داده
• Wait به مدت ۱ تا ۵ ثانیه
• اتصال مجدد Wait به Loop Over Items

این الگو در ارسال پیام، ایمیل، درخواست API و عملیات حساس به محدودیت سرعت بسیار کاربردی است.

۲. ذخیره وضعیت هر آیتم داخل حلقه

بهتر است پس از پردازش هر آیتم، نتیجه آن را مشخص کنید. برای مثال می‌توانید با نود Set یک فیلد status به آیتم اضافه کنید.

{  "id": 25,  "email": "user@example.com",  "status": "processed",  "processedAt": "2026-05-26T10:30:00.000Z"}

این کار باعث می‌شود خروجی نهایی Done قابل گزارش‌گیری باشد و بتوانید بفهمید کدام آیتم‌ها موفق یا ناموفق بوده‌اند.

۳. مدیریت خطا داخل حلقه

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

• فعال کردن گزینه Continue On Fail در نودهای حساس مانند HTTP Request
• استفاده از IF برای بررسی موفقیت یا شکست پاسخ API
• ثبت خطاها در Google Sheets، دیتابیس یا فایل لاگ
• ارسال هشدار به Slack یا Telegram در صورت شکست پردازش یک آیتم

۴. استفاده از Batch Size بیشتر برای افزایش سرعت

اگر سرویس مقصد محدودیت سخت‌گیرانه ندارد، می‌توانید Batch Size را بیشتر کنید. این کار باعث می‌شود تعداد تکرارهای حلقه کمتر شود و ورکفلو سریع‌تر اجرا شود.

برای مثال اگر ۱۰۰۰ آیتم دارید:

• Batch Size برابر 1 یعنی ۱۰۰۰ تکرار
• Batch Size برابر 10 یعنی ۱۰۰ تکرار
• Batch Size برابر 100 یعنی ۱۰ تکرار

البته افزایش Batch Size همیشه بهتر نیست. اگر هر آیتم پردازش سنگینی دارد یا API مقصد محدودیت دارد، مقدار پایین‌تر امن‌تر است.

۵. ترکیب با IF برای پردازش شرطی

می‌توانید داخل حلقه از نود IF استفاده کنید تا فقط بعضی آیتم‌ها پردازش شوند. برای مثال فقط سفارش‌هایی که وضعیت آن‌ها paid است وارد مرحله صدور فاکتور شوند.

• Loop Over Items
• IF: بررسی status برابر paid
• HTTP Request: صدور فاکتور
• Set: ثبت نتیجه
• برگشت به Loop Over Items

۶. ترکیب با Merge برای ساخت گزارش نهایی

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

۷. استفاده از Code Node برای تغییر داده‌ها قبل یا بعد از حلقه

گاهی لازم است قبل از ورود داده‌ها به Loop Over Items، ساختار آن‌ها اصلاح شود. نود Code برای تبدیل آرایه‌ها، فیلترکردن داده‌ها یا اضافه‌کردن فیلدهای کمکی بسیار مفید است.

return items.map(item => {  item.json.needsProcessing = item.json.status === "new";  return item;});

۸. جلوگیری از حلقه بی‌پایان

Loop Over Items برای پردازش آیتم‌های ورودی طراحی شده و معمولاً بعد از پایان آیتم‌ها وارد خروجی Done می‌شود. اما طراحی اشتباه اتصال‌ها می‌تواند باعث اجرای ناخواسته یا رفتار گیج‌کننده شود. برای جلوگیری از مشکل:

• فقط مسیر پردازش اصلی را به ورودی Loop Over Items برگردانید.
• خروجی Done را دوباره به ورودی حلقه متصل نکنید.
• از IF و مسیرهای شرطی با دقت استفاده کنید.
• در ورکفلوهای پیچیده، ابتدا با تعداد کمی آیتم تست بگیرید.

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

محدودیت‌های نود Loop Over Items

• این نود خودش پردازش خاصی روی داده انجام نمی‌دهد؛ فقط جریان پردازش آیتم‌ها را کنترل می‌کند.
• برای اجرای درست حلقه، باید اتصال برگشتی از انتهای مسیر پردازش به خود نود برقرار شود.
• اگر حجم داده بسیار زیاد باشد، همچنان ممکن است مصرف حافظه یا زمان اجرای ورکفلو بالا برود.
• در صورت طراحی نادرست مسیرهای شرطی، ممکن است بعضی آیتم‌ها پردازش نشوند یا نتیجه نهایی ناقص باشد.
• این نود جایگزین کامل پردازش Bulk در APIها نیست؛ اگر API مقصد عملیات Bulk واقعی دارد، گاهی استفاده مستقیم از Bulk API بهینه‌تر است.
• خروجی Done وابسته به داده‌هایی است که از مسیر حلقه برمی‌گردند؛ اگر نودهای داخل حلقه خروجی مناسب تولید نکنند، داده نهایی ممکن است کامل نباشد.

خطای رایج: فقط اولین آیتم پردازش می‌شود

علت: معمولاً اتصال برگشتی از آخرین نود داخل حلقه به Loop Over Items ایجاد نشده است.

راه‌حل: خروجی آخرین نود پردازشی را دوباره به ورودی Loop Over Items متصل کنید تا نود بتواند دسته بعدی را ارسال کند.

خطای رایج: خروجی Done اجرا نمی‌شود

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

راه‌حل: اجرای هر نود داخل حلقه را بررسی کنید، گزینه Continue On Fail را برای نودهای پرریسک فعال کنید و مطمئن شوید همه مسیرها در نهایت به Loop Over Items برمی‌گردند.

خطای رایج: دریافت خطای Too Many Requests

علت: ارسال سریع درخواست‌ها به API مقصد یا انتخاب Batch Size بالا.

راه‌حل: مقدار Batch Size را کاهش دهید و از نود Wait بین درخواست‌ها استفاده کنید.

خطای رایج: داده‌ها در خروجی نهایی ناقص هستند

علت: یکی از نودهای داخل حلقه داده اصلی را حذف کرده یا فقط بخشی از اطلاعات را برگردانده است.

راه‌حل: با نود Set یا Merge داده‌های اصلی را حفظ کنید. همچنین خروجی هر نود داخل حلقه را بررسی کنید تا مطمئن شوید فیلدهای لازم از بین نمی‌روند.

خطای رایج: اجرای کند ورکفلو

علت: Batch Size بسیار پایین، تعداد آیتم‌های زیاد، وجود Wait طولانی یا عملیات سنگین داخل حلقه.

راه‌حل: اگر محدودیت API ندارید، Batch Size را افزایش دهید. همچنین عملیات غیرضروری داخل حلقه را حذف کنید و پردازش‌های مشترک را قبل یا بعد از حلقه انجام دهید.

خطای رایج: پردازش تکراری آیتم‌ها

علت: طراحی اشتباه مسیرها، استفاده نامناسب از Reset یا برگشت چند مسیر مختلف به نود Loop Over Items.

راه‌حل: ساختار اتصال‌ها را ساده کنید، مسیر برگشتی واحد داشته باشید و با چند آیتم تستی رفتار حلقه را بررسی کنید.

ایده ها

• سیستم ارسال پیام مرحله‌ای: دریافت لیست مشتریان از Google Sheets و ارسال پیام شخصی‌سازی‌شده در Telegram یا WhatsApp با تأخیر کنترل‌شده بین پیام‌ها.
• ربات بررسی قیمت محصولات: دریافت لیست محصولات، ارسال درخواست به API فروشگاه‌ها، مقایسه قیمت و ثبت نتیجه در دیتابیس.
• اتوماسیون صدور فاکتور: پردازش سفارش‌های پرداخت‌شده یکی‌یکی، ساخت فاکتور PDF و ارسال آن به ایمیل مشتری.
• سیستم پاک‌سازی CRM: بررسی مخاطبان CRM، حذف داده‌های تکراری، به‌روزرسانی اطلاعات ناقص و ثبت گزارش نهایی.
• پردازش دسته‌ای محتوا با هوش مصنوعی: دریافت لیست عنوان‌های مقاله، ارسال هر عنوان به مدل هوش مصنوعی، ذخیره خروجی در Notion یا Airtable.

منابع و مستندات اصلی

• مستندات رسمی نود Loop Over Items در N8N
• مستندات رسمی ساخت Workflow در N8N
• آشنایی با ساختار داده در N8N
• مستندات Flow Logic در N8N
• انجمن رسمی N8N
• کانال رسمی N8N در YouTube
• بلاگ رسمی N8N