التعامل مع البيانات: المحولات، والمتغيرات، والتعبيرات

كيف يفهم n8n البيانات؟ رحلة داخل هيكل JSON

قبل أن نبدأ بتعديل البيانات، يجب أن نفهم كيف يراها n8n ويخزنها. يتعامل n8n مع البيانات كمصفوفة من العناصر، حيث كل عنصر هو كائن JSON (JavaScript Object Notation). حتى لو لم يكن لديك خلفية برمجية، يمكنك تخيل كائن JSON كجدول صغير يحتوي على مفاتيح وقيم.

أشكال البيانات الشائعة داخل n8n

• النصوص (Strings): مثل الأسماء، العناوين، أو النصوص الطويلة. تكون دائماً محاطة بعلامات تنصيص.
• الأرقام (Numbers): الأرقام الصحيحة والعشرية، وتُستخدم في الحسابات والتسعير.
• القيم المنطقية (Booleans): تأخذ إما قيمة true (صحيح) أو false (خاطئ)، وتُستخدم للتحكم في القرارات والمسارات الشرطية.
• المصفوفات (Arrays): قائمة من العناصر المجمعة معاً، مثل قائمة بمنتجات اشترها عميل واحد.
• الكائنات المتداخلة (Nested Objects): كائن داخل كائن، مثل حقل “العنوان” الذي يحتوي بداخله على “المدينة”، “الشارع”، و”الرمز البريدي”.

فهم هذه الأنواع أساسي لأن المحولات والتعبيرات تتصرف بشكل مختلف بناءً على نوع البيانات التي تتعامل معها. النص يتعامل مع أدوات التقطيع والدمج، بينما الرقم يتعامل مع العمليات الحسابية، والمصفوفة تتطلب التكرار أو التصفية.

التعبيرات (Expressions): إعطاء ذكاء وحركية للعقد

هل تساءلت يوماً كيف يمكنك إرسال رسالة بريد إلكتروني تحتوي على الاسم الشخصي للعميل بدلاً من رسالة عامة؟ هنا يأتي دور **التعبيرات**. فهي تتيح لك دمج البيانات الديناميكية داخل إعدادات العقد.

الصيغة الأساسية للتعبيرات

تعتمد التعبيرات في n8n على نسخة مبسطة من لغة **JavaScript**، مكتوبة داخل أقواس متعرجة مزوجة. الطريقة الأساسية لقراءة حقل معين من العقدة الحالية هي: {{ $json.fieldName }}.

مثلاً، إذا كان حقل customer_name يحتوي على القيمة “أحمد”، فإن كتابة {{ $json.customer_name }} في حقل الرسالة سيطبع “أحمد” عند تشغيل الأتمتة.

الوصول إلى بيانات من عقد سابقة

غالباً ما تحتاج إلى بيانات ليست من العقدة السابقة مباشرة، بل من عقدة أبعد في السلسلة. يوفر n8n طريقة بسيطة للوصول إلى أي عقدة باستخدام اسمها: {{ $(“اسم العقدة”).item.json.fieldName }}.

مثلاً، إذا كان لديك عقدة باسم Webhook_Trigger استلمت طلب شراء، ثم مر عبر عدة عقد أخرى، وأردت أخيراً إرسال بريد إلكتروني يتضمن رقم الطلب الأصلي، يمكنك ببساطة كتابة: {{ $("Webhook_Trigger").item.json.order_id }}.

تنسيق النصوص والعمليات الحسابية داخل التعبيرات

لا تقتصر التعبيرات على جلب القيم فقط، بل تتيح لك معالجة البيانات بشكل فوري أثناء تدفقها. بما أن n8n يعمل على بيئة Node.js، يمكنك استخدام دوال JavaScript القياسية لمختلف الأغراض.

1. معالجة النصوص (String Manipulation)

• تنظيف المسافات الزائدة: {{ $json.email.trim() }} تقوم بإزالة أي مسافات فارغة في بداية أو نهاية البريد الإلكتروني.
• تحويل النصوص إلى حروف كبيرة/صغيرة: {{ $json.code.toUpperCase() }} لتحويل الكود إلى الحروف الكبيرة.
• استخراج جزء من النص (Substring / Split): إذا كان لديك الاسم الكامل في حقل واحد وتريد الاسم الأول فقط: {{ $json.fullName.split(' ')[0] }}. هذا التعبير يقوم بتقسيم النص عند كل مسافة ويأخذ العنصر الأول (الاسم الأول).

2. العمليات الحسابية (Math Operations)

• حساب الإجمالي مع الضريبة: {{ $json.price * 1.15 }} لحساب السعر شامل ضريبة قيمة مضافة 15%.
• التقريب: {{ Math.round($json.totalAmount) }} لتقريب المبلغ لأقرب عدد صحيح.

3. التعامل مع التواريخ والأوقات (Dates and Times)

• جلب التاريخ الحالي بصيغة معينة: {{ $now.toFormat('yyyy-MM-dd') }}.
• إضافة أيام إلى تاريخ معين: {{ $now.plus({ days: 7 }).toFormat('yyyy-MM-dd') }} (مفيد جداً لإعادة تذكير الفواتير بعد أسبوع).
• تحويل صياغة تاريخ قادم من نموذج: {{ DateTime.fromISO($json.created_at).toFormat('dd/MM/yyyy') }}.

المتغيرات وسياق التنفيذ (Variables & Context)

عندما تقوم ببناء مسارات أتمتة معقدة، قد تحتاج إلى حفظ قيم لاستخدامها لاحقاً في أماكن مختلفة، أو للتمييز بين بيئة التطوير والبيئة الإنتاجية. هنا يأتي دور **المتغيرات** في n8n.

1. متغيرات البيئة (Environment Variables)

إذا كنت تستضيف n8n على خادمك الخاص (Self-hosted)، يمكنك تعريف متغيرات بيئة على مستوى الخادم نفسه. هذه المتغيرات رائعة لتخزين المفاتيح السرية أو روابط API الرئيسية التي لا تتغير. يمكنك الوصول إليها داخل أي تعبير باستخدام الصيغة: {{ $env.MY_CUSTOM_API_KEY }}.

2. متغيرات سير العمل (Workflow Variables)

في الإصدارات الحديثة من n8n، تم تقديم مفهوم “Variables” على مستوى سير العمل…