دستکاری JSON در n8n (۱۴۰۴): راهنمای کامل مپ کردن آرایه‌ها و آبجکت‌های پیچیده

یک وب‌هوک از درگاه پرداخت دریافت کرده‌اید که آرایه‌ای از items تودرتو دارد. شما فقط به SKU محصولاتی نیاز دارید که وضعیتشان paid است و باید آنها را در CRM ثبت کنید.

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

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

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

جعبه ابزار جراحی JSON در n8n: آشنایی با نودهای کلیدی

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

۱. نود Set: این نود، چاقوی سوئیسی شما برای کارهای ساده است. از آن برای ایجاد متغیرهای جدید، تغییر مقادیر موجود یا دسترسی سریع به یک فیلد خاص استفاده می‌کنید. Set برای کارهای مستقیم و بدون منطق پیچیده، ایده‌آل است.

۲. نود Code: این نود، اتاق عمل اصلی شماست. هر زمان که نیاز به منطق پیچیده، حلقه‌ها، شرط‌ها یا توابع پیشرفته جاوااسکریپت برای پردازش آرایه‌ها و آبجکت‌ها دارید، به سراغ نود Code می‌روید. تمام تکنیک‌های پیشرفته‌ای که در این مقاله بررسی می‌کنیم، در این نود پیاده‌سازی می‌شوند.

۳. نود Item Lists: این نود مجموعه‌ای از عملیات‌های از پیش آماده‌شده روی آرایه‌ها (لیست آیتم‌ها) را ارائه می‌دهد. کارهایی مثل تقسیم یک لیست بزرگ به چند لیست کوچک‌تر (Split)، مرتب‌سازی (Sort)، خلاصه‌سازی (Summarize) یا حذف موارد تکراری (Remove Duplicates) را بدون نیاز به یک خط کدنویسی انجام می‌دهد.

در تجربه ما در کارورا، ترکیبی هوشمندانه از این سه نود، قدرتمندترین نتیجه را به همراه دارد. برای کارهای ساده از Set و Item Lists و برای جراحی‌های دقیق و پیچیده از Code استفاده کنید.

قدم اول: تشریح جسد داده – دسترسی به آبجکت‌ها (Accessing & Parsing)

قبل از هر دستکاری پیچیده‌ای، باید بتوانیم به داده‌های مورد نظرمان به شکلی قابل اعتماد دسترسی پیدا کنیم. فرض کنید یک نود Webhook داده زیر را دریافت کرده است:

{
“customer”: {
“id”: “cus_12345”,
“email”: “arash.dev@example.com”,
“first-name”: “Arash”
},
“transaction_id”: “txn_abcde”
}

n8n دو روش اصلی برای دسترسی به این مقادیر در Expression Editor (ویرایشگر عبارت) در اختیار شما قرار می‌دهد:

۱. Dot Notation (نشانه‌گذاری نقطه‌ای):
این روش استاندارد و خواناترین حالت است. شما با استفاده از نقطه (.) بین سطوح مختلف آبجکت حرکت می‌کنید.

۲. Bracket Notation (نشانه‌گذاری براکتی):
این روش زمانی حیاتی می‌شود که کلید (key) شما شامل کاراکترهای خاصی باشد که در جاوااسکریپت مجاز نیستند (مانند خط تیره -، فاصله یا شروع شدن با عدد).

در مثال ما، کلید first-name دارای خط تیره است. استفاده از Dot Notation برای آن ($json.customer.first-name) منجر به خطا می‌شود. راه حل صحیح، استفاده از Bracket Notation است:

قانون سرانگشتی: همیشه از Dot Notation استفاده کنید، مگر اینکه کلید شما حاوی کاراکترهای غیرمجاز باشد. در آن صورت، Bracket Notation تنها راه حل شماست. در پروژه‌های واقعی، APIهای زیادی وجود دارند که از چنین کلیدهایی استفاده می‌کنند، بنابراین تسلط بر این تکنیک ضروری است.

قدم دوم: رام کردن آرایه‌ها (Array Manipulation)

اینجا جایی است که قدرت واقعی n8n و جاوااسکریپت نمایان می‌شود. اکثر داده‌های ارزشمند در APIها به شکل آرایه‌ای از آبجکت‌ها ارائه می‌شوند: لیست محصولات، لیست کاربران، لیست سفارشات و… ما سه عملیات حیاتی filter, map و reduce را با استفاده از نود Code بررسی می‌کنیم.

⚠️ نکته فنی مهم: در کدهای زیر ما از استاندارد جدید n8n v1 ($input.all()) استفاده می‌کنیم تا مطمئن شویم کد شما روی تمام آیتم‌های ورودی به درستی اجرا می‌شود.

۱. فیلتر کردن (Filtering): جداسازی سیگنال از نویز

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

داده ورودی (از نود قبلی):

[
{ “id”: 1, “email”: “user1@test.com”, “last_login”: “2026-08-20T10:00:00Z” },
{ “id”: 2, “email”: “user2@test.com”, “last_login”: “2026-08-18T15:30:00Z” },
{ “id”: 3, “email”: “user3@test.com”, “last_login”: “2026-08-20T22:00:00Z” },
{ “id”: 4, “email”: “user4@test.com”, “last_login”: “2026-07-01T11:00:00Z” }
]

کد در نود Code:
javascript
// در n8n v1+ برای دسترسی به همه آیتم‌های ورودی از $input.all() استفاده می‌کنیم
const allUsers = $input.all().map(item => item.json);

// تاریخ 24 ساعت پیش را محاسبه می‌کنیم
const yesterday = new Date();
yesterday.setDate(yesterday.getDate() – 1);

// با استفاده از متد filter، آرایه را پیمایش می‌کنیم
const recentUsers = allUsers.filter(user => {
// برای هر کاربر، تاریخ آخرین لاگین را به یک آبجکت Date تبدیل می‌کنیم
const lastLoginDate = new Date(user.last_login);
// اگر تاریخ لاگین بزرگتر از تاریخ دیروز باشد، کاربر در لیست باقی می‌ماند
return lastLoginDate > yesterday;
});

// نتیجه نهایی را به فرمت استاندارد n8n (آرایه‌ای از آبجکت‌های دارای کلید json) برمی‌گردانیم
return recentUsers.map(user => ({ json: user }));

خروجی نود Code:

[
{ “id”: 1, “email”: “user1@test.com”, “last_login”: “2026-08-20T10:00:00Z” },
{ “id”: 3, “email”: “user3@test.com”, “last_login”: “2026-08-20T22:00:00Z” }
]

متد filter یک آرایه جدید حاوی فقط عناصری که شرط شما را برآورده می‌کنند برمی‌گرداند، بدون اینکه آرایه اصلی را تغییر دهد.

۲. مپ کردن (Mapping): تغییر شکل و بهینه‌سازی داده

سناریو: شما یک لیست محصول خام و پر از اطلاعات اضافی از API فروشگاه خود دریافت کرده‌اید. برای ارسال این داده به CRM، فقط به id, name و price نیاز دارید و می‌خواهید نام فیلدها را نیز تغییر دهید.

داده ورودی:

[
{
“product_id”: “prod_111”,
“details”: { “title”: “n8n Automation Course”, “stock”: 42 },
“pricing”: { “amount”: 99.00, “currency”: “USD” }
},
{
“product_id”: “prod_222”,
“details”: { “title”: “Advanced API Integration”, “stock”: 15 },
“pricing”: { “amount”: 149.00, “currency”: “USD” }
}
]

کد در نود Code:
javascript
const rawProducts = $input.all().map(item => item.json);

// متد map یک آرایه جدید با همان تعداد آیتم می‌سازد، اما ساختار هر آیتم را تغییر می‌دهد
const cleanProducts = rawProducts.map(product => {
return {
sku: product.product_id, // تغییر نام فیلد
name: product.details.title, // دسترسی به آبجکت تودرتو
price: product.pricing.amount // استخراج قیمت
};
});

return cleanProducts.map(product => ({ json: product }));

خروجی نود Code:

[
{ “sku”: “prod_111”, “name”: “n8n Automation Course”, “price”: 99.00 },
{ “sku”: “prod_222”, “name”: “Advanced API Integration”, “price”: 149.00 }
]

متد map برای تبدیل ساختار داده (Data Transformation) حیاتی است. شما کنترل کاملی بر شکل خروجی دارید و می‌توانید داده‌ها را برای هر API یا سیستم دیگری آماده کنید.

۳. کاهش (Reducing): خلاصه‌سازی و تجمیع داده

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

داده ورودی:

[
{ “orderId”: “ord_001”, “amount”: 50.25, “status”: “paid” },
{ “orderId”: “ord_002”, “amount”: 120.00, “status”: “paid” },
{ “orderId”: “ord_003”, “amount”: 75.50, “status”: “refunded” },
{ “orderId”: “ord_004”, “amount”: 200.00, “status”: “paid” }
]

کد در نود Code:
javascript
const allOrders = $input.all().map(item => item.json);

// ابتدا سفارشات پرداخت نشده را فیلتر می‌کنیم
const paidOrders = allOrders.filter(order => order.status === ‘paid’);

// سپس با reduce جمع مبالغ را محاسبه می‌کنیم
const totalSales = paidOrders.reduce((accumulator, currentOrder) => {
return accumulator + currentOrder.amount;
}, 0);

// نتیجه یک عدد تنهاست، آن را در یک آبجکت استاندارد برمی‌گردانیم
return [{ json: { total_sales: totalSales } }];

خروجی نود Code:

{
“total_sales”: 370.25
}

متد reduce یک آرایه را به یک مقدار واحد (یک عدد، یک رشته یا حتی یک آبجکت) کاهش می‌دهد. این متد برای محاسبات تجمعی مانند جمع، میانگین یا ساخت گزارش‌های خلاصه بسیار قدرتمند است.

قدم سوم: نبرد با اژدهای تودرتو (Handling Nested Objects & Arrays)

اینجا درد اصلی بسیاری از توسعه‌دهندگان است. APIها عاشق ارسال داده‌های تودرتو (nested) هستند و اگر ندانید چطور با آن‌ها کار کنید، ورک‌فلو شما به سادگی می‌شکند.

مثال JSON پیچیده (حداقل ۳ سطح):

{
“order_id”: “ord_xyz_987”,
“customer_details”: {
“user_id”: “usr_123”,
“contact”: {
“email”: “dev.arash@karvara.com”,
“phone”: null
}
},
“line_items”: [
{
“item_id”: “li_001”,
“product”: {
“id”: “prod_n8n”,
“name”: “n8n Course”
},
“quantity”: 1
},
{
“item_id”: “li_002”,
“product”: null,
“quantity”: 2
}
]
}

دسترسی به یک مقدار در عمق:
برای دسترسی به id اولین محصول، مسیر زیر را دنبال می‌کنیم: {{ $json.line_items[0].product.id }}

اما یک مشکل بزرگ وجود دارد: چه اتفاقی می‌افتد اگر بخواهیم به id محصول دوم دسترسی پیدا کنیم؟ ($json.line_items[1].product.id)
از آنجایی که product برای آیتم دوم null است، تلاش برای خواندن id از null باعث ایجاد خطا و توقف کامل ورک‌فلو می‌شود.

راه حل حرفه‌ای: Optional Chaining (?.)
این اپراتور جاوااسکریپت یک نجات‌دهنده است. با قرار دادن ? قبل از .، به جاوااسکریپت می‌گویید: “سعی کن به این پراپرتی دسترسی پیدا کنی، اما اگر آبجکت والد null یا undefined بود، خطا نده و فقط undefined برگردان.”

کد امن و مقاوم در برابر خطا به این شکل خواهد بود:
{{ $json.line_items[1].product?.id }}

این عبارت به جای شکستن ورک‌فلو، به سادگی مقدار undefined را برمی‌گرداند. در پروژه‌های واقعی که با APIهای غیرقابل‌پیش‌بینی سروکار دارید، استفاده از Optional Chaining یک ضرورت است، نه یک انتخاب.

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

بیایید تمام تکنیک‌ها را در یک چالش واقعی کنار هم قرار دهیم.

هدف: از API گیت‌هاب، لیست ۱۰ کامیت آخر یک ریپازیتوری را می‌گیریم. سپس به ازای هر کامیت، اطلاعات پروفایل نویسنده آن را از یک API دیگر گیت‌هاب دریافت کرده و در نهایت، یک گزارش غنی‌شده شامل پیام کامیت و نام کامل نویسنده را برای ارسال به Slack آماده می‌کنیم.

ساختار ورک‌فلو:
1. HTTP Request (Get Commits): درخواست GET به api.github.com/repos/{owner}/{repo}/commits?per_page=10
2. Code (Transform & Enrich): یک نود Code که روی لیست کامیت‌ها map می‌زند و داده‌ها را ترکیب می‌کند.
3. Slack (Send Report): ارسال گزارش نهایی به یک کانال Slack.

کد کلیدی در نود Code (مرحله ۲):
در این بخش از متد داخلی this.helpers.httpRequest برای ارسال درخواست‌های همزمان استفاده می‌کنیم. این روش بسیار سریع‌تر از استفاده از حلقه‌های معمولی است.

javascript
// دریافت تمام کامیت‌های ورودی
const commits = $input.all().map(item => item.json);

// استفاده از تابع async در map
const enrichmentPromises = commits.map(async (commit) => {
const authorUsername = commit.author?.login;

// اگر نویسنده وجود نداشت، با داده‌های پیش‌فرض برگرد
if (!authorUsername) {
return {
commit_message: commit.commit.message,
author_name: ‘Unknown’,
commit_url: commit.html_url,
};
}

// درخواست API برای گرفتن اطلاعات پروفایل نویسنده
// نکته: استفاده از this.helpers.httpRequest روش استاندارد ارسال درخواست در نود Code است
let authorDetails = {};
try {
authorDetails = await this.helpers.httpRequest({
method: ‘GET’,
url: https://api.github.com/users/${authorUsername},
json: true // پاسخ را به صورت JSON پارس کن
});
} catch (error) {
// مدیریت خطا در صورت خرابی API
authorDetails = { name: authorUsername };
}

// ترکیب داده‌ها
return {
commit_message: commit.commit.message.split(‘\n’)[0], // فقط خط اول پیام کامیت
author_name: authorDetails.name || authorUsername, // اگر نام کامل وجود نداشت، از یوزرنیم استفاده کن
commit_url: commit.html_url,
};
});

// منتظر می‌مانیم تا تمام درخواست‌های API به پایان برسند
const enrichedCommits = await Promise.all(enrichmentPromises);

// گزارش نهایی را برمی‌گردانیم
return enrichedCommits.map(item => ({ json: item }));

خروجی این نود، آرایه‌ای تمیز و آماده برای ارسال به Slack خواهد بود:

[
{
“commit_message”: “feat: Implement advanced JSON parsing”,
“author_name”: “Arash Developer”,
“commit_url”: “https://github.com/…”
},
{
“commit_message”: “fix: Handle null values in nested objects”,
“author_name”: “Jane Coder”,
“commit_url”: “https://github.com/…”
}
]

این ورک‌فلو نمونه‌ای کامل از یک فرآیند ETL (Extract, Transform, Load) در دل n8n است. شما داده را از یک منبع استخراج کردید، آن را با داده‌های دیگر غنی‌سازی و تمیزسازی (Transform) کردید و در نهایت آن را برای بارگذاری در سیستم مقصد (Slack) آماده نمودید.

نتیجه‌گیری: شما دیگر یک قربانی API نیستید، یک معمار داده‌اید

تسلط بر دستکاری JSON در n8n، تفاوت بین ساختن یک ورک‌فلوی شکننده و یک سیستم اتوماسیون صنعتی و قابل اعتماد است. با یادگیری تکنیک‌های این مقاله، شما دیگر محدود به ساختار داده‌ای که APIها به شما تحمیل می‌کنند، نیستید.

بیایید نکات کلیدی را مرور کنیم:

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

—