نود Split Out در N8N

نود Split Out یکی از نودهای کاربردی برای تبدیل آرایه‌ها به آیتم‌های جداگانه در n8n است. وقتی داده‌ای دارید که داخل یک فیلد آن چند مقدار به‌صورت آرایه قرار گرفته، این نود می‌تواند هر عضو آرایه را به یک آیتم مستقل تبدیل کند تا پردازش، فیلتر، ذخیره‌سازی یا ارسال آن به سرویس‌های دیگر ساده‌تر شود.

معرفی نود در N8N

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

نوع نود: Function / Data Transformation
دسته‌بندی کاربردی: نود داخلی n8n برای تبدیل ساختار داده
کار اصلی: تبدیل یک آرایه داخل یک آیتم به چند آیتم جداگانه
اهمیت در ورکفلوها: بسیاری از APIها داده‌ها را به‌صورت آرایه برمی‌گردانند. برای پردازش تک‌به‌تک اعضای این آرایه‌ها، نود Split Out بسیار مهم است.

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

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

نود Split Out در پروژه‌های واقعی بسیار پرکاربرد است، مخصوصاً زمانی که با APIها، فایل‌های JSON، خروجی دیتابیس‌ها یا داده‌های جمع‌آوری‌شده از وب سروکار دارید.

۱. پردازش لیست سفارش‌ها

فرض کنید یک فروشگاه اینترنتی از API خود خروجی زیر را برمی‌گرداند:

{  "customerId": 125,  "customerName": "Ali Rezaei",  "orders": [    {      "id": 1001,      "amount": 450000    },    {      "id": 1002,      "amount": 720000    }  ]}

با Split Out روی فیلد orders، هر سفارش به یک آیتم جداگانه تبدیل می‌شود. سپس می‌توانید هر سفارش را به Google Sheets، CRM، دیتابیس یا سیستم حسابداری ارسال کنید.

۲. ارسال پیام جداگانه برای هر کاربر

اگر یک فیلد به نام users شامل لیستی از کاربران باشد، با Split Out می‌توانید برای هر کاربر یک آیتم جدا بسازید و سپس با نودهایی مثل Email، Telegram، Slack یا HTTP Request برای هر شخص پیام اختصاصی ارسال کنید.

۳. ذخیره محصولات در دیتابیس

بسیاری از APIهای فروشگاهی مثل Shopify، WooCommerce یا سیستم‌های اختصاصی، محصولات را به‌صورت آرایه برمی‌گردانند. با Split Out می‌توانید هر محصول را به یک ردیف مستقل در دیتابیس تبدیل کنید.

۴. ترکیب با نود HTTP Request

یکی از رایج‌ترین ترکیب‌ها، استفاده از Split Out بعد از نود HTTP Request است. ابتدا داده از API دریافت می‌شود، سپس فیلد آرایه‌ای با Split Out شکسته می‌شود و بعد آیتم‌ها یکی‌یکی پردازش می‌شوند.

HTTP Request: دریافت لیست کاربران
Split Out: تبدیل آرایه users به آیتم‌های جدا
IF: بررسی فعال بودن هر کاربر
Email یا Telegram: ارسال پیام به کاربران فعال

۵. ترکیب با نود Loop Over Items

بعد از Split Out می‌توانید از نود Loop Over Items استفاده کنید تا روی هر آیتم جداشده، عملیات مرحله‌به‌مرحله انجام شود. این روش برای پردازش حجم زیاد داده یا انجام درخواست‌های پشت‌سرهم به APIها مفید است.

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

تنظیمات نود Split Out ساده است، اما انتخاب درست فیلدها و گزینه‌های خروجی تأثیر زیادی روی کیفیت داده نهایی دارد.

Fields To Split Out

نوع داده: String / Field Name
کاربرد: مشخص می‌کند کدام فیلد آرایه‌ای باید به آیتم‌های جداگانه تبدیل شود.
مثال: اگر داده ورودی شامل فیلد orders باشد، مقدار این پارامتر را orders قرار دهید.
نکته: فیلدی که انتخاب می‌کنید باید آرایه باشد. اگر مقدار آن رشته، عدد یا آبجکت غیرآرایه باشد، نتیجه ممکن است خطا بدهد یا خروجی مورد انتظار تولید نشود.

Add Field To Split Out

نوع داده: لیست فیلدها
کاربرد: امکان انتخاب بیش از یک فیلد برای Split Out را فراهم می‌کند.
مثال: در داده‌ای که دو آرایه هم‌طول به نام‌های names و emails دارد، می‌توانید هر دو را برای جدا کردن انتخاب کنید.
نکته مهم: هنگام Split کردن چند فیلد، بهتر است طول آرایه‌ها با هم هماهنگ باشد تا داده‌های خروجی ساختار قابل پیش‌بینی داشته باشند.

Include

نوع داده: انتخابی / Dropdown
کاربرد: مشخص می‌کند در خروجی، علاوه بر داده‌های جداشده، چه فیلدهای دیگری از آیتم اصلی نگه داشته شوند.
گزینه‌ها:
No Other Fields: فقط فیلد Split شده در خروجی قرار می‌گیرد و سایر فیلدهای آیتم اصلی حذف می‌شوند.
All Other Fields: تمام فیلدهای دیگر آیتم اصلی در کنار فیلد Split شده نگه داشته می‌شوند.
Selected Other Fields: فقط فیلدهایی که خودتان مشخص می‌کنید در خروجی باقی می‌مانند.
مثال: اگر فیلد customerId باید همراه هر سفارش باقی بماند، گزینه All Other Fields یا Selected Other Fields را انتخاب کنید.

Fields To Include

نوع داده: String / Field Name
کاربرد: زمانی نمایش داده می‌شود که در گزینه Include مقدار Selected Other Fields را انتخاب کرده باشید.
مثال: برای نگه داشتن فقط شناسه و نام مشتری، مقدارهای customerId و customerName را انتخاب کنید.
نکته: این گزینه برای تمیز نگه داشتن خروجی بسیار مفید است، چون از انتقال فیلدهای غیرضروری به مراحل بعد جلوگیری می‌کند.

Destination Field Name

نوع داده: String
کاربرد: نام فیلدی را مشخص می‌کند که مقدار جداشده داخل آن قرار بگیرد.
مثال: اگر فیلد اصلی orders باشد، می‌توانید نام خروجی را order قرار دهید تا هر آیتم خروجی فیلدی به نام order داشته باشد.
کاربرد عملی: تبدیل نام جمع به مفرد برای خوانایی بهتر. مثلاً products به product یا users به user.

Include Binary

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

Disable Dot Notation

نوع داده: Boolean
کاربرد: تعیین می‌کند نقطه در نام فیلدها به‌عنوان مسیر آبجکت در نظر گرفته شود یا بخشی از نام واقعی فیلد باشد.
حالت پیش‌فرض: در n8n معمولاً Dot Notation فعال است. یعنی data.items به معنی فیلد items داخل آبجکت data است.
مثال با Dot Notation: اگر ساختار داده شما { "data": { "items": [] } } باشد، می‌توانید مسیر data.items را وارد کنید.
مثال با Disable Dot Notation: اگر نام واقعی فیلد شما دقیقاً data.items است و آبجکت تو در تو نیست، باید Disable Dot Notation را فعال کنید.

جدول خلاصه پارامترها

نام پارامتر	نوع داده	کاربرد	مثال عملی
Fields To Split Out	String / Field Name	انتخاب فیلد آرایه‌ای برای تبدیل به آیتم‌های جدا	orders
Add Field To Split Out	List	اضافه کردن چند فیلد برای Split	names و emails
Include	Dropdown	تعیین فیلدهای اضافی در خروجی	All Other Fields
Fields To Include	String / Field Name	نگه داشتن فیلدهای انتخابی از آیتم اصلی	customerId, customerName
Destination Field Name	String	تعیین نام فیلد خروجی برای مقدار جداشده	order
Include Binary	Boolean	انتقال داده‌های باینری به خروجی	true
Disable Dot Notation	Boolean	غیرفعال کردن تفسیر نقطه به‌عنوان مسیر آبجکت	true

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

نود Split Out یک یا چند آیتم ورودی دریافت می‌کند. در هر آیتم، فیلدی که برای Split مشخص شده باید آرایه باشد. سپس به تعداد اعضای آن آرایه، آیتم خروجی تولید می‌شود.

نمونه ورودی ساده

[  {    "json": {      "customerId": 12,      "customerName": "Sara Ahmadi",      "orders": [        {          "orderId": 501,          "total": 300000        },        {          "orderId": 502,          "total": 850000        },        {          "orderId": 503,          "total": 120000        }      ]    }  }]

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

Fields To Split Out: orders
Include: All Other Fields
Destination Field Name: order

نمونه خروجی

[  {    "json": {      "customerId": 12,      "customerName": "Sara Ahmadi",      "order": {        "orderId": 501,        "total": 300000      }    }  },  {    "json": {      "customerId": 12,      "customerName": "Sara Ahmadi",      "order": {        "orderId": 502,        "total": 850000      }    }  },  {    "json": {      "customerId": 12,      "customerName": "Sara Ahmadi",      "order": {        "orderId": 503,        "total": 120000      }    }  }]

نمونه ورودی با آرایه داخل آبجکت تو در تو

{  "data": {    "products": [      {        "sku": "A-100",        "name": "Keyboard"      },      {        "sku": "B-200",        "name": "Mouse"      }    ]  },  "source": "store-api"}

در این حالت، اگر Dot Notation فعال باشد، مقدار data.products را در Fields To Split Out وارد می‌کنید.

نمونه خروجی برای داده تو در تو

[  {    "json": {      "source": "store-api",      "product": {        "sku": "A-100",        "name": "Keyboard"      }    }  },  {    "json": {      "source": "store-api",      "product": {        "sku": "B-200",        "name": "Mouse"      }    }  }]

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

۱. قبل از Split Out ساختار داده را تمیز کنید

اگر داده‌ای که از API دریافت می‌کنید پیچیده است، بهتر است قبل از Split Out از نودهای Set، Edit Fields یا Code استفاده کنید تا فقط فیلدهای موردنیاز را نگه دارید. این کار باعث می‌شود خروجی Split Out ساده‌تر، سبک‌تر و قابل کنترل‌تر باشد.

۲. استفاده از Destination Field Name برای خوانایی بهتر

اگر فیلد ورودی به‌صورت جمع است، بهتر است نام خروجی را مفرد کنید. این کار در مراحل بعدی ورکفلو خوانایی Expressionها را بهتر می‌کند.

users به user
orders به order
products به product
tasks به task

۳. ترکیب با IF برای فیلتر کردن آیتم‌های جداشده

بعد از Split Out می‌توانید از نود IF استفاده کنید تا فقط آیتم‌هایی که شرایط خاصی دارند ادامه پیدا کنند.

فقط سفارش‌های بالای ۵۰۰ هزار تومان
فقط کاربران فعال
فقط محصولات دارای موجودی
فقط تسک‌هایی که وضعیت آن‌ها pending است

۴. ترکیب با Merge برای اتصال داده‌ها

اگر پس از Split Out لازم است داده‌های جداشده را با داده‌های دیگری ترکیب کنید، نود Merge می‌تواند مفید باشد. برای مثال، ابتدا لیست سفارش‌ها را Split کنید و سپس اطلاعات هر سفارش را با اطلاعات مشتری از منبع دیگری ترکیب کنید.

۵. کنترل حجم داده با Limit و Loop

اگر یک آرایه بسیار بزرگ را Split کنید، تعداد آیتم‌های خروجی زیاد می‌شود. برای جلوگیری از فشار روی سیستم یا محدودیت APIها، می‌توانید بعد از Split Out از نودهای Limit، Loop Over Items یا تنظیمات Batch استفاده کنید.

۶. Split کردن داده‌های APIهای صفحه‌بندی‌شده

در APIهایی که خروجی آن‌ها شامل فیلدهایی مثل data، items یا results است، Split Out معمولاً بعد از دریافت هر صفحه استفاده می‌شود. سپس با Loop یا Pagination می‌توان تمام صفحات را دریافت و آیتم‌ها را جداگانه پردازش کرد.

۷. حفظ شناسه منبع در خروجی

هنگام Split کردن آرایه‌ها، بهتر است شناسه رکورد اصلی را در خروجی نگه دارید. برای مثال اگر هر مشتری چند سفارش دارد، با نگه داشتن customerId در خروجی می‌توانید بعداً سفارش‌ها را به مشتری مربوطه وصل کنید.

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

۱. فیلد انتخاب‌شده آرایه نیست

یکی از خطاهای رایج این است که فیلدی که در Fields To Split Out وارد شده، آرایه نیست. Split Out برای داده‌های آرایه‌ای طراحی شده است.

علت: مقدار فیلد رشته، عدد، null یا آبجکت معمولی است.
راه‌حل: قبل از Split Out با نود IF یا Code بررسی کنید که مقدار فیلد واقعاً آرایه باشد.

۲. مسیر فیلد اشتباه است

اگر داده شما تو در تو باشد، باید مسیر درست را وارد کنید.

اشتباه: items
درست: data.items

البته این موضوع زمانی درست است که آرایه داخل آبجکت data قرار داشته باشد.

۳. مشکل با نقطه در نام فیلد

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

مثال نام فیلد: user.list
راه‌حل: گزینه Disable Dot Notation را فعال کنید.

۴. تولید تعداد زیاد آیتم خروجی

اگر آرایه ورودی بسیار بزرگ باشد، Split Out ممکن است تعداد زیادی آیتم تولید کند. این موضوع می‌تواند باعث کند شدن اجرای ورکفلو یا مصرف زیاد حافظه شود.

راه‌حل: از Pagination، Batch Processing، Loop Over Items یا Limit استفاده کنید.
راه‌حل تکمیلی: قبل از Split Out فقط فیلدهای ضروری را نگه دارید.

۵. حذف ناخواسته فیلدهای مهم

اگر گزینه Include روی No Other Fields باشد، فقط مقدار Split شده در خروجی باقی می‌ماند و سایر فیلدهای آیتم اصلی حذف می‌شوند.

راه‌حل: برای نگه داشتن فیلدهای مهم، گزینه All Other Fields یا Selected Other Fields را انتخاب کنید.

۶. ناهماهنگی هنگام Split کردن چند آرایه

اگر چند فیلد آرایه‌ای را هم‌زمان Split می‌کنید، باید به طول و ترتیب اعضای آرایه‌ها دقت کنید. ناهماهنگی می‌تواند باعث خروجی‌های غیرمنتظره شود.

راه‌حل: قبل از Split Out ساختار آرایه‌ها را با Code یا Set استاندارد کنید.

ایده ها

سیستم ارسال پیام انبوه هوشمند: دریافت لیست کاربران از API، Split کردن آرایه کاربران، فیلتر کاربران فعال و ارسال پیام شخصی‌سازی‌شده از طریق Telegram یا Email.
ثبت خودکار سفارش‌ها در Google Sheets: دریافت آرایه سفارش‌ها از فروشگاه آنلاین، تبدیل هر سفارش به یک آیتم جدا و ذخیره هر سفارش در یک ردیف مستقل.
مانیتورینگ محصولات ناموجود: دریافت لیست محصولات، Split کردن محصولات، بررسی موجودی با IF و ارسال هشدار برای کالاهای ناموجود.
ساخت سیستم پردازش تسک‌ها: دریافت آرایه‌ای از وظایف، Split کردن هر تسک، اختصاص به اعضای تیم در ابزارهایی مثل Trello، Notion یا Asana.
پردازش نتایج فرم‌های چندگزینه‌ای: دریافت پاسخ‌های فرم که شامل آرایه‌ای از انتخاب‌هاست، Split کردن گزینه‌ها و تحلیل جداگانه هر پاسخ در دیتابیس یا ابزار گزارش‌گیری.