آموزش Loop Over Items در n8n؛ پردازش داده‌ها به‌صورت حلقه‌ای

فرض کنید یک فهرست شامل ۱۰۰ محصول دارید و می‌خواهید اطلاعات هر محصول را به یک API ارسال کنید. یا ممکن است بخواهید اطلاعات چند صد مشتری را از یک فایل دریافت کرده و برای هرکدام عملیات مشخصی انجام دهید.

در چنین شرایطی، یکی از سؤال‌های مهم این است که چگونه می‌توان داده‌ها را کنترل‌شده پردازش کرد؛ به‌خصوص زمانی که لازم است داده‌ها در دسته‌های کوچک‌تر پردازش شوند یا برای هر مرحله از اجرای Workflow کنترل بیشتری داشته باشیم.

در n8n، نود Loop Over Items برای ایجاد حلقه و پردازش داده‌ها در دسته‌های مشخص کاربرد دارد. این نود در نسخه‌های قدیمی‌تر n8n با نام Split In Batches شناخته می‌شد.

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

Loop Over Items در n8n چیست؟

Loop Over Items نودی است که امکان پردازش داده‌ها را در چند مرحله و دسته‌های مشخص فراهم می‌کند.

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

اگر بخواهیم هر بار فقط ۱۰ آیتم را وارد مرحله پردازش کنیم، می‌توانیم Loop Over Items را طوری تنظیم کنیم که داده‌ها را در دسته‌های ۱۰تایی در اختیار مسیر حلقه قرار دهد.

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

برای مثال:

• دسته اول: آیتم‌های ۱ تا ۱۰
• دسته دوم: آیتم‌های ۱۱ تا ۲۰
• دسته سوم: آیتم‌های ۲۱ تا ۳۰
• ادامه پردازش تا رسیدن به آخرین آیتم

وقتی تمام دسته‌ها پردازش شدند، Workflow می‌تواند از مسیر تکمیل حلقه ادامه پیدا کند.

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

تفاوت پردازش عادی آیتم‌ها با Loop Over Items

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

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

برای مثال، اگر یک نود ۲۰ آیتم تولید کند و آن را به نودی متصل کنید که همه آیتم‌ها را می‌پذیرد، ممکن است نیازی به Loop Over Items نداشته باشید.

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

بنابراین، پیش از افزودن حلقه به Workflow، بررسی کنید که آیا نود موردنظر خودش از پردازش چند آیتم پشتیبانی می‌کند یا خیر.

آشنایی با ورودی‌ها و خروجی‌های Loop Over Items

برای استفاده صحیح از این نود، باید نقش ورودی و خروجی‌های آن را بشناسید.

در حالت رایج، Loop Over Items دو خروجی اصلی دارد:

• Loop: برای پردازش دسته جاری استفاده می‌شود.
• Done: پس از پایان پردازش تمام دسته‌ها، برای ادامه Workflow به کار می‌رود.

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

پس از پایان کار، مسیر Done اجرا می‌شود و می‌توانید عملیات نهایی Workflow را در آن قرار دهید.

این ساختار با اتصال معمولی چند نود تفاوت دارد؛ زیرا مسیر پردازش دوباره به نود حلقه برمی‌گردد.

آموزش ساخت اولین Loop در n8n

در این بخش یک مثال ساده می‌سازیم که در آن چند محصول را در دسته‌های کوچک‌تر پردازش می‌کنیم.

مرحله اول: ایجاد Workflow

وارد n8n شوید و یک Workflow جدید بسازید.

یک نود Manual Trigger اضافه کنید تا بتوانید Workflow را به‌صورت دستی اجرا کنید.

سپس یک نود Edit Fields به آن متصل کنید تا داده‌های آزمایشی محصولات را آماده کنیم.

ساختار اولیه:

Manual Trigger → Edit Fields

مرحله دوم: تعریف داده‌های آزمایشی

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

برای مثال، داده‌ها می‌توانند شامل فیلدهای زیر باشند:

• product_id
• product_name
• price

نمونه یک آیتم:

{

  "product_id": 101,

  "product_name": "Keyboard",

  "price": 1200000

}

برای آزمایش حلقه، بهتر است چند آیتم مجزا داشته باشید؛ برای مثال پنج محصول با شناسه‌های متفاوت.

توجه کنید که در n8n هر آیتم ورودی معمولاً یک شیء JSON مستقل است. اگر داده‌ها را به‌صورت یک آرایه داخل یک فیلد قرار دهید، ممکن است لازم باشد ابتدا آن آرایه را به آیتم‌های مستقل تبدیل کنید.

مرحله سوم: اضافه‌کردن Loop Over Items

یک نود Loop Over Items به Workflow اضافه کنید و خروجی Edit Fields را به ورودی آن متصل کنید.

ساختار Workflow اکنون به این شکل است:

Manual Trigger → Edit Fields → Loop Over Items

نود Loop Over Items را باز کنید.

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

با این تنظیم، نود تلاش می‌کند محصولات را در دسته‌های حداکثر دوتایی در اختیار مسیر Loop قرار دهد.

مرحله چهارم: اضافه‌کردن نود پردازش

بعد از Loop Over Items، یک نود برای پردازش داده‌ها قرار دهید.

برای مثال، می‌توانید از یک نود Edit Fields دیگر استفاده کنید تا مقدار یا اطلاعاتی را به هر محصول اضافه کنید.

در این مثال فرض می‌کنیم می‌خواهیم مشخص کنیم که هر محصول وارد مرحله پردازش شده است.

یک فیلد به نام processed تعریف کنید و مقدار آن را برابر true قرار دهید.

در تنظیمات نود، مطمئن شوید فیلدهای ورودی موردنیاز نیز حفظ می‌شوند؛ زیرا رفتار حفظ فیلدها به تنظیمات نود بستگی دارد.

مرحله پنجم: اتصال خروجی‌ها برای ایجاد حلقه

این مرحله مهم‌ترین قسمت ساخت Workflow است.

خروجی Loop از Loop Over Items را به نود پردازش متصل کنید.

سپس خروجی نود پردازش را دوباره به ورودی Loop Over Items برگردانید.

ساختار کلی به این شکل خواهد بود:

Edit Fields → Loop Over Items → Loop → نود پردازش → بازگشت به Loop Over Items

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

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

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

مرحله ششم: اجرای Workflow

Workflow را اجرا کنید و وضعیت هر نود را بررسی کنید.

با Batch Size برابر ۲ و پنج آیتم ورودی، انتظار داریم داده‌ها در چند دسته پردازش شوند.

پس از تکمیل تمام دسته‌ها، مسیر Done اجرا می‌شود.

برای اطمینان از صحت عملکرد، موارد زیر را بررسی کنید:

• آیا همه محصولات پردازش شده‌اند؟
• آیا اندازه دسته‌ها مطابق تنظیمات است؟
• آیا فیلدهای اصلی محصولات حفظ شده‌اند؟
• آیا مسیر Done پس از پایان حلقه اجرا شده است؟

این آزمایش ساده به شما کمک می‌کند منطق Loop Over Items را بهتر درک کنید.

مثال کاربردی: ارسال محصولات به یک API در دسته‌های کوچک

اکنون مثال قبلی را به یک سناریوی کاربردی تبدیل می‌کنیم.

فرض کنید یک فهرست شامل ۱۰۰ محصول دارید و می‌خواهید اطلاعات آن‌ها را به یک API ارسال کنید. ممکن است API مقصد برای هر درخواست محدودیت‌هایی داشته باشد یا بخواهید حجم هر مرحله از پردازش را کنترل کنید.

در چنین شرایطی، می‌توانید از Loop Over Items استفاده کنید.

مرحله اول: آماده‌سازی فهرست محصولات

ابتدا داده‌های محصولات را از منبع موردنظر دریافت کنید. این منبع می‌تواند یک فایل، پایگاه داده یا API باشد.

هر محصول باید به‌صورت یک آیتم مستقل در خروجی n8n قرار داشته باشد.

مرحله دوم: تنظیم Batch Size

Loop Over Items را بعد از نود دریافت داده‌ها قرار دهید.

اگر می‌خواهید هر دسته حداکثر شامل ۱۰ محصول باشد، مقدار Batch Size را برابر 10 قرار دهید.

این مقدار به معنای ارسال خودکار ۱۰ محصول در یک درخواست HTTP نیست؛ بلکه به این معناست که مسیر Loop در هر مرحله یک دسته شامل حداکثر ۱۰ آیتم دریافت می‌کند.

مرحله سوم: ارسال داده‌ها به API

یک نود HTTP Request به خروجی Loop متصل کنید.

تنظیمات HTTP Request به ساختار API مقصد بستگی دارد. اگر API برای هر محصول یک درخواست جداگانه می‌خواهد، باید مشخص کنید هر آیتم چگونه به درخواست تبدیل شود.

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

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

مرحله چهارم: بازگرداندن جریان به حلقه

خروجی مرحله پردازش را طبق ساختار Workflow به ورودی Loop Over Items برگردانید تا دسته بعدی پردازش شود.

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

مرحله پنجم: بررسی خطاهای API

اگر API به درخواست‌ها پاسخ خطا بدهد، باید مشخص کنید که Workflow چه رفتاری داشته باشد.

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

رفتار موردنظر را با توجه به اهمیت داده‌ها و امکانات مدیریت خطای نودهای استفاده‌شده طراحی کنید.

نکته مهم: استفاده از Batch Size به‌تنهایی تضمین نمی‌کند که محدودیت تعداد درخواست‌های API یا فاصله زمانی میان درخواست‌ها رعایت شود. برای محدودیت نرخ درخواست، ممکن است به تأخیر کنترل‌شده، تنظیمات اختصاصی نود یا طراحی مناسب‌تری برای پردازش نیاز داشته باشید.

Batch Size چیست و چه مقداری انتخاب کنیم؟

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

برای مثال:

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

برای انتخاب Batch Size مناسب، این موارد را در نظر بگیرید:

• حجم هر آیتم چقدر است؟
• پردازش هر آیتم چقدر زمان می‌برد؟
• سرویس مقصد چه محدودیت‌هایی دارد؟
• در صورت بروز خطا، چه میزان از داده‌ها باید دوباره پردازش شوند؟
• منابع سرور و زمان اجرای Workflow چقدر است؟

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

در مقابل، اگر داده‌ها سبک باشند و پردازش آن‌ها هزینه زیادی نداشته باشد، دسته‌های بزرگ‌تر می‌توانند تعداد مراحل حلقه را کاهش دهند.

هیچ عدد ثابتی برای تمام Workflowها مناسب نیست؛ بهتر است مقدار اولیه را با داده‌های آزمایشی انتخاب کرده و سپس بر اساس عملکرد واقعی تنظیم کنید.

آیا برای هر پردازش چندآیتمی باید از Loop Over Items استفاده کنیم؟

خیر. این یکی از مهم‌ترین نکات در طراحی Workflowهای n8n است.

بسیاری از نودهای n8n می‌توانند چند آیتم را در یک اجرا پردازش کنند. برای مثال، اگر یک نود قابلیت دریافت مجموعه‌ای از آیتم‌ها را داشته باشد، ممکن است بتوانید تمام داده‌ها را مستقیماً به آن بدهید.

در این شرایط، افزودن Loop Over Items ممکن است Workflow را پیچیده‌تر کند، بدون آنکه مزیت خاصی ایجاد کند.

Loop Over Items بیشتر زمانی مناسب است که:

• لازم باشد اندازه دسته‌های پردازش را کنترل کنید.
• بخواهید بعد از هر دسته عملیات مشخصی انجام دهید.
• به کنترل دقیق‌تر جریان اجرای Workflow نیاز داشته باشید.
• لازم باشد داده‌ها در چند مرحله پردازش شوند.

پیش از استفاده از حلقه، مستندات نودهای موردنظر و رفتار آن‌ها در پردازش چند آیتم را بررسی کنید.

تفاوت Loop Over Items و Split In Batches چیست؟

در نسخه‌های قدیمی‌تر n8n، این نود با نام Split In Batches شناخته می‌شد. در نسخه‌های جدیدتر، نام آن به Loop Over Items تغییر کرده است.

اگر در آموزش‌های قدیمی با Split In Batches روبه‌رو شدید، معمولاً با همان مفهوم کلی پردازش مرحله‌ای آیتم‌ها مواجه هستید.

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

خطاهای رایج هنگام استفاده از Loop Over Items

۱. حلقه فقط یک بار اجرا می‌شود

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

راه‌حل:

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

۲. بعضی آیتم‌ها پردازش نمی‌شوند

این مشکل ممکن است به خروجی نودهای قبلی، خطا در مرحله پردازش یا تنظیمات Workflow مربوط باشد.

راه‌حل:

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

۳. Workflow وارد حلقه بی‌پایان می‌شود

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

راه‌حل:

• مسیر بازگشت به Loop Over Items را بررسی کنید.
• مطمئن شوید فقط جریان پردازش موردنیاز به ورودی حلقه برمی‌گردد.
• اجرای Workflow را با تعداد کمی آیتم آزمایش کنید.
• مسیر Done را از مسیر پردازش حلقه جدا نگه دارید.

۴. خروجی نود پردازش، داده‌های اصلی را ندارد

بعضی نودها خروجی را بر اساس نتیجه عملیات خود تولید می‌کنند و ممکن است تمام فیلدهای ورودی را حفظ نکنند.

راه‌حل:

• خروجی نود پردازش را بررسی کنید.
• در صورت نیاز، با Edit Fields ساختار داده را اصلاح کنید.
• اگر لازم است اطلاعات قبلی حفظ شوند، پیش از ادامه Workflow روش مناسب نگهداری یا ترکیب آن‌ها را طراحی کنید.

۵. درخواست‌های API همچنان بیش از حد ارسال می‌شوند

تنظیم Batch Size به این معنی نیست که تمام محدودیت‌های سرویس مقصد رعایت شده‌اند.

راه‌حل:

• مستندات API را درباره محدودیت نرخ درخواست بررسی کنید.
• مشخص کنید API درخواست تکی می‌خواهد یا درخواست دسته‌ای.
• در صورت نیاز، از مکث کنترل‌شده یا سازوکار مناسب برای مدیریت نرخ درخواست استفاده کنید.
• خطاهایی مانند محدودیت نرخ درخواست را ثبت و مدیریت کنید.

نکات حرفه‌ای برای طراحی حلقه در n8n

برای ساخت Workflowهای قابل‌اعتماد، چند اصل را در نظر بگیرید:

۱. ابتدا با داده کم آزمایش کنید. قبل از پردازش هزاران آیتم، Workflow را با چند رکورد آزمایشی اجرا کنید.

۲. خروجی هر مرحله را بررسی کنید. فقط به سبزشدن نودها اکتفا نکنید؛ تعداد آیتم‌ها و ساختار داده‌ها را نیز کنترل کنید.

۳. پردازش تکراری را مدیریت کنید. اگر اجرای Workflow دوباره تکرار شود، ممکن است بعضی عملیات چند بار انجام شوند. برای عملیات حساس، از شناسه یکتا یا روش مناسب جلوگیری از تکرار استفاده کنید.

۴. خطاهای موقت را از خطاهای دائمی جدا کنید. خطای موقت شبکه ممکن است با تلاش دوباره برطرف شود، اما داده نامعتبر معمولاً به اصلاح نیاز دارد.

۵. برای پایان حلقه یک مرحله مشخص در نظر بگیرید. گزارش نهایی، ثبت تعداد آیتم‌های پردازش‌شده یا ارسال اعلان تکمیل عملیات می‌تواند در مسیر Done قرار بگیرد.

پرسش‌های متداول درباره Loop Over Items در n8n

Loop Over Items در n8n چه کاری انجام می‌دهد؟

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

آیا Loop Over Items همان Split In Batches است؟

در نسخه‌های قدیمی‌تر n8n، این نود با نام Split In Batches شناخته می‌شد. نام جدید آن Loop Over Items است، هرچند جزئیات رابط کاربری ممکن است با نسخه متفاوت باشد.

Batch Size چه کاربردی دارد؟

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

آیا می‌توان با Loop Over Items به API درخواست ارسال کرد؟

بله. می‌توانید نود HTTP Request را در مسیر Loop قرار دهید تا داده‌ها در دسته‌های مشخص پردازش شوند. با این حال، محدودیت نرخ درخواست API باید جداگانه بررسی شود.

خروجی Loop و Done چه تفاوتی دارند؟

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

آیا برای پردازش یک فهرست ساده از محصولات به حلقه نیاز دارم؟

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

چگونه از اجرای بی‌پایان حلقه جلوگیری کنم؟

اتصالات حلقه را دقیق بررسی کنید، خروجی پردازش را به ورودی صحیح برگردانید، مسیر Done را برای مرحله نهایی نگه دارید و ابتدا Workflow را با چند آیتم آزمایش کنید.

جمع‌بندی

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

با این حال، همه Workflowها به حلقه نیاز ندارند. بسیاری از نودهای n8n به‌صورت پیش‌فرض با چند آیتم کار می‌کنند؛ بنابراین بهتر است Loop Over Items را زمانی به کار ببرید که کنترل دسته‌ها یا جریان اجرای مرحله‌ای واقعاً ضروری باشد.

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

در مقاله بعدی، سراغ Code Node در n8n می‌رویم تا یاد بگیریم چگونه با JavaScript داده‌ها را پردازش کنیم و منطق سفارشی خود را در Workflow پیاده‌سازی کنیم.