مسار n8n — الجزء 2: التكامل مع APIs الخارجية

الارتقاء بمستوى الأتمتة: ما بعد الأساسيات

في الجزء الأول، تعلمنا أساسيات إرسال الطلبات والمصادقة في n8n. في هذا الجزء الثاني، سنغوص في سيناريوهات التكامل المتقدمة (Advanced API Integrations) التي تواجه المطورين وفرق التقنية في المؤسسات، مثل معالجة البيانات المعقدة الواردة من واجهات الـ API، والتعامل مع الـ Webhooks لإنشاء تفاعلات لحظية.

استقبال البيانات اللحظية (Webhooks)

بدلاً من إرسال طلبات متكررة (Polling) كل 10 دقائق للتأكد من وجود بيانات جديدة (مما يستهلك موارد الخادم)، تعتمد الأنظمة الحديثة على الـ Webhooks.

• قم بإضافة عقدة Webhook كأول عقدة في مسار n8n.
• حدد طريقة الاستقبال (عادة POST).
• سيولد n8n رابطين: رابط للاختبار (Test URL) ورابط للإنتاج (Production URL).
• انسخ رابط الإنتاج وضعه في النظام الخارجي (مثلاً: نظام الدفع عند إتمام معاملة، أو GitHub عند عمل Commit جديد).
• بمجرد حدوث الفعل في النظام الخارجي، سيرسل البيانات اللحظية إلى n8n، لتبدأ دورة العمل فوراً.

تنسيق البيانات المعقدة (Data Transformation)

عندما تستقبل بيانات من API خارجي، غالباً ما تكون بصيغة JSON متشعبة ومكدسة لا تتناسب مع النظام الذي تود إرسال البيانات إليه. هنا يأتي دور عقدة Item Lists وعقدة Code.

فك المصفوفات (Splitting Arrays)

إذا أرجعت الـ API مصفوفة (Array) تحتوي على 100 عنصر (مثلاً قائمة متبرعين)، لا يمكنك إرسالها ككتلة واحدة إلى نظام البريد الإلكتروني. استخدم عقدة Item Lists واختر Split Out Items. هذا سيحول المصفوفة الفردية إلى 100 عنصر منفصل، ليعمل المسار (Workflow) على كل عنصر بشكل مستقل.

تطويع البيانات باستخدام JavaScript

إذا كانت الـ API تعيد تواريخ بصيغة غير مفهومة (مثل Unix Timestamp) أو أسماء غير مرتبة، أضف عقدة Code واكتب سكربت JS بسيطاً لمعالجتها. مثال:

for (const item of $input.all()) {
  // تحويل التاريخ
  item.json.formattedDate = new Date(item.json.timestamp * 1000).toISOString();
  // دمج الاسم الأول والأخير
  item.json.fullName = `${item.json.firstName} ${item.json.lastName}`;
}
return $input.all();

إدارة حدود الـ API (Rate Limiting Management)

إذا كنت قد قسمت مصفوفة إلى 100 عنصر، وحاولت إرسالها دفعة واحدة إلى واجهة API خارجية (عبر عقدة HTTP Request أخرى)، فغالباً سيتم حظرك مؤقتاً بسبب تخطي الحد المسموح للطلبات (Rate Limit).

لتجنب ذلك، استخدم عقدة Split In Batches (أو خيار التحزيم في الإصدارات الأحدث). يمكنك تكوينها لتأخذ 10 عناصر فقط، تقوم بمعالجتها، ثم استخدام عقدة Wait للانتظار 5 ثوانٍ قبل معالجة الحزمة التالية. هذا التصميم يضمن تدفق البيانات بسلاسة ودون التسبب في حظر الخادم.

الخلاصة

التكامل المتقدم مع الأنظمة الخارجية عبر n8n يتطلب التفكير كمهندس بيانات. من خلال الجمع بين الـ Webhooks للاستجابة اللحظية، والمعالجة الدقيقة للبيانات الواردة عبر الـ Code Node، واحترام حدود خوادم الـ APIs باستخدام التحزيم (Batching)، يمكنك بناء مسارات أتمتة مؤسسية شديدة التعقيد تعمل بثبات واستقرار تام.