نود Code در N8N

نود Code در N8N

نود Code یکی از قدرتمندترین نودهای N8N است که به شما اجازه می‌دهد داخل ورکفلو، کد اختصاصی بنویسید و داده‌ها را دقیقاً مطابق نیاز خود پردازش، تبدیل، فیلتر، ترکیب یا آماده‌سازی کنید. هرجا نودهای آماده N8N برای منطق موردنظر شما کافی نباشند، نود Code نقش یک ابزار انعطاف‌پذیر و حرفه‌ای را ایفا می‌کند.

معرفی نود در N8N

نود Code برای اجرای کد سفارشی در جریان اجرای ورکفلو استفاده می‌شود. با این نود می‌توانید داده‌های ورودی را بخوانید، روی آن‌ها منطق دلخواه اعمال کنید و خروجی جدیدی به نودهای بعدی ارسال کنید.

دسته‌بندی نود Code در N8N از نوع Function است. این نود معمولاً برای پردازش داده، تبدیل ساختار JSON، انجام محاسبات، اعتبارسنجی، فیلترکردن آیتم‌ها، ساخت فیلدهای جدید و آماده‌سازی داده برای APIها یا دیتابیس‌ها استفاده می‌شود.

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

موارد استفاده

تبدیل ساختار داده‌ها

یکی از رایج‌ترین کاربردهای نود Code تبدیل ساختار JSON است. برای مثال ممکن است از یک API داده‌ای با ساختار پیچیده دریافت کنید، اما سرویس بعدی فقط چند فیلد خاص مانند نام، ایمیل و شماره تماس را نیاز داشته باشد.

  • حذف فیلدهای اضافه از خروجی API
  • تغییر نام فیلدها مانند تبدیل first_name به firstName
  • ترکیب چند فیلد مانند ساخت fullName از firstName و lastName
  • تبدیل آرایه‌ها به آبجکت یا برعکس

فیلترکردن داده‌ها

اگرچه N8N نودهای آماده‌ای مانند IF و Filter دارد، اما برای شرایط پیچیده‌تر می‌توان از نود Code استفاده کرد. برای مثال می‌توانید فقط سفارش‌هایی را عبور دهید که مبلغ آن‌ها بیشتر از مقدار مشخصی است و وضعیت پرداخت آن‌ها نیز paid باشد.

  • فیلتر سفارش‌های پرداخت‌شده
  • حذف کاربران غیرفعال از لیست
  • انتخاب رکوردهایی که تاریخ آن‌ها در بازه خاصی قرار دارد
  • حذف آیتم‌هایی که داده ناقص دارند

آماده‌سازی داده برای ارسال به API

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

  • ساخت body برای HTTP Request
  • فرمت‌کردن شماره تلفن قبل از ارسال به CRM
  • تبدیل تاریخ میلادی به فرمت ISO
  • ساخت آرایه محصولات برای ارسال به سیستم حسابداری

محاسبات و منطق اختصاصی

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

  • محاسبه مبلغ نهایی سفارش
  • تعیین سطح مشتری بر اساس مجموع خرید
  • محاسبه مدت زمان بین دو تاریخ
  • ساخت امتیاز برای لیدهای فروش

ترکیب با نودهای دیگر

نود Code معمولاً به‌تنهایی استفاده نمی‌شود و در کنار نودهای دیگر قدرت واقعی خود را نشان می‌دهد.

  • Webhook + Code + HTTP Request: دریافت داده از یک فرم، پاک‌سازی و ارسال به API خارجی
  • Google Sheets + Code + Gmail: خواندن لیست کاربران، ساخت متن ایمیل اختصاصی و ارسال پیام
  • Shopify + Code + Slack: بررسی سفارش‌ها، محاسبه مبلغ کل و ارسال گزارش به تیم فروش
  • HTTP Request + Code + PostgreSQL: دریافت داده از API، تبدیل ساختار و ذخیره در دیتابیس
  • Cron + Code + Telegram: اجرای زمان‌بندی‌شده، تولید گزارش و ارسال به تلگرام

پارامترها و تنظیمات

نود Code تنظیمات پیچیده‌ای ندارد، اما همان چند گزینه موجود تأثیر زیادی روی نحوه اجرای کد و خروجی آن دارند.

Mode

  • نام پارامتر: Mode
  • نوع داده: انتخابی
  • گزینه‌ها: Run Once for All Items و Run Once for Each Item
  • توضیح کاربرد: مشخص می‌کند کد شما یک‌بار برای همه آیتم‌های ورودی اجرا شود یا برای هر آیتم به‌صورت جداگانه.
  • مثال عملی: اگر می‌خواهید همه آیتم‌ها را با هم پردازش کنید، مثلاً جمع کل سفارش‌ها را حساب کنید، از Run Once for All Items استفاده کنید. اگر می‌خواهید برای هر آیتم یک فیلد جدید بسازید، از Run Once for Each Item استفاده کنید.

Run Once for All Items

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

نمونه کد برای پردازش همه آیتم‌ها:

const items = $input.all();
const result = items.map(item => {
  return {
    json: {
      name: item.json.name,
      email: item.json.email,
      status: 'processed'
    }
  };
});
return result;

Run Once for Each Item

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

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

return {
  json: {
    ...$json,
    fullName: `${$json.firstName} ${$json.lastName}`,
    isActive: true
  }
};

Language

  • نام پارامتر: Language
  • نوع داده: انتخابی
  • گزینه‌ها: JavaScript و در برخی نسخه‌ها Python
  • توضیح کاربرد: زبان برنامه‌نویسی مورد استفاده در نود را مشخص می‌کند.
  • مثال عملی: برای بیشتر ورکفلوها JavaScript انتخاب رایج‌تری است، چون ساختار داده‌ها در N8N بر پایه JSON است و JavaScript برای کار با JSON بسیار مناسب است.

JavaScript Code

  • نام پارامتر: Code
  • نوع داده: متن کدنویسی
  • توضیح کاربرد: محل نوشتن کد JavaScript برای پردازش داده‌های ورودی و تولید خروجی است.
  • مثال عملی: ساخت فیلد priceWithTax از روی price و taxRate.

نمونه:

return $input.all().map(item => {
  const price = item.json.price || 0;
  const taxRate = item.json.taxRate || 0;
  return {
    json: {
      ...item.json,
      priceWithTax: price + (price * taxRate)
    }
  };
});

Python Code

  • نام پارامتر: Code
  • نوع داده: متن کدنویسی
  • توضیح کاربرد: در نسخه‌هایی که Python در نود Code فعال است، می‌توانید منطق پردازش را با Python بنویسید.
  • مثال عملی: تبدیل لیست ورودی و اضافه‌کردن فیلد جدید به هر آیتم.

نمونه ساده Python:

items = _input.all()
result = []

for item in items:
  data = item.json
  data["status"] = "processed"
  result.append({"json": data})

return result

دسترسی به داده‌های ورودی

  • نام پارامتر یا متغیر: $input.all()
  • نوع داده: آرایه‌ای از آیتم‌ها
  • توضیح کاربرد: همه آیتم‌های ورودی را برمی‌گرداند.
  • مثال عملی: پردازش لیست سفارش‌ها یا کاربران.

const items = $input.all();

  • نام پارامتر یا متغیر: $input.first()
  • نوع داده: آیتم
  • توضیح کاربرد: اولین آیتم ورودی را دریافت می‌کند.
  • مثال عملی: زمانی که فقط یک رکورد از نود قبلی انتظار دارید.

const firstItem = $input.first();

  • نام پارامتر یا متغیر: $json
  • نوع داده: آبجکت JSON
  • توضیح کاربرد: در حالت Run Once for Each Item به داده JSON آیتم جاری دسترسی می‌دهد.
  • مثال عملی: خواندن ایمیل کاربر جاری.

const email = $json.email;

  • نام پارامتر یا متغیر: $binary
  • نوع داده: داده باینری
  • توضیح کاربرد: برای دسترسی به فایل‌ها و داده‌های باینری مانند تصویر، PDF یا فایل CSV استفاده می‌شود.
  • مثال عملی: نگهداری فایل دریافتی از Webhook و ارسال آن به نود بعدی.
  • نام پارامتر یا متغیر: $itemIndex
  • نوع داده: عدد
  • توضیح کاربرد: اندیس آیتم جاری را مشخص می‌کند.
  • مثال عملی: شماره‌گذاری ردیف‌ها یا ایجاد شناسه موقت.

return { json: { ...$json, rowNumber: $itemIndex + 1 } };

نکات مهم هنگام پیکربندی

  • خروجی نود Code باید حتماً ساختار قابل قبول N8N داشته باشد.
  • در حالت Run Once for All Items معمولاً باید یک آرایه از آیتم‌ها برگردانید.
  • هر آیتم خروجی باید حداقل دارای کلید json باشد.
  • برای جلوگیری از خطا، فیلدهایی را که ممکن است وجود نداشته باشند با مقدار پیش‌فرض مدیریت کنید.
  • اگر با داده‌های زیاد کار می‌کنید، از حلقه‌ها و پردازش‌های سنگین غیرضروری پرهیز کنید.
  • برای کار با تاریخ و زمان، بهتر است از فرمت‌های استاندارد مانند ISO 8601 استفاده شود.

ورودی‌ها و خروجی‌ها

ورودی نود Code

ورودی نود Code معمولاً مجموعه‌ای از آیتم‌هاست که از نود قبلی وارد می‌شود. هر آیتم در N8N معمولاً شامل یک بخش json و در صورت وجود فایل، یک بخش binary است.

نمونه ورودی:

[
  {
    "json": {
      "firstName": "Ali",
      "lastName": "Ahmadi",
      "email": "ali@example.com",
      "totalOrders": 5
    }
  },
  {
    "json": {
      "firstName": "Sara",
      "lastName": "Karimi",
      "email": "sara@example.com",
      "totalOrders": 12
    }
  }
]

خروجی نود Code

خروجی نود Code باید به شکل آیتم‌های قابل فهم برای N8N باشد. ساختار استاندارد خروجی به‌صورت آرایه‌ای از آبجکت‌هاست که هر آبجکت یک کلید json دارد.

نمونه خروجی معتبر:

[
  {
    "json": {
      "fullName": "Ali Ahmadi",
      "email": "ali@example.com",
      "customerLevel": "normal"
    }
  },
  {
    "json": {
      "fullName": "Sara Karimi",
      "email": "sara@example.com",
      "customerLevel": "vip"
    }
  }
]

مثال کامل تبدیل داده

فرض کنید داده‌های کاربران را از Google Sheets دریافت کرده‌اید و می‌خواهید نام کامل و سطح مشتری را بسازید.

کد:

const items = $input.all();

return items.map(item => {
  const firstName = item.json.firstName || '';
  const lastName = item.json.lastName || '';
  const totalOrders = item.json.totalOrders || 0;

  return {
    json: {
      fullName: `${firstName} ${lastName}`.trim(),
      email: item.json.email,
      customerLevel: totalOrders >= 10 ? 'vip' : 'normal'
    }
  };
});

کار با داده باینری

اگر آیتم ورودی دارای فایل باشد، می‌توانید داده باینری را همراه خروجی نگه دارید. این موضوع زمانی مهم است که مثلاً یک فایل از Webhook دریافت کرده‌اید و بعد از پردازش اطلاعات JSON، همچنان می‌خواهید فایل را به نود بعدی منتقل کنید.

نمونه:

return $input.all().map(item => {
  return {
    json: {
      ...item.json,
      processed: true
    },
    binary: item.binary
  };
});

نکات پیشرفته و ترفندها

حذف داده‌های تکراری

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

const items = $input.all();
const seen = new Set();
const uniqueItems = [];

for (const item of items) {
  const email = item.json.email;
  if (!seen.has(email)) {
    seen.add(email);
    uniqueItems.push(item);
  }
}

return uniqueItems;

مرتب‌سازی آیتم‌ها

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

const items = $input.all();

items.sort((a, b) => {
  return b.json.total - a.json.total;
});

return items;

گروه‌بندی داده‌ها

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

const items = $input.all();
const grouped = {};

for (const item of items) {
  const city = item.json.city || 'unknown';
  if (!grouped[city]) {
    grouped[city] = 0;
  }
  grouped[city] += item.json.amount || 0;
}

return Object.entries(grouped).map(([city, totalAmount]) => ({
  json: { city, totalAmount }
}));

دسترسی به خروجی نودهای قبلی

در نود Code می‌توانید به داده‌های نودهای دیگر نیز دسترسی داشته باشید. این قابلیت برای مقایسه داده‌ها یا ترکیب خروجی چند نود بسیار کاربردی است.

const users = $('Get Users').all();
const orders = $('Get Orders').all();

return users.map(user => {
  const userOrders = orders.filter(order => order.json.userId === user.json.id);
  return {
    json: {
      ...user.json,
      ordersCount: userOrders.length
    }
  };
});

استفاده از console.log برای عیب‌یابی

برای بررسی مقدار متغیرها و پیدا کردن خطاها می‌توانید از console.log استفاده کنید. این کار هنگام تست ورکفلو بسیار مفید است.

const items = $input.all();
console.log('Total items:', items.length);
return items;

مدیریت خطا با try و catch

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

try {
  const items = $input.all();
  return items.map(item => ({
    json: {
      email: item.json.email.toLowerCase()
    }
  }));
} catch (error) {
  return [{
    json: {
      success: false,
      message: error.message
    }
  }];
}

بهینه‌سازی عملکرد

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

ترکیب پیشرفته با Split In Batches

اگر با حجم زیادی از داده‌ها کار می‌کنید، ترکیب نود Split In Batches و Code کمک می‌کند داده‌ها را دسته‌دسته پردازش کنید. این روش فشار روی حافظه و سرویس‌های مقصد را کاهش می‌دهد.

  • خواندن داده از دیتابیس
  • تقسیم داده به دسته‌های کوچک
  • پردازش هر دسته با Code
  • ارسال کنترل‌شده به API مقصد

محدودیت‌ها و خطاها

محدودیت‌ها

  • نود Code جایگزین کامل یک محیط برنامه‌نویسی بزرگ نیست و برای پردازش‌های بسیار سنگین مناسب نیست.
  • اجرای کدهای طولانی و پیچیده می‌تواند نگهداری ورکفلو را دشوار کند.
  • دسترسی به پکیج‌های خارجی در همه محیط‌ها آزاد نیست و ممکن است به تنظیمات سرور یا محدودیت‌های نسخه ابری وابسته باشد.
  • کد باید در زمان منطقی اجرا شود؛ پردازش‌های طولانی ممکن است باعث timeout شوند.
  • خروجی باید با ساختار مورد انتظار N8N سازگار باشد، در غیر این صورت نود خطا می‌دهد.
  • برای کار با فایل‌های بزرگ، محدودیت حافظه و اندازه داده باید در نظر گرفته شود.

خطای رایج: خروجی نامعتبر

یکی از رایج‌ترین خطاها زمانی رخ می‌دهد که خروجی به شکل صحیح برگردانده نشود. برای مثال برگرداندن یک آبجکت ساده به‌جای آرایه در حالت Run Once for All Items می‌تواند باعث خطا شود.

خروجی اشتباه:

return { name: 'Ali' };

خروجی صحیح:

return [{ json: { name: 'Ali' } }];

خطای رایج: فراموش‌کردن کلید json

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

اشتباه:

return [{ name: 'Sara' }];

صحیح:

return [{ json: { name: 'Sara' } }];

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

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

راه‌حل:

const email = item.json.email ? item.json.email.toLowerCase() : null;

خطای رایج: تفاوت Modeها

کدی که در حالت Run Once for All Items درست کار می‌کند، ممکن است در حالت Run Once for Each Item خطا بدهد. دلیل آن تفاوت دسترسی به داده‌ها و نوع خروجی مورد انتظار است.

  • در Run Once for All Items معمولاً از $input.all() استفاده می‌شود.
  • در Run Once for Each Item معمولاً از $json استفاده می‌شود.
  • در حالت اجرای برای هر آیتم، خروجی معمولاً یک آیتم است، نه آرایه‌ای از همه آیتم‌ها.

خطای رایج: از بین رفتن داده باینری

اگر آیتم ورودی دارای فایل باشد و در خروجی فقط json را برگردانید، داده باینری از بین می‌رود. برای حفظ فایل، باید binary را هم منتقل کنید.

return $input.all().map(item => ({
  json: item.json,
  binary: item.binary
}));

ایده ها

  • ساخت سیستم امتیازدهی لیدها: دریافت اطلاعات کاربران از فرم، محاسبه امتیاز بر اساس شغل، بودجه و رفتار کاربر، سپس ارسال لیدهای باکیفیت به CRM.
  • گزارش‌ساز فروش روزانه: دریافت سفارش‌ها از فروشگاه، گروه‌بندی بر اساس محصول یا شهر، محاسبه مجموع فروش و ارسال گزارش به Slack یا Telegram.
  • پاک‌سازی خودکار دیتای Google Sheets: حذف ردیف‌های تکراری، استانداردسازی شماره موبایل، اصلاح ایمیل‌ها و آماده‌سازی داده برای کمپین ایمیلی.
  • مبدل داده بین دو API: دریافت خروجی پیچیده از یک سرویس، تبدیل ساختار JSON و ارسال آن به سرویس دیگر با فرمت موردنیاز.
  • سیستم تشخیص اولویت تیکت‌ها: بررسی متن، نوع مشتری و کلمات کلیدی تیکت، سپس تعیین سطح اولویت و ارسال تیکت‌های فوری به تیم پشتیبانی.

منابع و مستندات اصلی

دسته بندی: N8N برچسب ها:

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

19 − پنج =