Loop Over Items في n8n للمبتدئين: التكرار وBatching وتجنب Rate Limits

آخر تحديث: 12 سبتمبر 2026.

عندما يبدأ المبتدئ في n8n ويستقبل عشرات الصفوف من Google Sheets أو قائمة عملاء من API، يظهر سؤال طبيعي: هل أحتاج إلى Loop حتى أعالج كل عنصر؟ في كثير من الحالات لا؛ معظم Nodes في n8n تتعامل مع عدة Items تلقائيًا. لكنك تحتاج إلى Loop Over Items عندما تريد التحكم في حجم الدُفعات، معالجة العناصر بالتتابع، إضافة انتظار بين الطلبات، أو تقليل احتمالات تجاوز حدود API.

الجواب المختصر: متى أستخدم Loop Over Items في n8n؟

استخدم Loop Over Items عندما تحتاج إلى تقسيم البيانات إلى دفعات Batches والتحكم في تنفيذ كل دفعة قبل الانتقال إلى التالية. أما إذا كانت Node التالية تستطيع معالجة كل Items تلقائيًا ولا توجد قيود Rate Limit أو ترتيب خاص، فغالبًا لا تحتاج إلى Loop صريح أصلًا.

قاعدة عملية: لا تضف Loop لمجرد وجود أكثر من Item. أضفه فقط عندما تحتاج تحكمًا إضافيًا في التدفق أو السرعة أو حجم المعالجة.

ما المقصود بـItem في n8n؟

n8n يمرر البيانات بين الـNodes على شكل مجموعة من العناصر تسمى Items. كل Item يحتوي عادةً بيانات JSON خاصة بسجل واحد أو كيان واحد. إذا قرأت 100 صف من Google Sheets، فقد تحصل على 100 Item. وإذا استقبلت قائمة عملاء من API، فقد تحتاج أولًا إلى تحويل القائمة إلى Items منفصلة قبل معالجتها.

لفهم بنية البيانات قبل بناء Loop، راجع دليل Expressions وJSON في n8n، لأنه يوضح كيف تقرأ الحقول والمصفوفات وتتبع مصدر البيانات بين العقد.

هل n8n يكرر التنفيذ تلقائيًا على كل Item؟

نعم، في عدد كبير من Nodes يكون التعامل مع عدة Items جزءًا طبيعيًا من طريقة عمل n8n. لذلك قد تمرر 20 Item إلى Node لاحقة وتجد أنها تتعامل معها دون أن تبني حلقة يدويًا.

لهذا السبب يقع بعض المبتدئين في خطأ إضافة Loop Over Items إلى كل Workflow تقريبًا. النتيجة تكون Workflow أطول وأكثر تعقيدًا بلا فائدة حقيقية.

ابدأ دائمًا بالسؤال التالي: هل أحتاج إلى التحكم في كيفية مرور العناصر، أم يكفيني السلوك الافتراضي؟

ما هي Loop Over Items؟

Loop Over Items هي Node مصممة لمعالجة مجموعة من العناصر على دفعات. كانت تُعرف في إصدارات سابقة باسم Split In Batches، لذلك قد تجد شروحات قديمة تستخدم الاسم السابق.

الفكرة الأساسية بسيطة:

1. تستقبل Node مجموعة Items.
2. تحدد Batch Size.
3. ترسل الدفعة الحالية عبر مسار Loop.
4. تنفذ Nodes التي تريدها على هذه الدفعة.
5. تعود الدورة لمعالجة الدفعة التالية.
6. بعد انتهاء جميع العناصر تخرج النتيجة من مسار Done.

ما معنى Batch Size؟

Batch Size هو عدد العناصر التي تمر في كل دورة.

Batch Size	السلوك	متى يفيد؟
1	عنصر واحد في كل دورة	عندما تحتاج تنفيذًا متتابعًا أو تأخيرًا بين الطلبات
5	5 عناصر في كل دورة	توازن بين السرعة وتقليل الضغط على API
20+	دفعات أكبر	عندما تكون الخدمة تتحمل الحمل وتريد تقليل عدد الدورات

لا يوجد رقم سحري يناسب الجميع. الرقم الصحيح يعتمد على حدود الخدمة الخارجية، حجم البيانات، ووقت التنفيذ.

مثال عملي: إرسال بيانات 50 عميلًا إلى API

افترض أن Google Sheets أعادت 50 عميلًا، وتريد إرسال بياناتهم إلى API خارجي. إذا كانت الخدمة تسمح بعدد محدود من الطلبات خلال فترة قصيرة، فقد يؤدي إرسال كل الطلبات سريعًا إلى استجابات مثل 429 Too Many Requests.

يمكنك بناء التدفق كالتالي:

Google Sheets
   ↓
Loop Over Items (Batch Size = 1)
   ↓
HTTP Request
   ↓
Wait
   ↘ العودة إلى Loop Over Items

بهذه البنية يمر كل عميل على HTTP Request، ثم ينتظر Workflow فترة محددة قبل معالجة العميل التالي.

إذا لم تكن مرتاحًا بعد مع إعداد الطلبات الخارجية، اقرأ أولًا دليل HTTP Request في n8n للمبتدئين.

كيف تساعد Loop Over Items في تجنب Rate Limits؟

Rate Limit هو حد تفرضه خدمة خارجية على عدد الطلبات خلال ثانية أو دقيقة أو ساعة. تجاوز هذا الحد قد يؤدي إلى رفض مؤقت للطلبات.

Loop Over Items تساعدك بطريقتين:

• تقليل حجم الدفعة: بدل إرسال عشرات العناصر مرة واحدة، ترسل عددًا صغيرًا في كل دورة.
• إضافة Wait: يمكنك إدخال فترة انتظار بين الدورات حتى لا تتجاوز الحد.

لكن لا تعتمد على التخمين. راجع وثائق الـAPI التي تتعامل معها لتعرف حدودها الفعلية، ثم اضبط Batch Size والانتظار بناءً عليها.

مثال: Batch Size = 5 بدل 1

ليس من الضروري معالجة عنصر واحد في كل دورة. إذا كانت الخدمة تسمح بخمس عمليات متتالية بأمان، يمكنك استخدام Batch Size يساوي 5.

إذا كان لديك 50 Item، فسيتم تقسيمها نظريًا إلى 10 دفعات. هذا قد يكون أسرع بكثير من معالجة عنصر واحد في كل مرة، مع بقاء التحكم أفضل من دفع كل البيانات دفعة واحدة.

Loop Over Items أم Split Out؟

هاتان الفكرتان مختلفتان:

• Split Out: تستخدمها عندما يكون لديك Array داخل Item واحدة وتريد تحويل عناصرها إلى Items مستقلة.
• Loop Over Items: تستخدمها عندما أصبحت لديك Items متعددة وتريد التحكم في كيفية معالجتها على دفعات.

مثال: API يعيد Item واحدة فيها Array تحتوي 100 منتج. قد تحتاج أولًا إلى Split Out لإنتاج 100 Item، ثم Loop Over Items إذا أردت معالجة المنتجات على دفعات.

هل أحتاج Loop لمعالجة كل صف من Google Sheets؟

غالبًا لا. إذا أعادت Google Sheets عدة Items وكانت Node التالية تتعامل طبيعيًا مع عدة Items، فقد يعمل Workflow بدون Loop Over Items.

أضف Loop فقط إذا احتجت ترتيبًا محددًا، Wait بين العمليات، Batch Size، أو حماية من قيود خدمة خارجية.

ما الفرق بين Loop وPagination؟

الـLoop يتعامل مع Items أصبحت موجودة بالفعل داخل Workflow. أما Pagination فتتعامل مع API يقسم النتائج إلى صفحات، مثل 100 نتيجة في كل طلب.

في هذه الحالة تحتاج إلى إعداد Pagination وفق إمكانيات HTTP Request أو منطق الخدمة نفسها حتى تجلب كل الصفحات أولًا أو تدريجيًا. بعد ذلك قد تحتاج إلى batching لمعالجة النتائج دون ضغط زائد.

لا تخلط بين المشكلتين: جلب جميع صفحات API شيء، ومعالجة Items الناتجة على دفعات شيء آخر.

Loop Over Items مع Webhook

قد يستقبل Webhook في n8n طلبًا يحتوي Array من الطلبات أو العملاء أو المنتجات. إذا كانت البيانات كلها داخل Array واحدة، افحص Output أولًا. قد تحتاج Split Out قبل Loop Over Items.

ثم يمكنك تمرير كل Item إلى CRM أو Google Sheets أو API خارجي، مع التحكم في Batch Size.

كيف تتعامل مع الأخطاء داخل Loop؟

وجود Loop لا يعني أن Workflow أصبح مقاومًا للأخطاء. إذا فشل HTTP Request بسبب Timeout أو 429 أو خطأ في البيانات، يجب أن تقرر ماذا يحدث:

• هل تعيد المحاولة؟
• هل تتجاوز العنصر وتكمل؟
• هل توقف Workflow بالكامل؟
• هل ترسل العنصر الفاشل إلى مسار مراجعة؟

لهذا من المهم ربط منطق Loop باستراتيجية واضحة للأخطاء. راجع دليل Retry on Fail وError Workflow في n8n لفهم الجزء المكمل.

مثال عملي: تحديث CRM مع انتظار بين السجلات

لنفترض أن لديك 30 Lead جديدة وتريد إرسالها إلى CRM:

1. Google Sheets تجلب 30 صفًا.
2. Loop Over Items تستقبل 30 Item.
3. Batch Size = 1.
4. HTTP Request يرسل بيانات الـLead إلى CRM.
5. Wait تنتظر ثانية واحدة.
6. التدفق يعود إلى Loop لمعالجة العنصر التالي.
7. بعد انتهاء الـ30 Item ينتقل التنفيذ إلى Done.

هذه البنية سهلة الفهم والصيانة، وتسمح لك لاحقًا بإضافة Logging أو Retry أو إشعار بالعناصر الفاشلة.

5 أخطاء شائعة مع Loop Over Items

1. استخدام Loop بدون حاجة: كثير من Nodes تتعامل مع Items متعددة تلقائيًا.
2. نسيان العودة إلى Loop: إذا لم يكتمل مسار الدورة بشكل صحيح قد لا تتم معالجة بقية العناصر كما تتوقع.
3. اختيار Batch Size عشوائي: يجب أن يتناسب مع الخدمة الخارجية وحجم البيانات.
4. استخدام Loop لحل مشكلة Array: قد تكون المشكلة الحقيقية أنك تحتاج Split Out.
5. تجاهل الأخطاء: عنصر واحد سيئ قد يفسد النتيجة أو يوقف المسار إذا لم تضع استراتيجية واضحة.

متى لا تستخدم Loop Over Items؟

لا تستخدمها فقط لأن لديك قائمة بيانات. تجنبها عندما:

• Node التالية تتعامل مع كل Items تلقائيًا دون مشكلة.
• لا توجد قيود Rate Limit أو ترتيب تنفيذ.
• إضافة Loop ستجعل Workflow أبطأ دون فائدة.
• المشكلة أصلًا Array تحتاج Split Out وليست batching.

Checklist قبل إضافة Loop إلى Workflow

• هل البيانات الحالية Item واحدة أم عدة Items؟
• هل توجد Array يجب تقسيمها أولًا؟
• هل Node التالية تعالج Items تلقائيًا؟
• هل API لديها Rate Limit موثق؟
• هل أحتاج تنفيذًا متتابعًا أم يمكن المعالجة دفعة واحدة؟
• ما Batch Size المناسب؟
• هل أحتاج Wait بين الدورات؟
• ماذا سيحدث إذا فشل Item واحد؟
• هل أحتاج Retry أو Error Workflow؟

أسئلة شائعة عن Loop Over Items في n8n

هل Loop Over Items هي نفسها Split In Batches؟

نعم من حيث الأصل الوظيفي؛ ستجد الاسم القديم Split In Batches في كثير من الشروحات والقوالب، بينما الاسم المستخدم حاليًا هو Loop Over Items.

هل أضع Batch Size = 1 دائمًا؟

لا. استخدم 1 عندما تحتاج معالجة متتابعة أو تريد انتظارًا بين العناصر. استخدم دفعات أكبر عندما تسمح الخدمة بذلك وتريد أداءً أسرع.

هل Loop Over Items تمنع خطأ 429 تلقائيًا؟

لا. هي تمنحك التحكم في حجم الدفعات، لكنك تحتاج إلى ضبط Batch Size وWait بما يتوافق مع Rate Limit الفعلي للخدمة الخارجية.

لماذا لدي Array واحدة بدل عدة Items؟

لأن مصدر البيانات قد أعاد قائمة داخل حقل واحد. في هذه الحالة افحص JSON وقد تحتاج إلى Split Out لتحويل عناصر Array إلى Items مستقلة.

هل Loop مطلوبة مع HTTP Request؟

ليس دائمًا. إذا كان لديك Items متعددة وHTTP Request يستطيع العمل عليها دون تجاوز حدود الخدمة، قد لا تحتاج Loop. تصبح مفيدة عندما تريد ضبط السرعة أو الدفعات أو التسلسل.

الخلاصة

أهم فكرة للمبتدئ هي أن n8n لا يحتاج Loop يدويًا لكل قائمة بيانات. معظم العمل يبدأ بفهم Items وبنية JSON، ثم تضيف Loop Over Items فقط عندما تحتاج تحكمًا فعليًا في batching أو السرعة أو التسلسل.

إذا كنت تبني أساسك في n8n، ابدأ من دليل n8n للمبتدئين، ثم راجع Expressions وJSON وHTTP Request. وبعد فهم الـLoop، أكمل بدليل معالجة الأخطاء لتبني Workflows أكثر استقرارًا وقابلية للصيانة.

مصادر رسمية مفيدة: توثيق n8n حول Looping وLoop Over Items (Split in Batches).