فصلِ 5

تبدیل داده: شکل‌دادن به جریان

قلبِ اکثرِ گردش‌کارها: داده را از شکلی که هست به شکلی که سرویسِ بعدی می‌خواهد دربیاوری.

Edit Fields (Set) — نانِ روزانه

افزودن، تغییرنام، حذف و ثابت‌کردنِ فیلدها.

نودِ Edit Fields (که قبلاً Set نام داشت) پرکاربردترین نودِ تبدیل است. با آن یک ساختارِ تمیز می‌سازی: فقط فیلدهایی که می‌خواهی، با نام و مقدارِ دلخواه. حالتِ Keep Only Set هر چیزِ اضافه را دور می‌ریزد — برای تمیزنگه‌داشتنِ داده قبل از ذخیره عالی است.

نودِ Code — وقتی منطق واقعی می‌خواهی

JavaScript یا Python، با دو حالتِ اجرا.

دو حالت دارد و انتخابش مهم است:

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

// حالتِ All Items — باید آرایه‌ای از {json} برگردانی
const items = $input.all();
return items.map(i => ({
  json: { name: i.json.name.toUpperCase(), seen: true }
}));

قراردادِ خروجی

نودِ Code همیشه باید آرایه‌ای از آیتم برگرداند که هرکدام کلیدِ json دارند. فراموش‌کردنِ این ساختار، شایع‌ترین خطای نودِ کد است — اگر شیءِ خام برگردانی، n8n شکایت می‌کند.

شکستن، جمع‌کردن و ادغام

سه نودی که تعدادِ آیتم‌ها را عوض می‌کنند.

نود	کارش
Split Out	یک فیلدِ آرایه‌ای را به چند آیتمِ جدا باز می‌کند
Aggregate	چند آیتم را در یک آیتم (یا یک آرایه) جمع می‌کند
Merge	دو شاخهٔ ورودی را کنارِ هم می‌گذارد یا تطبیق می‌دهد

مثال: از یک API یک آیتم می‌گیری که فیلدِ resultsـش آرایه‌ای ۲۰تایی است. Split Out رویِ results آن را به ۲۰ آیتم تبدیل می‌کند تا نودِ بعدی برای هرکدام جدا کار کند.

حلقهٔ صریح با Loop Over Items

وقتی باید دسته‌دسته پیش بروی.

گرچه n8n خودش روی آیتم‌ها حلقه می‌زند، گاهی نیاز به کنترلِ دستی داری — مثلاً پردازشِ ۱۰۰۰ آیتم در دسته‌های ۵۰تایی برای احترام به محدودیتِ نرخِ یک API. نودِ Loop Over Items (پیش‌تر Split in Batches) این را ممکن می‌کند: بدنهٔ حلقه اجرا می‌شود، به ابتدای حلقه برمی‌گردد، تا وقتی همهٔ دسته‌ها تمام شوند.