Expressions وJSON في n8n للمبتدئين: كيف تقرأ البيانات وتربط الحقول بدون أخطاء

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

إذا بدأت استخدام n8n فستصل سريعًا إلى لحظة ترى فيها بيانات بصيغة JSON، وتحتاج أن تنقل قيمة من Node إلى أخرى باستخدام Expression مثل {{ $json.email }}. هنا يبدأ الجزء الذي يربك كثيرًا من المبتدئين. الفكرة أبسط مما تبدو: JSON هو شكل البيانات، وExpression هي الطريقة التي تشير بها إلى قيمة داخل هذه البيانات أو تحوّلها قبل تمريرها للخطوة التالية.

في هذا الدليل ستتعلم كيف تقرأ بنية JSON في n8n، وكيف تستخدم Expressions بأمان، وما الفرق بين $json والإشارة إلى Node بالاسم، وكيف تتعامل مع الحقول المتداخلة والمصفوفات والقيم المفقودة، مع أمثلة مرتبطة بواجهات API وHTTP Request.

الجواب المختصر: ما هي Expressions وJSON في n8n؟

يعالج n8n البيانات بين الـNodes على هيئة عناصر Items، وكل Item يحتوي عادةً كائن JSON. أما Expression فهي تعبير ديناميكي يُكتب داخل {{ ... }} لقراءة قيمة من البيانات أو تكوين قيمة جديدة. مثال: إذا كانت البيانات تحتوي على {"name":"Ahmed"} فيمكن استخدام {{ $json.name }} للحصول على القيمة Ahmed.

أولًا: ما المقصود بـJSON داخل n8n؟

JSON اختصار لـJavaScript Object Notation، وهو تنسيق نصي منظم تستخدمه تطبيقات وواجهات API لتبادل البيانات. لا تحتاج أن تصبح مبرمج JavaScript حتى تستخدمه في n8n، لكن عليك فهم ثلاثة أشكال أساسية:

• الحقل البسيط: اسم وقيمة، مثل "email": "user@example.com".
• الكائن المتداخل: حقل يحتوي مجموعة حقول أخرى، مثل "customer": {"name":"Ahmed","city":"Cairo"}.
• المصفوفة Array: قائمة قيم أو كائنات، مثل "items": [{"product":"A"},{"product":"B"}].

عندما تستقبل استجابة من API عبر عقدة HTTP Request، غالبًا ستجد نتيجة مشابهة لهذا المثال:

{
  "customer": {
    "name": "Ahmed",
    "email": "ahmed@example.com"
  },
  "status": "paid",
  "total": 120,
  "items": [
    {"name": "Service A", "price": 70},
    {"name": "Service B", "price": 50}
  ]
}

قبل أن تحاول كتابة أي Expression، افتح Output للعقدة السابقة واقرأ هذه البنية. هذه الخطوة وحدها تمنع نسبة كبيرة من أخطاء المسارات.

ثانيًا: ما هي Expression في n8n؟

Expression هي طريقة إدخال قيمة ديناميكية بدل كتابة نص ثابت. في أي حقل يدعم Expression يمكنك قراءة بيانات التنفيذ الحالي، أو بيانات Node سابقة، أو تنفيذ عمليات بسيطة على النصوص والأرقام والتواريخ.

الصيغة الأساسية تكون داخل قوسين مزدوجين:

{{ $json.fieldName }}

إذا كان لديك الحقل total بالقيمة 120، فإن:

{{ $json.total }}

تعيد القيمة 120.

كيف تقرأ حقلًا متداخلًا داخل JSON؟

إذا كانت القيمة داخل كائن فرعي، تتبع المسار نقطة بعد نقطة. في المثال السابق اسم العميل موجود داخل customer، لذلك نستخدم:

{{ $json.customer.name }}

والبريد الإلكتروني:

{{ $json.customer.email }}

أما إذا كان اسم الحقل يحتوي مسافة أو شرطة أو رموزًا غير مناسبة لصيغة النقطة، فاستخدم الأقواس:

{{ $json["customer name"] }}

كيف تقرأ قيمة من Array؟

المصفوفة تبدأ فهارسها من الصفر. إذا كان لديك:

"items": [
  {"name":"Service A"},
  {"name":"Service B"}
]

فإن أول عنصر هو:

{{ $json.items[0].name }}

والثاني:

{{ $json.items[1].name }}

لكن إذا كان عدد العناصر يتغير من تنفيذ إلى آخر، لا تعتمد على رقم ثابت إلا إذا كان منطق الـWorkflow يضمن ذلك. في الحالات المتغيرة استخدم Nodes المخصصة للتعامل مع القوائم أو Code Node عند الحاجة. وإذا تحولت الـArray إلى Items متعددة وتحتاج إلى معالجتها على دفعات، راجع دليل Loop Over Items وBatching في n8n.

$json أم الإشارة إلى Node بالاسم؟

$json يشير عادةً إلى بيانات الـItem الحالي في السياق الذي تعمل فيه. هذا ممتاز عندما تكون العقدة السابقة مباشرة هي مصدر البيانات ولا توجد فروع معقدة.

لكن عندما تريد قراءة بيانات من Node محددة بوضوح، فالإشارة إلى اسمها تجعل المقصود أوضح. مثال:

{{ $('HTTP Request').item.json.customer.email }}

هذه الصيغة تقول بوضوح: اجلب البريد الإلكتروني من بيانات عقدة اسمها HTTP Request. هذا مفيد خصوصًا في Workflows التي تحتوي على IF أو Merge أو أكثر من مسار للبيانات.

قاعدة عملية: استخدم $json للبيانات الحالية البسيطة، واستخدم الإشارة باسم الـNode عندما تحتاج مصدرًا محددًا أو عندما يصبح الـWorkflow متشعبًا.

مثال عملي: نقل بريد عميل من API إلى Gmail

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

{
  "customer": {
    "name": "Mona",
    "email": "mona@example.com"
  },
  "plan": "Pro"
}

في Gmail Node يمكنك وضع حقل To كالتالي:

{{ $json.customer.email }}

وفي Subject:

مرحبًا {{ $json.customer.name }} — تم تفعيل خطة {{ $json.plan }}

بهذا أنت لا تنسخ البيانات يدويًا؛ كل تنفيذ يستخدم بيانات العميل الحالي تلقائيًا.

كيف تبني نصًا ديناميكيًا داخل Expression؟

يمكن دمج النص الثابت مع البيانات بسهولة. مثال:

{{ 'طلب جديد من ' + $json.customer.name }}

ويمكنك إجراء عملية حسابية بسيطة:

{{ $json.total * 1.14 }}

أو تحويل نص إلى أحرف صغيرة:

{{ $json.customer.email.toLowerCase() }}

الفائدة هنا ليست استعراض JavaScript، بل تنفيذ التحويل في المكان الذي تحتاجه دون إضافة Nodes لا ضرورة لها.

ماذا يحدث إذا كان الحقل غير موجود؟

من أكثر الأخطاء شيوعًا أن تتوقع وجود حقل في كل تنفيذ بينما API قد تحذفه عندما تكون قيمته فارغة. لذلك لا تفترض أن كل مسار موجود دائمًا.

يمكن استخدام optional chaining في حالات كثيرة لتجنب كسر القراءة:

{{ $json.customer?.email }}

ويمكن إضافة قيمة بديلة:

{{ $json.customer?.email || 'no-email' }}

لكن لا تستخدم قيمة افتراضية تخفي مشكلة مهمة. إذا كان البريد الإلكتروني مطلوبًا قبل إرسال رسالة، الأفضل أن تضيف IF للتحقق من وجوده، لا أن تمرر قيمة وهمية.

الفرق بين القيمة الفارغة والقيمة غير الموجودة

هذه نقطة صغيرة لكنها مهمة في الأتمتة:

• "email": "" يعني أن الحقل موجود لكن قيمته فارغة.
• عدم وجود email أصلًا يعني أن المفتاح غير موجود.
• "email": null يعني أن النظام أرسل الحقل لكن بلا قيمة فعلية.

قد تحتاج إلى التعامل مع الحالات الثلاث بشكل مختلف، خصوصًا قبل إدخال البيانات إلى CRM أو Sheets أو قاعدة بيانات.

Expressions مع Webhook: مثال واقعي

إذا كنت تستقبل Lead عبر Webhook في n8n وكانت البيانات المرسلة:

{
  "name": "Sara",
  "phone": "+201000000000",
  "source": "landing-page"
}

يمكنك تمرير الاسم إلى Google Sheets بـ:

{{ $json.name }}

والمصدر بـ:

{{ $json.source }}

ثم استخدام IF Node للتحقق من أن source يساوي landing-page قبل متابعة التنفيذ. هذا يجعل Workflow أكثر قابلية للفهم من وضع منطق طويل ومعقد داخل Expression واحدة.

5 أخطاء شائعة عند استخدام Expressions في n8n

1. كتابة اسم الحقل بالتخمين: افحص Output الفعلي للعقدة السابقة أولًا.
2. نسيان أن Array تبدأ من 0: العنصر الأول هو [0] وليس [1].
3. الاعتماد على $json بعد تغير سياق البيانات: في Workflows المتشعبة قد تحتاج إلى الإشارة إلى Node محددة بالاسم.
4. وضع منطق كبير جدًا داخل Expression: عندما يصبح التعبير صعب القراءة، استخدم Node مناسبة أو Code Node.
5. عدم اختبار القيم المفقودة: جرّب بيانات ناقصة أو فارغة قبل تشغيل Workflow في بيئة حقيقية.

كيف تختبر Expression قبل الاعتماد عليها؟

اعمل بهذه الخطوات:

1. شغّل الـNode التي تجلب البيانات.
2. افتح Output وتأكد من البنية الفعلية.
3. انتقل إلى الحقل المطلوب واختر وضع Expression.
4. اكتب المسار وشاهد Preview للقيمة.
5. اختبر أكثر من Item إذا كانت البيانات متعددة.
6. جرّب سيناريو بقيمة ناقصة أو فارغة.
7. بعد نجاح الاختبار فقط فعّل الـWorkflow للاستخدام الحقيقي.

Expressions أم Set/Edit Fields أم Code Node؟

الحالة	الأداة الأنسب غالبًا
قراءة حقل أو تعديل بسيط لقيمة واحدة	Expression
إعادة تسمية وتنظيم عدة حقول	Edit Fields / Set
شرط واضح لمسار التنفيذ	IF
تحويلات معقدة أو معالجة Array كبيرة	Code Node أو Nodes متخصصة
استخراج قيمة من استجابة API	Expression غالبًا

الهدف ليس تقليل عدد الـNodes بأي ثمن؛ الهدف أن يبقى Workflow مفهومًا ويمكن صيانته بعد شهر أو ستة أشهر.

كيف ترتبط Expressions بـHTTP Request وAPIs؟

عند العمل مع API، تستخدم Expressions في اتجاهين:

• قبل الطلب: لبناء URL أو Headers أو Query Parameters أو Body اعتمادًا على بيانات سابقة.
• بعد الطلب: لاستخراج قيم محددة من JSON الذي أعادته الـAPI.

مثلًا يمكن أن يكون جزء من URL ديناميكيًا:

https://api.example.com/customers/{{ $json.customer_id }}

ثم بعد وصول الاستجابة تستخرج حالة العميل:

{{ $json.status }}

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

متى تتحول Expression إلى مصدر أخطاء؟

Expression تصبح خطرة عندما تعتمد على افتراضات غير مختبرة: اسم Node تغير، بنية API تغيرت، الحقل أصبح اختياريًا، أو Array أصبحت فارغة. لذلك عند بناء Workflow لعميل أو عمل إنتاجي، أضف تحققًا من المدخلات ومسارًا واضحًا للأخطاء.

لدينا دليل مستقل يشرح Retry on Fail وError Workflow في n8n، وهو الخطوة التالية المنطقية بعد فهم التعامل مع البيانات.

Checklist سريعة قبل حفظ أي Expression

• هل قرأت Output الحقيقي بدل تخمين بنية JSON؟
• هل المسار يعمل على أكثر من Item؟
• هل الحقل قد يكون null أو غير موجود؟
• هل تحتاج فعلًا $json أم مرجعًا مباشرًا إلى Node أخرى؟
• هل التعبير بسيط وقابل للفهم؟
• هل هناك IF أو Validation مطلوب قبل تنفيذ إجراء حساس؟
• هل اختبرت سيناريو الفشل؟

أسئلة شائعة عن Expressions وJSON في n8n

هل يجب أن أتعلم JavaScript لاستخدام Expressions؟

لا. تستطيع تنفيذ معظم Workflows الأساسية بمعرفة مسارات JSON وبعض العمليات البسيطة. تعلم JavaScript يصبح مفيدًا تدريجيًا عندما تحتاج تحويلات أكثر تعقيدًا.

ما معنى $json في n8n؟

هو مرجع إلى بيانات JSON للـItem الحالي في السياق الذي تعمل فيه. تستخدم بعده اسم الحقل للوصول إلى قيمة مثل {{ $json.email }}.

كيف أعرف المسار الصحيح لحقل داخل JSON؟

شغّل العقدة السابقة وافتح Output، ثم اتبع تداخل الحقول كما يظهر فعليًا. إذا كان البريد داخل customer فالمسار يكون عادةً $json.customer.email.

لماذا تعمل Expression في اختبار وتفشل لاحقًا؟

غالبًا لأن البيانات الحقيقية تحتوي حالات لم تظهر في الاختبار: حقل مفقود، Array فارغة، أكثر من Item، أو مسار Workflow مختلف. اختبر أكثر من سيناريو وأضف Validation.

هل أستخدم Expression لكل شيء؟

لا. استخدمها للقراءة والتحويلات القصيرة. للمنطق الكبير استخدم IF أو Edit Fields أو Code Node بحيث يبقى الـWorkflow واضحًا وقابلًا للصيانة.

الخلاصة

لفهم n8n جيدًا، لا تحتاج حفظ عشرات الصيغ. ركز على ثلاثة أشياء: اقرأ JSON كما هو، حدد مصدر البيانات بدقة، واجعل Expression قصيرة وواضحة. بعد ذلك ستصبح عملية ربط Webhooks وAPIs وGoogle Sheets وGmail وغيرها أكثر مباشرة بكثير.

إذا كنت ما زلت في البداية، ارجع إلى دليل n8n للمبتدئين. وإذا وصلت بالفعل إلى مرحلة APIs، انتقل إلى دليل HTTP Request ثم أكمل بدليل معالجة الأخطاء في n8n. بهذه الثلاثة مع هذا الدليل يصبح لديك أساس عملي متماسك لبناء Workflows حقيقية بدل نسخ قوالب لا تفهم بياناتها.