Expressions در n8n: آموزش کامل اسکریپت‌نویسی ۱۴۰۴

احتمالاً ورک‌فلوهای شما «خنگ» و ناکارآمد هستند. دلیل آن هم یک اشتباه رایج و خطرناک است: استفاده از مقادیر ثابت یا به اصطلاح فنی، هاردکد کردن (Hardcoding).

وقتی یک اتوماسیون می‌سازید که داده‌ها را به صورت ایستا پردازش می‌کند، در واقع یک سیستم شکننده طراحی کرده‌اید که با کوچکترین تغییری فرو می‌پاشد. اگر به دنبال ساخت سیستم‌های پایدار هستید، همانطور که در مرجع تخصصی n8n بررسی کردیم، پویایی شرط بقای اتوماسیون است.

راه‌حل این مشکل و مغز متفکر ورک‌فلوهای هوشمند، مفهوم کلیدی Expressions است. Expressions به ورک‌فلو شما اجازه می‌دهند تا داده‌ها را به صورت داینامیک پردازش کنند و بر اساس آن تصمیم بگیرند.

در پروژه‌های واقعی که در کارورا مدیریت کرده‌ایم، گاهاً شاهد این سناریوی تلخ بوده‌ایم: یک ورک‌فلو حیاتی که وظیفه همگام‌سازی اطلاعات مشتریان را بر عهده داشت، ناگهان از کار افتاد. پس از ساعت‌ها بررسی، مشکل مشخص شد: یک شناسه (ID) یا پارامتر پیکربندی به صورت ثابت وارد شده بود.

تیم فنی آن شناسه را تغییر داده بود و فرد مسئول به یاد نداشت که باید آن را در اتوماسیون به‌روزرسانی کند. نتیجه؟ از دست رفتن داده‌های چندین روز. Expressions دقیقاً برای جلوگیری از همین فجایع طراحی شده‌اند.

Expressions در n8n چیست؟ مغز متفکر اتوماسیون شما

اجازه دهید تعاریف آکادمیک را کنار بگذاریم. Expression در n8n یک قطعه کد کوتاه جاوا اسکریپت است که به شما اجازه می‌دهد به داده‌های ورک‌فلو دسترسی پیدا کرده، آن‌ها را دستکاری کنید و مقادیر داینامیک تولید نمایید.

به زبان ساده، Expressions به نودهای شما قدرت «فکر کردن» می‌دهند. هر زمان که در یک فیلد از نودهای n8n، آیکون کوچک fx یا دکمه Expression را مشاهده می‌کنید، به این معناست که آن فیلد قابلیت پذیرش کد را دارد.

ساختار اصلی و سینتکس تمام Expressions در n8n به شکل زیر است:

`javascript
{{ JAVASCRIPT_CODE }}
`

هر چیزی که بین این آکولادهای دوتایی {{ }} قرار می‌گیرد، به عنوان کد جاوا اسکریپت تفسیر و اجرا می‌شود و خروجی آن جایگزین محتوای فیلد خواهد شد.

بیایید با یک مثال بسیار ساده شروع کنیم. یک نود Edit Fields (که قبلاً Set نام داشت) در ورک‌فلو خود ایجاد کنید. در قسمت Value، به جای وارد کردن یک متن ثابت، عبارت زیر را قرار دهید:

`javascript
{{ $now }}
`

پس از اجرای نود، خواهید دید که مقدار فیلد دیگر متن {{ $now }} نیست، بلکه تاریخ و زمان دقیق اجرای ورک‌فلو است. $now یک متغیر ویژه (Luxon DateTime) است. برای اطلاعات بیشتر می‌توانید به مستندات رسمی n8n مراجعه کنید.

⚠️ نکته امنیتی بسیار مهم: هرگز اطلاعات حساس مثل پسورد دیتابیس یا API Key را حتی در Expressions هاردکد نکنید. همیشه از بخش Credentials در نودها استفاده کنید تا امنیت داده‌هایتان حفظ شود.

معماری داده و نقش Expressions در n8n

برای استفاده حرفه‌ای از Expressions، ابتدا باید ساختار جریان داده در n8n را به صورت دقیق درک کنید. n8n داده‌ها را در قالب آیتم‌های (Items) JSON بین نودها جابجا می‌کند. درک تفاوت متغیرهای زیر حیاتی‌ترین بخش یادگیری شماست:

| متغیر | توضیح مفهومی | کاربرد اصلی | مثال |
| :— | :— | :— | :— |
| $json | به داده‌های JSON آیتمی اشاره دارد که در حال حاضر پردازش می‌شود. | دسترسی به فیلدهای ورودی نود فعلی. | {{ $json.customer_name }} |
| $item(index) | شبیه «ماشین زمان» است. دسترسی به خروجی کامل یک نود قبلی بر اساس ایندکس. | ارجاع به داده‌های مراحل اولیه ورک‌فلو (Legacy). | {{ $item(0).$json.id }} |
| $runIndex | شمارنده اجرای ورک‌فلو در یک حلقه (Loop). | شمارش آیتم‌های در حال پردازش در نود Loop Over Items. | {{ $runIndex }} |

سناریوی ۱: استفاده از $json برای دسترسی به داده‌های فعلی

فرض کنید یک نود Webhook دارید که اطلاعات یک فرم را دریافت می‌کند:

`json
{
“body”: {
“name”: “آرش”,
“email”: “arash@example.com”,
“plan”: “premium”
}
}
`

در نود بعدی (مثلاً Send Email)، از Expression زیر استفاده می‌کنید:

`javascript
سلام {{ $json.body.name }}، به سرویس ما خوش آمدید.
`

سناریوی ۲: استفاده از $item برای ارجاع به گذشته

اگر بخواهید به خروجی یک نود در ابتدای مسیر (مثلاً نود Get Config) دسترسی داشته باشید، بدون اینکه آن نود مستقیماً به نود فعلی متصل باشد:

`javascript
Config-ID: {{ $(‘Get Config’).item.json.configId }}
`

نکته فنی: در نسخه‌های مدرن n8n، استفاده از سینتکس $('Node Name').item استانداردتر از $item(0) است و خوانایی ورک‌فلوهای پیچیده را به شدت افزایش می‌دهد.

راهنمای عملی ۱۴۰۴: ۵ مثال پولساز با Expressions

تئوری کافیست. بیایید ببینیم Expressions چطور در سناریوهای کسب‌وکاری واقعی، ارزش‌آفرینی می‌کنند.

۱. منطق شرطی: ارسال ایمیل‌های متفاوت

سناریو: ارسال لینک درگاه پرداخت ریالی برای کاربران ایرانی و Stripe برای خارجی‌ها.
راه‌حل: استفاده از عملگر سه‌تایی در Expressions:

`javascript
لینک پرداخت: {{ $json.country === ‘IR’ ? ‘https://iran-gateway.com/’ + $json.orderId : ‘https://stripe.com/’ + $json.orderId }}
`

۲. فرمت‌دهی داده: ترکیب نام و نام خانوادگی

راه‌حل: ساخت نام کامل (fullName) از اجزای جداگانه:

`javascript
{{ $json.firstName + ‘ ‘ + $json.lastName }}
`

۳. ساخت URL داینامیک برای API

سناریو: دریافت جزئیات سفارش بر اساس شناسه مشتری.
راه‌حل: تزریق شناسه مشتری در URL:

`
https://api.ecommerce.com/v2/customers/{{ $json.customerId }}/orders
`

۴. محاسبات ریاضی: قیمت نهایی با تخفیف

راه‌حل: محاسبه قیمت با کسر درصد تخفیف به کمک Expressions:

`javascript
{{ parseFloat(($json.basePrice * (1 – $json.discountPercentage / 100)).toFixed(2)) }}
`

۵. کار با آرایه‌ها: استخراج لیست ایمیل‌ها

سناریو: تبدیل لیستی از آبجکت‌ها به یک رشته متنی ایمیل (CSV) برای ارسال به یک سرویس دیگر.
راه‌حل: استفاده از متد .map() و .join() جاوا اسکریپت روی items:

`javascript
{{ $items().map(item => item.json.email).join(‘, ‘) }}
`

سطح حرفه‌ای: ترکیب Expressions با Code Node

Expressions ابزاری قدرتمند برای تبدیل داده هستند، اما زمانی که منطق شما بسیار پیچیده می‌شود (مثلاً نیاز به توابع بازگشتی یا کتابخانه‌های خارجی دارید)، Code Node وارد میدان می‌شود.

قانون طلایی ما در پروژه‌ها این است:
از Expressions برای *آماده‌سازی* داده و از Code Node برای *پردازش* سنگین استفاده کنید.

فرض کنید می‌خواهید لیستی از محصولات را فیلتر کنید که موجودی انبارشان کم است. انجام این کار با ترکیب این دو ابزار مهندسی‌تر است. ابتدا با یک Expression ساده داده‌ها را استخراج کنید و سپس در Code Node منطق پیچیده حلقه و فیلتر را اعمال نمایید.

به یاد داشته باشید که بسیاری از متدهای پیشرفته مانند .map() و .filter() مستقیماً در Expressions قابل استفاده هستند و برای بیش از ۹۰٪ کارها شما را از کدنویسی سنگین بی‌نیاز می‌کنند. این رویکرد تعادلی، ورک‌فلوهای شما را در سال ۱۴۰۴ و فراتر از آن، ماژولار و قدرتمند نگه می‌دارد.

—