التعبيرات في n8n: $json و$now ولماذا $node غير موجود — دليل $

التعبير في n8n هو قطعة JavaScript صغيرة تُكتب داخل حقل في العقدة نفسها. وسؤال «كيف أستخرج قيمة من عقدة سابقة؟» له جواب واحد قصير: $('اسم العقدة'). لكن قبل أن نصل إليه هناك عادة واحدة تُحمل معك من أدوات أخرى، وهي التي تُعطّل نصف من يبدأون.

⚠️ قبل أن تبدأ

• $node غير موجودة في n8n. الصحيح $('Node Name'). الشرح في القسم الأول.
• المنطقة الزمنية الافتراضية EDT (نيويورك). لا يرفع خطأً ولا تحذيراً، بل يُنتج تواريخ خاطئة — والقسم الرابع.
• التعبيرات تُقيَّم في حقول بيانات الاعتماد أيضاً، وتُقيَّم من جديد في كل تشغيلة. لا تضع مفتاحاً ثابتاً داخل نص تعبير — والقسم السابع.

ما الذي يجب أن تصحّحه قبل أن تكتب تعبيراً واحداً؟

اكتب {{ $node["Gmail"].email }} ولن تجد $node في أي مكان: صفحة مرجع المتغيّرات في n8n لا تُدرجها أصلاً. وهذه قائمة المتغيّرات الجذرية كاملة كما تنشرها n8n:

$(), $binary, $execution, $fromAI(), $if(), $ifEmpty(), $input,
$itemIndex, $jmespath(), $json, $max(), $min(), $nodeVersion,
$now, $pageCount, $parameter, $prevNode, $request, $response,
$runIndex, $secrets, $today, $vars, $workflow

القيمة التي تبحث عنها هي $()، وتعريفها في التوثيق:

Returns the data of the specified node **Syntax:** $(nodeName)

فالقاعدة عملية لا نظرية: اسم العقدة بين قوسين، لا بين أقواس مربّعة.

{{ $('Node Name') }}

ويمكن أن تُسلسَل على هذه النتيجة. الشكل الشائع هو أن تطلب أول عنصر منها ثم حقلاً داخله:

{{ $('Fetch Invoices').first().json.amount }}

التوثيق ينصّ على أن $() «يعيد بيانات العقدة المحدّدة» ولا يثبّت شكل هذه السلسلة، فاحتفظ بها بوصفها النمط الشائع لا قاعدة ملزِمة.

وأقرب ما يشبه «العقدة السابقة» هو $prevNode: Information about the node that the current input came from.، و$workflow يعطيك Information about the current workflow. أما $input فهو ببساطة The input data of the current node — ولا تحتاجه في أسبوعك الأول، لكنه الاسم الكامل لما ستكتبه بعد شهر كـ$input.item.json.

الأساس: كل ما بين العقدتين عناصر، و$json مجرد اختصار

القاعدة التي يقوم عليها كل ما في هذه الصفحة جملة واحدة: In n8n, all data passed between nodes is an array of objects.

العنصر نفسه عند n8n ملتفوف داخل كائن له مفتاح json — // Wrap each item in another object, with the key 'json' — ولهذا لا تمرّ مصفوفة بريد عادية كما هي: كل صف يصبح عنصراً مستقلاً. أساسيات هذا مشروحة في أول سير عمل لك، وهنا نحتاج منها شيئاً واحداً فقط.

$json تعريف مختصر لا أكثر: Returns the JSON input data to the current node, for the current item. Shorthand for $input.item.json.

انتبه إلى كلمتين في هذا التعريف: «للعنصر الحالي»، و«اختصار». فهو لا يعطيك البيانات كلها — يعطيك العنصر الذي تعمل عليه هذه العقدة الآن. وn8n تعالج العناصر واحداً واحداً: Nodes process multiple items automatically. When a node receives an array of data items, it processes each item individually and performs the configured operation for each one.

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

وسنتيجة هذه القاعدة عملية: نفس التعبير يبدو فورياً في المعاينة لأن المعاينة تحتوي صفاً واحداً، ثم يبدو بطيئاً في الإنتاج لأن الملف فيه آلاف الصفوف. التعبير لم يتغيّر — تغيّر عدد العناصر التي يُقيَّم عليها.

خمس درجات، لا تقفز فوقها

الدرجة الأولى: اسحب ولا تكتب

n8n يبني التعبير بدل أن تبنيه: You can map fruit by dragging and dropping fruit from the INPUT into the field where you want to use its value. This creates an expression, {{ $json.fruit }}.

لم تكتب حرفاً واحداً، ونتيجة سحبتك هي {{ $json.fruit }}. ابدأ من هنا: كل حقل في n8n يطلب منك قيمة يمكن أن تكون ثابتة أو تعبيراً، والسحب يوصلك إلى الباب الصحيح بلا كتابة.

الدرجة الثانية: $json بيدك

هذه هي الأمثلة التي تعطيها n8n نفسها: Pull {{$json.city}}. ولا أعمق من «حقل داخل حقل»: $json.body.city يعني الحقل city داخل body. وجملة التوثيق هنا تستحق التوقّف:

Note that this example uses JMESPath syntax to query the JSON data. You can also write this expression as {{$json['body']['city']}}.

أي أن $json.a.b و$json['a']['b'] شيء واحد، فخذ هذه الصفقة الآن وامضِ. أما $jmespath() فهي في قائمة المتغيّرات، وهي للاستعلامات على هياكل متداخلة تحتاج فعلاً لغة استعلام — لا لسحب حقل واحد. لا تبدأ بها.

الدرجة الثالثة: $now

A DateTime representing the current moment. وعندها جملة واحدة تفسّر نصف ما ستراه في القسم التالي: Uses the workflow's time zone (which can be changed in the workflow settings).

الدرجة الرابعة: $if() — منطق داخل الحقل

$if($now.hour < 17, "Good day", "Good evening") — «إن كان الشرط، وإلا». وهي قابلة للتعشيش:

$if($now.hour < 10 ? "Good morning" : $if($now.hour < 17 ? "Good day" : "Good evening"))

الدرجة الخامسة: $fromAI() — تعبئة حقل بالنموذج

$fromAI(key, description?, type?, defaultValue?)، والأنواع One of string, number, boolean, json, date, datetime.

التصحيح المهم هنا: $fromAI() ليست «الوكيل يملأ الحقل». هي حقل مسمّى مسبقاً تنتظر تعبئته. n8n يعرف من الوسيط الثاني ما الذي تريده، ومن الوسيط الثالث أي نوع قيمة تريد، ومن الوسيط الرابع ماذا يفعل إن لم يجد جواباً. النموذج هو منفّذ التعبئة، أما قرار ماذا يُملأ فهو قرارك أنت في الوصف.

⚠️ المنطقة الزمنية: الفخّ الذي لا يُظهر خطأً

⚠️ المنطقة الزمنية الافتراضية If you don't configure the workflow or instance timezone, n8n defaults to the EDT (New York) timezone.

هذه ليست تفصيلاً في صفحة إعدادات. هي تفسّر سبباً مباشراً لانحراف التواريخ: $now يستخدم منطقة سير العمل، وسير العمل الذي لم تُحدّد له منطقة يسقط على EDT.

ومعه وشك يقع كل مساء: تقرير يومي يُبنى عند منتصف الليل بتوقيتك أنت، فيخرج مختوماً بتاريخ اليوم التالي — لأن n8n ترى الساعة بعد منتصف الليل بتوقيت نيويورك. لا خطأ في السجل، ولا تنبيه، بل فاتورة أو تقرير بتاريخ خاطئ يصل إلى صندوقك.

العلاج سطر واحد: حدّد المنطقة الزمنية في إعدادات سير العمل قبل أول تشغيل، لا بعده.

متى تكفي التعبير، ومتى تحتاج عقدة Code؟

الحدّ العملي بسيط: التعبير يضبط قيمة واحدة في حقل واحد. وما عداه — إعادة ترتيب كامل، أو حلقة على العناصر، أو دمج مصادر متعددة — فهذه عمل عقدة Code. وهذا جدول n8n نفسه:

الطريقة	متى تحتاجها	أمثلة	متاحة على
Expressions	Set a single parameter value using existing data	Pull {{$json.city}}, format dates, simple math	Cloud and Self-hosted
Code node	Write full JavaScript/Python for complex transformations	Restructure data, loop through items, use external libraries	Cloud and Self-hosted
AI Transform node	Generate transformation code from natural language	Group by user and sum totals, categorize by sentiment	Cloud only
Other data transformation nodes	Perform common operations with a visual interface	Aggregate items, split arrays, sort data, remove duplicates	Cloud and Self-hosted

وكن صادقاً مع الجدول: فيه صفّ واحد تجاوزه الزمن.

⚠️ صفّ واحد في هذا الجدول لم يعد يعمل You can no longer add an **AI Transform** node. Write JavaScript directly in the **Code** node instead.

اقرأ بقية الجدول، وتخطَّ هذا الصف. وأما أول سؤال يطرحه كل من يقف أمام عقدة Code — «هل يشتغل الكود عندي؟» — فالجواب على n8n Cloud هو لا:

You can't access the file system or make HTTP requests. · You can't import external npm modules.

أي أن كوداً يقرأ ملفاً من قرصك أو يستدعي واجهة برمجية مباشرةً ليس مكانه هنا على السحابة. والمخرج الصحيح في n8n هو عقدة مناسبة للمهمة أو تكامل جاهز: عقدة Code تُحوّل البيانات التي وصلت، ولا تخرج منها إلى الشبكة.

وضبط طريقة تشغيلها داخل العقدة نفسها سطر واحد، والوضع الافتراضي هو الأول: Run Once for All Items: this is the default. والبديل Run Once for Each Item: choose this if you want your code to run for every input item.

أمّا Python فحالتها منفصلة: Pyodide is removed from n8n 2.0.، وNative Python support using task runners is available from n8n 1.111.0. This feature is stable as of n8n 2.

وحتى لا تصطدم بترقية لاحقة:

⚠️ ترقية إلى n8n 3.0 n8n 3.0 removes the $evaluateExpression() convenience method from the Code node (JavaScript).

⚠️ خطأ «لم تُنفَّذ العقدة»: حين يشير التعبير إلى عقدة لم تعمل

An expression references the node '<node-name>', but it hasn't been executed yet. Either change the expression, or re-wire your workflow to make sure that node executes first.

الرسالة تحتمل حلّين، وكلاهما مكتوب داخلها: غيّر التعبير، أو أعد التوصيل. والخبر الجيد أن n8n تعطيك أداة كشف قبل التخمين:

$("<node-name>").isExecuted

الاستخدام الأنفع: لا تسأل «لماذا ظهر الخطأ؟» بل «هل تعمل هذه العقدة أصلاً؟». ضع {{ $('Node Name').isExecuted }} في حقل مؤقت داخل عقدة لاحقة، فرى Boolean يجيبك قبل أن تعيد رسم الوصلات.

وسببا الخطأ الأشيع في الممارسة: أنك شغّلت عقدة واحدة من السير بدل السير كله، أو أن الفرع المُشير إليه لم يُنفَّذ أصلاً في هذه التشغيلة — شرط لم يتحقق، أو عقدة سبقت في مسار آخر.

والسببان يُعالَجان في منطق المسار ومعالجة الأخطاء، أما التصحيح بين يديك: اقرأ الرسالة حرفياً — الجملة الأخيرة فيها هي الحل.

⚠️ التعبيرات تدخل حقول بيانات الاعتماد — وهذا مقصود

You can also use expressions in credential fields. · Expressions are evaluated per execution, so different executions don't share data.

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

القاعدة التي ألتزم بها بنفسي: قيمة سرّية لا تُكتب داخل نص تعبير، ولا داخل أي حقل نصّي في العقدة — تُكتب في بيانات الاعتماد، لأنها كيان منفصل عن نص سير العمل، ومن يملك حق تعديل السير لا يقرأها من داخل نصّه. و$secrets و$vars موجودتان في قائمة المتغيّرات نفسها، لكنهما ليستا مكاناً لتخزين قيمة ثابتة.

أما كيف تُدار المفاتيح على نسخة ذاتية الاستضافة، ومن يقرأها متى، فيفسّره الاستضافة الذاتية بأمان.

أين يتقاطع هذا مع الوكلاء؟

إذا كان سير عملك يمرّ على عقدة وكيل، فثلاثة أشياء من هذه الصفحة تصير يوميّة:

1. قراءة نتيجة أداة: $('اسم الأداة') بدل تخزين النتيجة في متغيّر ثابت تنساه.
2. isExecuted: أشيع خطأ حقيقي عند الوكلاء هو فرع لم يُنفَّذ ثم يشير إليه تعبير.
3. الحدّ بين {{ }} وCode: الوكيل يعيد json نظيفاً، فغالباً ما تحتاج $json فقط ولا تحتاج عقدة Code إطلاقاً.

ولو أردت الفرق بين «حقل واحد يملؤه النموذج» و«حلقة استدلال كاملة تستدعي أدوات»، فالتفصيل في الوكلاء الثلاثة في n8n. أمّا المقابِل اللغوي لفكرة $fromAI() — «الاستدعاء يستدعي أداة ويملأ حقلاً بنتيجتها» — فيشرحه الأدوات واستدعاء الأدوات في لانغ تشين من الجهة الأخرى.

---

أُراجع في n8n 2.42.5 (2026-10-08). n8n يُصدر نسخاً جديدة أسبوعياً تقريباً، فراجع التوثيق إن كان عمرك يتجاوز بضعة أشهر.

---

تحتاج أتمتة تعمل فعلاً؟

نصمّم ونبني أنظمة أتمتة للشركات والأفراد على n8n — من أول سير عمل يعمل خلال يوم، إلى وكيل يوثّق خطواته ويطلب موافقة بشرية قبل أي إجراء حسّاس. اكتب لنا وضعك من صفحة التواصل.