نود Aggregate در N8N

نود Aggregate در N8N

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

معرفی نود در N8N

نود Aggregate در N8N برای تبدیل چند آیتم ورودی به یک یا چند آیتم خروجی استفاده می‌شود. این نود معمولاً زمانی کاربرد دارد که داده‌ها به‌صورت جداگانه وارد ورکفلو می‌شوند، اما در مرحله بعدی نیاز دارید آن‌ها را به‌شکل یک لیست، آرایه یا آبجکت تجمیع‌شده به نود بعدی ارسال کنید.

  • نام نود: Aggregate
  • دسته‌بندی: Function / Data Transformation
  • نوع عملکرد: تبدیل و تجمیع داده‌ها
  • کاربرد اصلی: تبدیل چندین آیتم جداگانه به یک ساختار داده واحد یا آرایه‌ای
  • مناسب برای: آماده‌سازی داده برای API، گزارش‌گیری، ارسال ایمیل، ذخیره‌سازی در دیتابیس، ساخت JSON نهایی و ترکیب با نودهای شرطی یا پردازشی

در N8N داده‌ها معمولاً به‌صورت آیتم‌های جداگانه بین نودها جابه‌جا می‌شوند. برای مثال اگر از Google Sheets ده ردیف بخوانید، خروجی آن معمولاً ده آیتم جداگانه است. اما بسیاری از APIها یا سیستم‌ها انتظار دارند داده‌ها به‌صورت یک آرایه در یک فیلد مشخص ارسال شوند. اینجاست که نود Aggregate اهمیت پیدا می‌کند.

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

۱. تبدیل چند ردیف Google Sheets به یک آرایه واحد

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

{  "orders": [    {      "id": 1001,      "customer": "Ali",      "amount": 250000    },    {      "id": 1002,      "customer": "Sara",      "amount": 430000    }  ]}

با نود Aggregate می‌توانید تمام آیتم‌ها را داخل فیلدی مثل orders جمع‌آوری کنید و سپس آن را با نود HTTP Request ارسال کنید.

۲. آماده‌سازی داده برای ارسال ایمیل گزارش

اگر از چندین سفارش، خطا، لاگ یا تیکت خروجی گرفته‌اید و می‌خواهید همه آن‌ها را در یک ایمیل خلاصه کنید، ابتدا با Aggregate داده‌ها را یکجا می‌کنید و سپس با نودهایی مثل Set، Code یا Email متن گزارش را می‌سازید.

  • خواندن سفارش‌ها از دیتابیس
  • تجمیع سفارش‌ها با Aggregate
  • ساخت متن گزارش با Code یا Set
  • ارسال ایمیل با Gmail، SMTP یا Email Send

۳. ساخت payload مناسب برای APIها

بسیاری از APIها داده‌ها را به‌صورت batch دریافت می‌کنند. برای مثال API ممکن است به‌جای ارسال هر کاربر به‌صورت جداگانه، یک آرایه از کاربران بخواهد:

{  "users": [    {      "name": "Reza",      "email": "reza@example.com"    },    {      "name": "Neda",      "email": "neda@example.com"    }  ]}

در این سناریو، نود Aggregate کمک می‌کند چندین آیتم کاربر را در فیلدی مثل users قرار دهید و سپس آن را به HTTP Request بدهید.

۴. تجمیع خروجی دیتابیس

اگر با نودهای PostgreSQL، MySQL، MongoDB یا Microsoft SQL چندین ردیف از دیتابیس دریافت می‌کنید، Aggregate می‌تواند آن‌ها را در قالب یک لیست آماده کند. این کار برای ذخیره‌سازی در یک سیستم دیگر، ساخت گزارش یا انتقال batch بسیار مفید است.

۵. ترکیب با Split In Batches

در بعضی ورکفلوها ابتدا داده‌ها را با Split In Batches به دسته‌های کوچک‌تر تقسیم می‌کنید، پردازش انجام می‌دهید و سپس در انتها با Aggregate نتایج پردازش‌شده را دوباره به یک ساختار منظم تبدیل می‌کنید.

  • دریافت ۱۰۰۰ رکورد از API
  • تقسیم رکوردها به batchهای ۱۰۰تایی
  • پردازش هر batch
  • تجمیع خروجی نهایی با Aggregate

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

تنظیمات نود Aggregate بسته به نسخه N8N ممکن است کمی تفاوت ظاهری داشته باشد، اما منطق اصلی آن ثابت است: مشخص می‌کنید کدام داده‌ها باید از آیتم‌های ورودی برداشته شوند و در چه ساختاری در خروجی قرار بگیرند.

Aggregate

  • نام پارامتر: Aggregate
  • نوع داده: انتخابی / Dropdown
  • کاربرد: مشخص می‌کند عملیات تجمیع به چه شکل انجام شود.
  • گزینه‌های رایج:
    • Individual Fields: فقط فیلدهای مشخص‌شده از آیتم‌های ورودی جمع‌آوری می‌شوند.
    • All Item Data Into a Single List: کل داده‌های آیتم‌ها در یک آرایه واحد قرار می‌گیرند.
  • مثال عملی: اگر فقط ایمیل کاربران را نیاز دارید، از Individual Fields استفاده کنید. اگر کل اطلاعات کاربران باید به‌صورت یک لیست ارسال شود، از All Item Data Into a Single List استفاده کنید.

Fields To Aggregate

  • نام پارامتر: Fields To Aggregate
  • نوع داده: مجموعه‌ای از فیلدها / Collection
  • کاربرد: مشخص می‌کند کدام فیلدها از آیتم‌های ورودی استخراج و تجمیع شوند.
  • زمان استفاده: زمانی که حالت Aggregate روی Individual Fields باشد.
  • مثال عملی: اگر آیتم‌های ورودی شامل name، email و amount هستند و فقط email و amount را می‌خواهید، این دو فیلد را در این بخش اضافه می‌کنید.

Field To Aggregate

  • نام پارامتر: Field To Aggregate
  • نوع داده: String
  • کاربرد: نام فیلدی که باید از هر آیتم ورودی برداشته شود.
  • مثال عملی: برای تجمیع ایمیل‌ها مقدار این پارامتر را برابر email قرار دهید.
  • نمونه: اگر ورودی شامل فیلد customer.email باشد، می‌توانید از مسیر نقطه‌ای استفاده کنید؛ البته در صورت فعال بودن Dot Notation.

Rename Field

  • نام پارامتر: Rename Field
  • نوع داده: Boolean / روشن یا خاموش
  • کاربرد: مشخص می‌کند نام فیلد خروجی با نام فیلد ورودی یکی باشد یا نام جدیدی برای آن تعریف شود.
  • مثال عملی: اگر فیلد ورودی email است اما می‌خواهید در خروجی با نام emails ذخیره شود، این گزینه را فعال کنید.

Output Field Name

  • نام پارامتر: Output Field Name
  • نوع داده: String
  • کاربرد: نام فیلد خروجی را مشخص می‌کند.
  • زمان استفاده: زمانی که Rename Field فعال باشد یا زمانی که باید داده‌ها در یک فیلد مشخص ذخیره شوند.
  • مثال عملی: اگر فیلد email را تجمیع می‌کنید، بهتر است نام خروجی را emails قرار دهید تا مشخص باشد خروجی یک آرایه است.

Destination Field Name

  • نام پارامتر: Destination Field Name
  • نوع داده: String
  • کاربرد: نام فیلدی که همه آیتم‌ها به‌صورت یک آرایه در آن ذخیره می‌شوند.
  • زمان استفاده: زمانی که حالت Aggregate روی All Item Data Into a Single List باشد.
  • مثال عملی: اگر می‌خواهید همه سفارش‌ها در خروجی داخل فیلدی به نام orders قرار بگیرند، مقدار این پارامتر را orders تنظیم کنید.

Include

  • نام پارامتر: Include
  • نوع داده: انتخابی / Dropdown
  • کاربرد: مشخص می‌کند هنگام تجمیع کل داده‌ها، کدام فیلدها در خروجی قرار بگیرند.
  • گزینه‌های رایج:
    • All Fields: تمام فیلدهای هر آیتم در لیست خروجی قرار می‌گیرند.
    • Specified Fields: فقط فیلدهای مشخص‌شده وارد خروجی می‌شوند.
    • All Fields Except: همه فیلدها به‌جز فیلدهای مشخص‌شده وارد خروجی می‌شوند.
  • مثال عملی: اگر هر آیتم شامل id، name، email و password است، با All Fields Except می‌توانید password را حذف کنید.

Fields To Include

  • نام پارامتر: Fields To Include
  • نوع داده: String یا لیست فیلدها
  • کاربرد: مشخص می‌کند فقط کدام فیلدها در خروجی تجمیع‌شده قرار بگیرند.
  • زمان استفاده: زمانی که Include روی Specified Fields قرار داشته باشد.
  • مثال عملی: مقدار id,name,email باعث می‌شود فقط این سه فیلد در آرایه خروجی ذخیره شوند.

Fields To Exclude

  • نام پارامتر: Fields To Exclude
  • نوع داده: String یا لیست فیلدها
  • کاربرد: مشخص می‌کند کدام فیلدها از خروجی حذف شوند.
  • زمان استفاده: زمانی که Include روی All Fields Except قرار داشته باشد.
  • مثال عملی: مقدار password,token,internalNote باعث حذف فیلدهای حساس از خروجی می‌شود.

Keep Missing And Null Values

  • نام پارامتر: Keep Missing And Null Values
  • نوع داده: Boolean
  • کاربرد: مشخص می‌کند اگر بعضی آیتم‌ها فیلد موردنظر را نداشتند یا مقدار آن null بود، آن مقدار در آرایه خروجی حفظ شود یا نادیده گرفته شود.
  • مثال عملی: اگر ۵ آیتم دارید و در دو آیتم فیلد email خالی است، با فعال بودن این گزینه ممکن است خروجی شامل null نیز باشد.
  • نکته مهم: اگر ترتیب آیتم‌ها برای شما مهم است، حفظ مقدارهای null می‌تواند کمک کند جایگاه داده‌ها در آرایه تغییر نکند.

Merge Lists

  • نام پارامتر: Merge Lists
  • نوع داده: Boolean
  • کاربرد: اگر فیلدهای ورودی خودشان آرایه باشند، این گزینه می‌تواند آن‌ها را به‌جای ساخت آرایه‌ای از آرایه‌ها، در یک لیست واحد ادغام کند.
  • مثال عملی: اگر هر آیتم شامل فیلد tags باشد و tags یک آرایه باشد، با Merge Lists می‌توانید همه tagها را در یک آرایه یکپارچه جمع کنید.

Disable Dot Notation

  • نام پارامتر: Disable Dot Notation
  • نوع داده: Boolean
  • کاربرد: مشخص می‌کند نقطه در نام فیلد به‌عنوان مسیر آبجکت تفسیر شود یا بخشی از نام واقعی فیلد باشد.
  • مثال عملی: اگر فیلدی با نام واقعی user.email دارید، فعال کردن Disable Dot Notation باعث می‌شود N8N آن را به‌عنوان یک کلید ساده در نظر بگیرد، نه مسیر user سپس email.

Include Binary Data

  • نام پارامتر: Include Binary Data
  • نوع داده: Boolean
  • کاربرد: مشخص می‌کند داده‌های باینری همراه آیتم‌ها نیز در خروجی تجمیع‌شده لحاظ شوند یا نه.
  • مثال عملی: اگر آیتم‌های ورودی شامل فایل، تصویر یا PDF هستند و می‌خواهید همراه داده‌های JSON منتقل شوند، این گزینه اهمیت دارد.
  • نکته مهم: نگهداری داده‌های باینری در تجمیع‌های بزرگ می‌تواند مصرف حافظه ورکفلو را افزایش دهد.

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

  • اگر قصد ارسال داده به API دارید، نام فیلد خروجی را مطابق ساختار مورد انتظار API انتخاب کنید.
  • برای فیلدهایی که آرایه هستند، رفتار Merge Lists را بررسی کنید تا خروجی ناخواسته به‌صورت آرایه تو در تو ساخته نشود.
  • اگر داده‌های ورودی بزرگ هستند، از تجمیع بیش از حد در یک آیتم خودداری کنید؛ چون ممکن است مصرف حافظه بالا برود.
  • اگر فیلدهای حساس مثل password، token یا apiKey در داده‌ها وجود دارند، قبل از Aggregate آن‌ها را با Set یا Edit Fields حذف کنید.
  • اگر از نام فیلدهای دارای نقطه استفاده می‌کنید، وضعیت Disable Dot Notation را با دقت تنظیم کنید.

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

ساختار ورودی

نود Aggregate معمولاً چندین آیتم ورودی دریافت می‌کند. هر آیتم در N8N معمولاً یک آبجکت JSON دارد. برای مثال خروجی یک نود Google Sheets، HTTP Request یا دیتابیس می‌تواند به‌شکل زیر باشد:

[  {    "json": {      "id": 1,      "name": "Ali",      "email": "ali@example.com",      "amount": 250000    }  },  {    "json": {      "id": 2,      "name": "Sara",      "email": "sara@example.com",      "amount": 430000    }  },  {    "json": {      "id": 3,      "name": "Reza",      "email": "reza@example.com",      "amount": 180000    }  }]

خروجی در حالت Individual Fields

اگر در حالت Individual Fields فیلدهای email و amount را تجمیع کنید، خروجی می‌تواند به‌شکل زیر باشد:

[  {    "json": {      "email": [        "ali@example.com",        "sara@example.com",        "reza@example.com"      ],      "amount": [        250000,        430000,        180000      ]    }  }]

اگر Rename Field را فعال کنید و نام خروجی email را به emails تغییر دهید، خروجی به‌شکل زیر خواهد بود:

[  {    "json": {      "emails": [        "ali@example.com",        "sara@example.com",        "reza@example.com"      ]    }  }]

خروجی در حالت All Item Data Into a Single List

اگر کل آیتم‌ها را داخل فیلدی به نام customers یا orders تجمیع کنید، خروجی معمولاً یک آیتم شامل یک آرایه خواهد بود:

[  {    "json": {      "customers": [        {          "id": 1,          "name": "Ali",          "email": "ali@example.com",          "amount": 250000        },        {          "id": 2,          "name": "Sara",          "email": "sara@example.com",          "amount": 430000        },        {          "id": 3,          "name": "Reza",          "email": "reza@example.com",          "amount": 180000        }      ]    }  }]

نمونه کاربرد در HTTP Request

فرض کنید API مقصد چنین بدنه‌ای می‌خواهد:

{  "source": "n8n",  "orders": [    {      "id": 1,      "amount": 250000    },    {      "id": 2,      "amount": 430000    }  ]}

برای ساخت این ساختار، می‌توانید ابتدا با Aggregate داده‌ها را داخل فیلد orders قرار دهید و سپس با نود Set یا Edit Fields مقدار source را اضافه کنید.

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

۱. استفاده از Aggregate قبل از ارسال batch به API

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

  • HTTP Request برای دریافت داده‌ها
  • Set برای پاک‌سازی و استانداردسازی فیلدها
  • Aggregate برای ساخت آرایه نهایی
  • HTTP Request برای ارسال batch

۲. ترکیب Aggregate با Code برای محاسبه گزارش

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

const orders = $json.orders;const totalAmount = orders.reduce((sum, order) => {  return sum + order.amount;}, 0);return [  {    json: {      totalOrders: orders.length,      totalAmount    }  }];

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

۳. حذف فیلدهای اضافی قبل از Aggregate

اگر داده‌های ورودی فیلدهای زیادی دارند، بهتر است قبل از Aggregate با نود Set یا Edit Fields فقط فیلدهای لازم را نگه دارید. این کار باعث سبک‌تر شدن خروجی و کاهش مصرف حافظه می‌شود.

  • حذف فیلدهای سیستمی
  • حذف token و اطلاعات حساس
  • حذف توضیحات طولانی یا داده‌های غیرضروری
  • نگه‌داشتن فقط فیلدهای موردنیاز API مقصد

۴. استفاده از Aggregate برای ساخت لیست ایمیل

اگر چند آیتم کاربر دارید و فقط می‌خواهید فهرست ایمیل‌ها را بسازید، حالت Individual Fields بهترین انتخاب است. فیلد email را انتخاب کنید و خروجی را با نام emails ذخیره کنید.

{  "emails": [    "ali@example.com",    "sara@example.com",    "reza@example.com"  ]}

این خروجی برای ارسال به سرویس‌های ایمیل مارکتینگ، CRM یا سیستم‌های اعلان گروهی مناسب است.

۵. کنترل آرایه‌های تو در تو با Merge Lists

اگر آیتم‌های ورودی شما شامل آرایه هستند، خروجی Aggregate ممکن است به‌صورت آرایه‌ای از آرایه‌ها ساخته شود. برای مثال:

{  "tags": [    ["new", "vip"],    ["paid", "returning"]  ]}

با فعال کردن Merge Lists می‌توان خروجی را به شکل ساده‌تر تبدیل کرد:

{  "tags": [    "new",    "vip",    "paid",    "returning"  ]}

۶. ترکیب با IF برای فیلتر قبل از تجمیع

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

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

۷. استفاده از Aggregate بعد از Loop

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

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

محدودیت‌های نود Aggregate

  • عدم انجام محاسبات آماری پیشرفته: Aggregate برای ساخت آرایه و تجمیع ساختاری داده استفاده می‌شود، نه برای محاسبه مستقیم مجموع، میانگین، حداقل یا حداکثر. برای این کار می‌توانید از Code یا نودهای مخصوص خلاصه‌سازی داده استفاده کنید.
  • مصرف حافظه در داده‌های بزرگ: اگر هزاران یا میلیون‌ها آیتم را در یک آیتم واحد تجمیع کنید، ممکن است مصرف حافظه بالا برود.
  • وابستگی به ساختار درست ورودی: اگر فیلدهای ورودی در همه آیتم‌ها یکسان نباشند، خروجی ممکن است شامل مقدارهای خالی، null یا آرایه‌های نامنظم شود.
  • عدم گروه‌بندی پیچیده به‌صورت پیش‌فرض: اگر می‌خواهید داده‌ها را بر اساس customerId، category یا status گروه‌بندی کنید، ممکن است نیاز به استفاده از Code، Item Lists، Summarize یا ترکیب چند نود داشته باشید.
  • احتمال تولید آرایه‌های تو در تو: هنگام تجمیع فیلدهایی که خودشان آرایه هستند، باید تنظیمات Merge Lists را بررسی کنید.

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

علت احتمالی: نام فیلد در Field To Aggregate اشتباه وارد شده یا مسیر فیلد با ساختار واقعی داده مطابقت ندارد.

راه‌حل: خروجی نود قبلی را بررسی کنید و نام دقیق فیلد را کپی کنید. اگر فیلد داخل آبجکت nested است، مسیر آن را درست وارد کنید؛ برای مثال customer.email.

خطای رایج: مقدارها null شده‌اند

علت احتمالی: برخی آیتم‌ها فیلد موردنظر را ندارند یا مقدار آن‌ها واقعاً null است.

راه‌حل: قبل از Aggregate با IF، Filter یا Set داده‌ها را پاک‌سازی کنید. همچنین وضعیت گزینه Keep Missing And Null Values را بررسی کنید.

خطای رایج: خروجی آرایه‌ای از آرایه‌ها است

علت احتمالی: فیلدی که تجمیع می‌کنید خودش در هر آیتم یک آرایه است.

راه‌حل: گزینه Merge Lists را فعال کنید یا بعد از Aggregate با Code آرایه‌ها را flatten کنید.

const tags = $json.tags.flat();return [  {    json: {      tags    }  }];

خطای رایج: API مقصد payload را قبول نمی‌کند

علت احتمالی: ساختار خروجی Aggregate با ساختار مورد انتظار API یکی نیست. برای مثال API فیلد orders می‌خواهد، اما خروجی شما data یا items است.

راه‌حل: نام Destination Field Name را مطابق مستندات API تنظیم کنید. در صورت نیاز از Set یا Edit Fields برای ساخت ساختار نهایی استفاده کنید.

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

علت احتمالی: تعداد آیتم‌ها زیاد است یا داده‌های حجیم مثل فایل و باینری همراه آیتم‌ها تجمیع می‌شوند.

راه‌حل: داده‌ها را batch کنید، فیلدهای غیرضروری را حذف کنید و از Include Binary Data فقط زمانی استفاده کنید که واقعاً لازم است.

ایده ها

  • ساخت گزارش روزانه فروش: دریافت سفارش‌ها از دیتابیس، تجمیع آن‌ها با Aggregate، محاسبه مجموع با Code و ارسال گزارش با ایمیل یا Slack.
  • ارسال کاربران جدید به CRM به‌صورت batch: خواندن کاربران از Google Sheets یا دیتابیس، تجمیع آن‌ها در فیلد users و ارسال به CRM با HTTP Request.
  • ساخت لیست ایمیل برای کمپین: استخراج ایمیل کاربران فعال، تجمیع در آرایه emails و ارسال به سرویس ایمیل مارکتینگ.
  • تجمیع لاگ‌های خطا: جمع‌آوری خطاهای چند سرویس، تجمیع در یک آرایه و ارسال خلاصه به تیم فنی در Slack یا Telegram.
  • ساخت payload برای هوش مصنوعی: جمع‌آوری چند متن، نظر مشتری یا تیکت پشتیبانی در یک آرایه و ارسال آن‌ها به مدل AI برای خلاصه‌سازی یا تحلیل احساسات.

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

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

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

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

سیزده + 3 =