آموزش Function در n8n؛ تفاوت Function و Code Node با مثال عملی

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

در نسخه‌های قدیمی n8n، دو نود با نام‌های Function و Function Item برای اجرای کد JavaScript استفاده می‌شدند. این نودها به کاربران اجازه می‌دادند اطلاعات را پردازش کنند و خروجی دلخواه بسازند. در نسخه‌های جدیدتر، نود Code جایگزین این روش شده است.

در این مقاله یاد می‌گیریم Function در n8n چه کاربردی داشت، چه تفاوتی با Function Item داشت، چطور از کدهای آن در نسخه‌های قدیمی استفاده می‌شد و چگونه می‌توان همان منطق را با Code Node در نسخه‌های جدید پیاده‌سازی کرد.

Function در n8n چیست؟

Function یک نود در نسخه‌های قدیمی n8n بود که امکان اجرای کد JavaScript را روی داده‌های ورودی یک Workflow فراهم می‌کرد.

به کمک این نود می‌توانستید کارهایی مانند موارد زیر انجام دهید:

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

برای مثال، فرض کنید یک API اطلاعات محصولات فروشگاه را برمی‌گرداند. هر محصول شامل نام، قیمت و تعداد موجودی است. شما می‌خواهید ارزش موجودی هر محصول را محاسبه کنید و فقط محصولاتی را نگه دارید که ارزش موجودی آن‌ها بیشتر از یک میلیون تومان است.

این کار با نوشتن چند خط JavaScript قابل انجام است.

نکته مهم: اگر از نسخه جدید n8n استفاده می‌کنید و نود Function را در فهرست نودها پیدا نمی‌کنید، این موضوع طبیعی است. برای اجرای کدهای جدید باید از Code Node استفاده کنید.

تفاوت Function، Function Item و Code Node چیست؟

این سه نام به یک قابلیت کلی، یعنی اجرای کد در Workflow، مربوط هستند؛ اما نحوه پردازش داده‌ها در آن‌ها یکسان نیست.

در نود Function معمولاً تمام آیتم‌های ورودی در قالب یک آرایه در اختیار کد قرار می‌گرفتند. بنابراین می‌توانستید هم‌زمان روی چند رکورد عملیات انجام دهید، آن‌ها را فیلتر کنید یا ساختار خروجی را تغییر دهید.

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

در Code Node نیز می‌توانید بر اساس نیاز خود یکی از دو حالت اصلی را انتخاب کنید:

• Run Once for All Items: اجرای کد یک‌بار برای تمام آیتم‌های ورودی
• Run Once for Each Item: اجرای کد برای هر آیتم به‌صورت جداگانه

بنابراین برای بازنویسی Workflowهای قدیمی، باید ابتدا مشخص کنید کد قبلی روی تمام داده‌ها اجرا می‌شده یا روی هر رکورد به‌صورت مستقل.

آموزش Function در نسخه‌های قدیمی n8n

اگر هنوز از نسخه‌ای استفاده می‌کنید که نودهای Function یا Function Item را دارد، می‌توانید کدهای JavaScript را مستقیماً داخل آن‌ها بنویسید.

برای مثال، فرض کنید اطلاعات زیر از یک نود قبلی دریافت شده است:

[

  {

    "name": "Laptop",

    "price": 50000000,

    "quantity": 2

  },

  {

    "name": "Mouse",

    "price": 800000,

    "quantity": 5

  }

]

هر آیتم شامل نام محصول، قیمت و تعداد موجودی است.

مثال اول: اضافه کردن یک فیلد جدید با Function

فرض کنید می‌خواهید ارزش موجودی هر محصول را محاسبه کنید. برای این کار در نسخه قدیمی، یک Function Node بعد از نود دریافت اطلاعات قرار دهید و کد زیر را در آن بنویسید:

return items.map(item => {

  item.json.inventoryValue =

    item.json.price * item.json.quantity;



  return item;

});

در این مثال:

• items مجموعه آیتم‌های ورودی است.
• item.json اطلاعات هر آیتم را نگه می‌دارد.
• inventoryValue فیلد جدیدی است که به اطلاعات محصول اضافه می‌شود.
• map() روی تمام آیتم‌ها اجرا می‌شود و آرایه خروجی را تولید می‌کند.

خروجی به شکل زیر خواهد بود:

[

  {

    "name": "Laptop",

    "price": 50000000,

    "quantity": 2,

    "inventoryValue": 100000000

  },

  {

    "name": "Mouse",

    "price": 800000,

    "quantity": 5,

    "inventoryValue": 4000000

  }

]

در نتیجه، هر محصول یک فیلد جدید به نام inventoryValue دارد.

توجه کنید که این نمونه مربوط به ساختار کدنویسی Function در نسخه‌های قدیمی است؛ برای اجرای همین منطق در نسخه‌های جدید باید از Code Node استفاده کنید.

مثال دوم: فیلتر کردن اطلاعات با Function

حالا فرض کنید می‌خواهید فقط محصولاتی را نگه دارید که ارزش موجودی آن‌ها بیشتر از ده میلیون تومان است.

کد زیر را در Function Node قرار دهید:

return items.filter(item => {

  const inventoryValue =

    item.json.price * item.json.quantity;



  return inventoryValue > 10000000;

});

متد filter() فقط آیتم‌هایی را نگه می‌دارد که شرط تعیین‌شده برای آن‌ها برقرار باشد.

در این مثال، محصول Laptop با ارزش موجودی صد میلیون تومان باقی می‌ماند؛ اما محصول Mouse با ارزش موجودی چهار میلیون تومان از خروجی حذف می‌شود.

این روش برای فیلتر کردن سفارش‌ها، محصولات، کاربران و داده‌های دریافتی از APIها کاربرد دارد.

Function Item در n8n چه کاربردی داشت؟

Function Item برای زمانی طراحی شده بود که می‌خواستید کد را روی هر آیتم به‌صورت مستقل اجرا کنید.

برای مثال، فرض کنید اطلاعات هر مشتری شامل نام و نام خانوادگی است و می‌خواهید یک فیلد جدید به نام fullName ایجاد کنید.

کد نمونه در Function Item قدیمی:

item.fullName =

  `${item.firstName} ${item.lastName}`;



return item;

در این الگو، کد برای هر آیتم اجرا می‌شود و فیلد جدیدی به اطلاعات آن اضافه می‌کند.

نحوه دقیق دسترسی به فیلدها و قالب کد به نسخه قدیمی n8n بستگی دارد؛ بنابراین اگر در حال نگهداری یک Workflow قدیمی هستید، بهتر است کد را با نسخه همان Workflow بررسی کنید.

در نسخه‌های جدید، همین کار را می‌توانید با Code Node و حالت Run Once for Each Item انجام دهید.

جایگزین Function در نسخه‌های جدید n8n چیست؟

جایگزین اصلی Function و Function Item در نسخه‌های جدید، Code Node است.

برای اجرای همان مثال محاسبه ارزش موجودی در نسخه جدید، مراحل زیر را انجام دهید:

1. وارد Workflow خود شوید.
2. روی علامت افزودن نود کلیک کنید.
3. نود Code را جست‌وجو و انتخاب کنید.
4. اگر می‌خواهید تمام آیتم‌ها را هم‌زمان پردازش کنید، حالت Run Once for All Items را انتخاب کنید.
5. کد JavaScript را در بخش کدنویسی وارد کنید.
6. نود را اجرا کنید و خروجی را بررسی کنید.

مثال کاربردی: تبدیل Function به Code Node

اگر کد قدیمی شما برای تمام آیتم‌ها اجرا می‌شده است، می‌توانید منطق آن را در حالت Run Once for All Items بازنویسی کنید:

const items = $input.all();



return items.map(item => {

  return {

    ...item,

    json: {

      ...item.json,

      inventoryValue:

        item.json.price * item.json.quantity,

    },

  };

});

در این کد:

• $input.all() تمام آیتم‌های ورودی را دریافت می‌کند.
• map() روی هر آیتم اجرا می‌شود.
• عملگر ... اطلاعات قبلی را حفظ می‌کند.
• مقدار inventoryValue به خروجی اضافه می‌شود.
• آرایه نهایی با قالب مورد انتظار Code Node برگردانده می‌شود.

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

مثال: تبدیل Function Item به Code Node

اگر هدف شما پردازش هر رکورد به‌صورت جداگانه است، حالت Run Once for Each Item را انتخاب کنید.

برای اضافه کردن نام کامل مشتری، می‌توانید بنویسید:

return {

  ...$json,

  fullName: `${$json.firstName} ${$json.lastName}`,

};

در این حالت، $json به داده‌های آیتم جاری اشاره می‌کند. کد فیلدهای قبلی را حفظ می‌کند و فیلد fullName را به آن‌ها اضافه می‌کند.

برای جلوگیری از خطا، مطمئن شوید نام فیلدهای ورودی دقیقاً با نام‌هایی که در کد استفاده کرده‌اید مطابقت دارند.

چه زمانی از Function یا Code Node استفاده کنیم؟

هر کاری در n8n به کدنویسی نیاز ندارد. در بسیاری از سناریوها، نودهای آماده ساده‌تر و قابل‌نگهداری‌تر هستند.

برای انتخاب درست می‌توانید از جدول زیر استفاده کنید:

اگر هدف شما فقط اضافه کردن یک فیلد ثابت یا تغییر نام یک فیلد است، بهتر است ابتدا Edit Fields را بررسی کنید. استفاده از JavaScript زمانی ارزشمندتر می‌شود که منطق موردنیاز پیچیده‌تر باشد یا به کنترل بیشتری روی داده‌ها نیاز داشته باشید.

نکات مهم هنگام مهاجرت از Function به Code Node

تبدیل Function به Code Node همیشه به معنی کپی کردن مستقیم کد قبلی نیست. ساختار ورودی، خروجی و نحوه دسترسی به داده‌ها ممکن است متفاوت باشد.

هنگام مهاجرت به این موارد توجه کنید:

۱. حالت اجرای مناسب را انتخاب کنید. اگر کد قدیمی روی آرایه‌ای از آیتم‌ها کار می‌کرد، معمولاً Run Once for All Items نقطه شروع مناسبی است. اگر کد برای هر رکورد جداگانه اجرا می‌شد، Run Once for Each Item را بررسی کنید.

۲. ساختار خروجی را بررسی کنید. در حالت پردازش همه آیتم‌ها، معمولاً باید آرایه‌ای از آیتم‌های n8n برگردانید. در حالت پردازش هر آیتم، باید خروجی با ساختار مورد انتظار همان حالت سازگار باشد.

۳. اطلاعات قبلی را ناخواسته حذف نکنید. هنگام ایجاد خروجی جدید، اگر فقط فیلدهای تازه را برگردانید، ممکن است اطلاعات قبلی از بین بروند. عملگر ... می‌تواند به حفظ فیلدهای موجود کمک کند.

۴. کد را با داده واقعی آزمایش کنید. مقادیر خالی، null، فیلدهای غایب و پاسخ‌های غیرمنتظره API را در نظر بگیرید.

۵. مجوزها و محدودیت‌های محیط اجرا را بررسی کنید. دسترسی به کتابخانه‌ها و امکانات JavaScript ممکن است با توجه به نسخه و تنظیمات محیط n8n متفاوت باشد. هر کدی که در Node.js معمولی اجرا می‌شود، لزوماً بدون تغییر در Code Node قابل اجرا نیست.

خطاهای رایج در Function و Code Node

خطای ساختار خروجی

یکی از مشکلات رایج، برگرداندن داده‌ای با ساختاری است که Code Node انتظار ندارد.

در حالت Run Once for All Items، خروجی باید با قالب آیتم‌های n8n سازگار باشد. در مثال‌های این مقاله، هر آیتم دارای فیلد json است.

خطای نام فیلدها

اگر در کد از item.json.price استفاده کنید اما داده ورودی فیلد price نداشته باشد، ممکن است نتیجه محاسبه NaN یا خروجی نامعتبر باشد.

می‌توانید قبل از محاسبه، وجود فیلدها را بررسی کنید:

const price = Number($json.price ?? 0);

const quantity = Number($json.quantity ?? 0);



return {

  ...$json,

  inventoryValue: price * quantity,

};

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

اشتباه گرفتن Function با Code Node

اگر در نسخه جدید Function را جست‌وجو می‌کنید و نتیجه‌ای نمی‌بینید، لازم نیست به دنبال نصب یک نود قدیمی باشید. ابتدا Code Node را بررسی کنید و سپس کد را مطابق حالت اجرای انتخاب‌شده بازنویسی کنید.

استفاده غیرضروری از کد

نوشتن JavaScript برای هر تغییر کوچک، Workflow را دشوارتر از حد نیاز می‌کند. در صورت امکان از نودهای استاندارد استفاده کنید و کدنویسی را برای منطق‌هایی نگه دارید که واقعاً به آن نیاز دارند.

جمع‌بندی

Function و Function Item از نودهای قدیمی n8n برای اجرای JavaScript بودند. Function بیشتر برای پردازش مجموعه آیتم‌ها و Function Item برای اجرای منطق روی هر آیتم به‌صورت جداگانه کاربرد داشتند.

در نسخه‌های جدید، Code Node جایگزین این روش شده و دو حالت Run Once for All Items و Run Once for Each Item امکان انتخاب روش پردازش را فراهم می‌کنند.

اگر قصد دارید Workflowهای قدیمی را نگهداری کنید، بهتر است منطق کد قبلی، ساختار ورودی و قالب خروجی آن را بررسی کرده و سپس آن را به Code Node منتقل کنید. برای یادگیری روش جدید اجرای JavaScript، مقاله آموزش Code Node در n8n؛ اجرای کد JavaScript و پردازش داده‌ها را نیز مطالعه کنید.

سوالات متداول

آیا Function در نسخه جدید n8n وجود دارد؟

در نسخه‌های جدید، Code Node جایگزین Function و Function Item شده است. اگر Function را پیدا نمی‌کنید، از Code Node استفاده کنید.

تفاوت Function و Function Item چیست؟

Function برای پردازش مجموعه‌ای از آیتم‌های ورودی استفاده می‌شد؛ Function Item کد را روی هر آیتم به‌صورت مستقل اجرا می‌کرد.

آیا می‌توان کد Function را مستقیماً در Code Node کپی کرد؟

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

آیا برای استفاده از n8n باید JavaScript بلد باشیم؟

خیر. بسیاری از Workflowها را می‌توان با نودهای آماده ساخت. بااین‌حال، آشنایی با JavaScript برای پردازش داده‌های پیچیده، کار با APIها و ساخت اتوماسیون‌های اختصاصی مفید است.

برای تغییر ساده داده‌ها بهتر است از Edit Fields استفاده کنیم یا Code Node؟

برای تغییرات ساده مانند اضافه کردن، حذف یا تغییر نام فیلدها، Edit Fields معمولاً انتخاب ساده‌تری است. برای محاسبات و منطق اختصاصی، Code Node گزینه مناسب‌تری خواهد بود.