Code Node في n8n للمبتدئين: أمثلة JavaScript لتحويل JSON والتحقق من البيانات

آخر مراجعة تحريرية: 10 أكتوبر 2026. عندما تبدأ باستخدام n8n ستكتشف أن معظم المهام يمكن إنجازها دون كتابة كود. لكن ماذا لو أردت تنظيف أسماء العملاء، توحيد البريد الإلكتروني، حساب قيمة فاتورة، أو معالجة قائمة عناصر دفعة واحدة؟ هنا تأتي Code Node في n8n كأداة محددة الغرض، وليست بديلًا عن كل Nodes الأخرى.

الجواب المختصر: استخدم Code Node عندما لا تكفي Expressions أو Edit Fields للتحويل المطلوب. اختر بين Run Once for Each Item لمعالجة كل عنصر منفصلًا، وRun Once for All Items لمعالجة القائمة كلها. الأهم أن تُرجع بيانات بالصيغة التي يفهمها n8n، وتختبر الحالات الناقصة قبل تشغيل Workflow تلقائيًا.

متى تحتاج Code Node فعلًا؟

ابدأ من دليل n8n للمبتدئين إذا كانت مفاهيم Trigger وExecution جديدة عليك. ثم استخدم هذه القاعدة:

المهمة	الخيار الأبسط
نسخ حقل أو دمج نصين	Expression أو Edit Fields
توجيه المسار حسب شرط	IF أو Switch
تكرار عناصر مع مراعاة حدود API	Loop Over Items
تطبيع بيانات متعددة بقواعد مخصصة	Code Node
استدعاء API خارجي	HTTP Request، لا تضع الطلب في Code Node

إذا لم تفهم بعد $json والمصفوفات، راجع Expressions وJSON في n8n قبل متابعة الأمثلة.

ما الفرق بين وضعي تشغيل Code Node؟

Run Once for Each Item

ينفذ الكود مرة لكل عنصر وارد. مناسب لتنظيف اسم أو حساب مبلغ أو إضافة حقل جديد إلى كل سجل. في هذا الوضع يمكنك قراءة $json وإرجاع عنصر واحد بالشكل { json: {...} }.

Run Once for All Items

ينفذ الكود مرة واحدة لكل مجموعة العناصر الواردة. استخدم $input.all() للوصول إلى القائمة. في هذا الوضع أرجع مصفوفة عناصر؛ وعندما تحتفظ بعلاقة واحد لواحد بين المدخلات والمخرجات، أضف pairedItem لتسهيل تتبع مصدر كل عنصر في الخطوات اللاحقة.

تجربة 1: تنظيف بيانات عميل — لكل عنصر

الهدف: بعد Webhook أو Google Sheets، يصل سجل يحوي name وemail. نريد إزالة المسافات وتوحيد حالة البريد وتسجيل ما إذا كان الحقلان صالحين مبدئيًا. هذه عملية تنظيف بسيطة، وليست تحققًا نهائيًا من ملكية البريد.

1. أنشئ Workflow تجريبيًا يبدأ بـManual Trigger.
2. أضف Edit Fields وأدخل قيمتي name وemail تجريبيتين.
3. أضف Code Node واختر JavaScript ثم Run Once for Each Item.
4. الصق الكود التالي وشغّل العقدة.

const name = String($json.name ?? '').trim();
const email = String($json.email ?? '').trim().toLowerCase();
return {
  json: {
    ...$json,
    name,
    email,
    validForReview: name.length > 0 && email.includes('@')
  }
};

إذا كانت البيانات {"name":" Sara ","email":" SARA@EXAMPLE.COM "}، فستحصل على اسم دون فراغات وبريد بحروف صغيرة. لا تستخدم includes('@') وحده بوصفه فحصًا قانونيًا أو أمنيًا لصحة البريد؛ إنه فحص أولي لغرض المثال.

تجربة 2: حساب قيمة طلب — لكل عنصر

افترض أن كل Item يمثل طلبًا به quantity وunitPrice. نريد حساب الإجمالي وتحديد السجلات غير الصالحة بدل السماح لقيمة NaN بالمرور.

const quantity = Number($json.quantity);
const unitPrice = Number($json.unitPrice);
const valid = Number.isFinite(quantity)
  && Number.isFinite(unitPrice)
  && quantity >= 0
  && unitPrice >= 0;
return {
  json: {
    ...$json,
    valid,
    total: valid ? Math.round(quantity * unitPrice * 100) / 100 : null
  }
};

هذا مثال توضيحي للبيانات البسيطة؛ أنظمة الفوترة الحقيقية تحتاج قواعد إضافية للعملات والضرائب والتقريب. بعد Code Node يمكنك استخدام IF أو Switch لإرسال السجلات غير الصالحة إلى مراجعة بشرية.

تجربة 3: معالجة قائمة كاملة مع الحفاظ على الربط

إذا كانت لديك عشرة سجلات وتريد إضافة ترتيب متسلسل إلى كل سجل، استخدم Run Once for All Items:

const items = $input.all();
return items.map((item, index) => ({
  json: {
    ...item.json,
    rowNumber: index + 1
  },
  pairedItem: { item: index }
}));

إضافة pairedItem هنا تساعد العقد التالية على معرفة أي مدخل أنتج كل مخرج. إذا غيّرت عدد العناصر أو جمّعت عدة مدخلات في عنصر واحد، راجع توثيق Item Linking لأن الربط قد يحتاج معالجة مختلفة. جرّب ثلاثة سجلات على الأقل، ثم افحص Output لكل سجل.

مثال عملي متكامل: نموذج عميل → تنظيف → Sheets → Telegram

هذا تطبيق يجمع دروس الموقع الحالية في مشروع واحد دون تعقيد غير ضروري:

1. Webhook: يستقبل طلب الاستشارة من نموذج تجريبي. راجع شرح Webhook.
2. Code Node: ينظف الاسم والبريد ويضيف validForReview.
3. IF: إذا كانت البيانات الأساسية ناقصة، يُرسل السجل إلى مسار مراجعة بدل إضافته تلقائيًا.
4. Google Sheets: يضيف السجلات المقبولة إلى جدول المتابعة؛ راجع ربط Google Sheets مع n8n.
5. Telegram: يرسل إشعارًا مختصرًا دون كشف بيانات حساسة في قناة عامة؛ راجع ربط Telegram مع n8n.
6. Error Workflow: يبلّغ عن فشل الخطوات المهمة وفق دليل التعامل مع الأخطاء.

تنبيه: منع التكرار لا يتحقق تلقائيًا بمجرد استخدام Code Node. إذا كان Webhook قد يُستدعى مرتين، أنشئ معرّف طلب ثابتًا وتحقق من وجوده في التخزين قبل إضافة صف أو إرسال إشعار جديد. اختبر أيضًا فشل Sheets بعد نجاح خطوة سابقة.

أخطاء Code Node الشائعة وكيف تحلها

العرض	السبب المحتمل	الإجراء
الـNode لا تعيد Items متوقعة	إرجاع Object في وضع All Items بدل Array	أرجع مصفوفة من عناصر لها خاصية json
قيمة undefined	اسم حقل غير موجود أو بنية JSON مختلفة	افحص Input واستخدم ?? للقيم الاختيارية
ربط بيانات من Node سابقة يفشل	فقدان item linking بعد تحويل عناصر	راجع pairedItem والربط في العقد اللاحقة
NaN في حساب	نص أو قيمة مفقودة داخل حقل رقمي	استخدم Number.isFinite وتحقق من المدخلات
محاولة HTTP داخل الكود	استخدام Code Node بدل عقدة مخصصة	استخدم HTTP Request وCredentials

الأمان والخصوصية عند استخدام JavaScript في n8n

• لا تكتب مفاتيح API أو كلمات المرور داخل الكود؛ استخدم Credentials وOAuth والعقد المصممة للاتصال بالخدمات.
• لا تطبع بيانات العملاء الحساسة في السجلات بغرض التشخيص.
• اختبر الكود على بيانات وهمية قبل إدخاله في Workflow يعمل على حسابات حقيقية.
• ضع حدودًا لحجم البيانات عند معالجة آلاف العناصر؛ قد تكون Nodes المخصصة أو تقسيم الدفعات أكثر أمانًا.
• إذا كانت الأتمتة تعمل وفق جدول، راجع Schedule Trigger لتجنب التشغيل المتكرر غير المقصود.

قائمة اختبار قبل تفعيل Workflow

1. اختبر عنصرًا صحيحًا، وآخر ينقصه البريد، وثالثًا يحوي أرقامًا غير صالحة.
2. تأكد أن كل مخرج يحتوي json وأن عدد العناصر صحيح.
3. افحص ربط العناصر عند الرجوع إلى بيانات Nodes سابقة.
4. تأكد من عدم تكرار السجل أو الإشعار عند إعادة التشغيل.
5. راجع مسار الخطأ والخصوصية والصلاحيات قبل التفعيل.

الأسئلة الشائعة

هل أحتاج Code Node لتعلم n8n؟

لا. ابدأ بـTrigger وEdit Fields وIF وHTTP Request، ثم استخدم الكود عندما تكون هناك حاجة فعلية لتحويلات مخصصة.

هل يمكن تنفيذ طلب API من داخل Code Node؟

النهج الموصى به في n8n هو استخدام HTTP Request للاتصالات الخارجية، مع نظام Credentials بدل تضمين الأسرار في الكود.

لماذا تختفي بيانات العناصر في الخطوات التالية؟

قد تكون أرجعت بنية غير صحيحة أو فقدت الربط بين المدخلات والمخرجات. افحص Output وراجع pairedItem إذا استخدمت وضع All Items.

مصادر رسمية لمراجعة التفاصيل

• توثيق Code Node الرسمي.
• أمثلة Code Node الرسمية.
• شرح ربط العناصر في n8n.

ملاحظة تحريرية: تختلف بعض تفاصيل واجهة n8n باختلاف الإصدار وبيئة Cloud أو Self-hosted؛ راجع التوثيق الرسمي عند التنفيذ. الأمثلة للتعلّم ولا تتضمن بيانات عملاء حقيقية.