Data in n8n: Items, Expressions and Mapping

Reach current-item and earlier-node data with expressions, map fields with Edit Fields, and know when item linking helps or breaks.

بعد از این درس می‌توانی

  • با $json به داده آیتم ورودی همین گره و با $('نام گره') به داده گره‌های قبلی ارجاع بدهد.
  • تفاوت .item (آیتم پیوندخورده) با .first()، .last() و .all() را بگوید و برای هر موقعیت درست انتخاب کند.
  • با Edit Fields خروجی را به شکل قرارداد گره بعد نگاشت کند و مقدار تهی را درست مدیریت کند.
  • علت رایج Expressionهای خالی یا غلط (گره دیگر، نام تغییرکرده، پیوند شکسته) را تشخیص بدهد.

چرا این درس مهم است

ورک‌فلوی برگ سبز برای هر تیکت، سفارش مربوط را می‌خواند و پاسخ می‌ساخت. با یک تیکت عالی کار می‌کرد. روزی که ده تیکت با هم آمد، همه ده پاسخ وضعیت اولین سفارش را گفتند. Expression همکار $('Get Order').first() بود؛ در آزمون با یک آیتم «درست» بود و با ده آیتم غلط.

بیشتر ایرادهای ورک‌فلوهای n8n از همین‌جاست: داده درست است، ولی Expression به آیتم اشتباه اشاره می‌کند. این درس یاد می‌دهد دقیقاً بدانی هر Expression به کدام داده نگاه می‌کند.

مفاهیم کلیدی

یادآوری: آیتم و تقسیم آرایه با Split Out را در درس قبل، و مسیر فیلد (data[0].items[0].title) را در دوره HTTP و JSON دیدی.

  • Expression (عبارت): کد کوتاه داخل {{ }} در فیلد یک گره که هنگام اجرا برای هر آیتم محاسبه می‌شود.
  • $json (داده آیتم فعلی): بخش json آیتمی که الان وارد همین گره شده است.
  • Item Linking (پیوند آیتم): ردی که n8n نگه می‌دارد تا بداند هر آیتم از کدام آیتم گره قبلی ساخته شده است.
  • Data Mapping (نگاشت داده): تبدیل شکل داده یک گره به شکلی که گره بعد انتظار دارد.
  • Edit Fields (گره ویرایش فیلدها): گرهی که فیلدها را می‌سازد، تغییر نام می‌دهد یا حذف می‌کند.

مدل ذهنی

هر گره را مثل کارمندی پشت میز ببین که پرونده‌ها یکی‌یکی جلویش می‌آیند. $json پرونده‌ای است که الان روی میز است. $('Get Order').item یعنی «برو از بایگانی، برگه‌ای را بیاور که همین پرونده از آن ساخته شده». و $('Get Order').first() یعنی «اولین برگه بایگانی را بیاور»، هر پرونده‌ای که روی میز باشد.

تفاوت ارجاع آیتم پیوندخورده و اولین آیتم: گره Get Orders سه سفارش A و B و C دارد؛ گره Build Reply سه آیتم ساخته‌شده از آن‌ها را پردازش می‌کند؛ با item هر آیتم به سفارش خودش وصل است؛ با first همه به سفارش A اشاره می‌کنند.

تفاوت ارجاع آیتم پیوندخورده و اولین آیتم

این تشبیه کجا غلط است؟ کارمند واقعی اگر برگه پدر را پیدا نکند، می‌گوید «پیدا نکردم». در n8n، اگر پیوند آیتم شکسته باشد (مثلاً یک گره Code آیتم‌ها را از نو ساخته باشد)، .item ممکن است خطا بدهد یا نتواند آیتم درست را تشخیص دهد. پیوند همیشه خودکار سالم نمی‌ماند؛ باید بدانی کجا ممکن است بشکند.

گام‌به‌گام

گام ۱: `$json` همیشه ورودی همین گره است

وقتی فیلدی را از پنل ورودی به یک پارامتر می‌کشی، n8n Expressionی مثل {{ $json.fruit }} می‌سازد که برای هر آیتم مقدار همان آیتم را می‌گیردsrc-n8n-data-structure. نکته کلیدی: $json فقط به آیتم ورودی همین گره اشاره می‌کند. اگر فیلدی در ورودی نیست (چون در گره دو مرحله عقب‌تر بود)، $json آن را ندارد و نتیجه خالی است.

گام ۲: ارجاع به گره‌های قبلی

مستندات n8n این نحو را می‌دهدsrc-n8n-reference-previous-nodes:

نحویعنیکی
$('Get Order').item.jsonآیتم پیوندخورده: آیتمی از Get Order که آیتم فعلی از آن ساخته شدهبیشتر وقت‌ها؛ وقتی هر آیتم به یک آیتم مشخص قبلی مربوط است
$('Get Order').first()اولین آیتم آن گره، بدون توجه به پیوندوقتی آن گره فقط یک آیتم دارد (مثل تنظیمات یا یک پاسخ کلی)
$('Get Order').last()آخرین آیتمبه‌ندرت
$('Get Order').all()همه آیتم‌ها به‌شکل فهرستوقتی به کل فهرست نیاز داری (مثلاً شمارش)

داستان آغاز درس: .first() با یک آیتم و .item نتیجه یکسان دارند؛ تفاوت فقط با چند آیتم دیده می‌شود. پس همیشه با دست‌کم دو آیتم بیازما.

نام گره بخشی از Expression است. اگر گره «Get Order» را به «Read Order» تغییر نام بدهی، n8n معمولاً ارجاع‌ها را به‌روز می‌کند، ولی Expressionهایی که در متن آزاد یا کد نوشته‌ای را بررسی کن.

گام ۳: نگاشت با Edit Fields

گره بعدی معمولاً شکل مشخصی می‌خواهد: API ثبت تیکت سه فیلد customer_ref، category، text را می‌خواهد. با Edit Fields:

  • فقط فیلدهای لازم را نگه دار، نه همه چیز؛ داده اضافه (مثلاً تلفن مشتری) بی‌دلیل جلو نمی‌رود.
  • نام‌ها را با قرارداد گره بعد یکی کن.
  • نوع را درست بگذار: عدد، رشته، بولی.
  • برای مقدار تهی تصمیم بگیر: {{ $json.carrier ?? 'نامعلوم' }} فقط برای null و undefined جایگزین می‌گذارد؛ || رشته خالی و صفر را هم جایگزین می‌کند و ممکن است عدد صفر را خراب کند.

گام ۴: Expressionها جاوااسکریپت کوتاه‌اند

داخل {{ }} می‌توانی متدهای ساده رشته و عدد را به کار ببری: {{ $json.text.trim() }}، {{ $json.total.toLocaleString() }}، {{ $json.items.length }}. قاعده عملی: اگر Expression از یک خط ساده بیشتر شد، آن را در یک گره Edit Fields جدا با نام روشن بگذار یا گره Code بنویس (درس بعد)، تا خواندنی و آزمودنی بماند.

گام ۵: پیوند کجا می‌شکند

پیوند آیتم وقتی سالم است که هر گره مشخص کند خروجی‌اش از کدام ورودی آمده؛ گره‌های آماده n8n معمولاً این را انجام می‌دهند. خطر در جاهایی است که آیتم‌ها از نو ساخته یا ادغام می‌شوند: گره Code که فهرست تازه برمی‌گرداند، تجمیع (Aggregate) و ادغام (Merge). پس از این گره‌ها، .item به گره‌های پیش از آن‌ها را با چند آیتم بیازما؛ و اگر لازم شد، داده لازم را پیش از آن گره در خود آیتم نگه دار.

مثال‌ها

پیاده‌سازی عملی

آزمایشگاه Expression. حدود ۲۲ دقیقه. داده و هفت تمرین در assets/expression-lab.md است.

اجرای محلی
  1. ورک‌فلوی تازه: Manual Trigger ← Edit Fields با نام «Get Order» ← Edit Fields با نام «Get Ticket» ← Edit Fields با نام «Build Reply».
  2. خروجی «Get Order» و «Get Ticket» را با داده فایل تمرین سنجاق کن (یا در خود Edit Fields مقدارها را بساز).
  3. هفت تمرین را در «Build Reply» بنویس و نتیجه را با پیش‌بینی‌ات مقایسه کن.
  4. حالا «Get Order» را طوری سنجاق کن که سه سفارش داشته باشد و «Get Ticket» هم سه تیکت. Expression تمرین ۲ را یک بار با .item و یک بار با .first() اجرا کن و خروجی‌ها را مقایسه کن.
سرویس میزبانی‌شده (در دسترس قانونی)

همان گام‌های مسیر محلی در n8n Cloud، اگر در دسترس قانونی است؛ این تمرین به هیچ API بیرونی نیاز ندارد.

بدون اجرا / شبیه‌ساز

هفت تمرین را روی کاغذ حل کن و با پاسخ‌های پایین فایل مقایسه کن. بعد بنویس اگر «Get Order» سه آیتم داشت، تمرین ۲ با .first() برای پاسخ دوم و سوم چه مقداری می‌داد.

بدون کد

بیشتر Expressionها را با کشیدن فیلد از پنل ورودی بساز و فقط بخش‌های کوچک را دستی تایپ کن. پیش‌نمایش نتیجه زیر هر فیلد را ببین.

با کد

تمرین ۶ را یک بار هم در یک گره Code بنویس که روی همه آیتم‌های ورودی حلقه می‌زند و برای هرکدام پیام می‌سازد. بنویس کدام راه برای این کار ساده‌تر و خواناتر است و چرا.

اشتباه‌های رایج

اشتباهنتیجهکار درست
$json برای داده گره دیگرمقدار خالی$('نام گره').item.json
.first() وقتی چند آیتم هستهمه به آیتم اول اشاره می‌کنند.item برای آیتم پیوندخورده
آزمون فقط با یک آیتمایراد .first() دیده نمی‌شودهمیشه با دست‌کم دو آیتم
`` برای مقدار پیش‌فرض عددصفر جایگزین می‌شود??
Expression چندخطی پیچیده در یک فیلدخواندن و آزمودن سختگره جدا با نام روشن
بردن همه فیلدها تا آخر ورک‌فلوداده شخصی بی‌دلیل جابه‌جا می‌شودفقط فیلدهای لازم

اشکال‌زدایی

Expression در پیش‌نمایش خالی است یا undefined نشان می‌دهد.

فیلد در ورودی همین گره نیست؛ در گره دیگری است، یا نامش (حروف، فاصله) فرق دارد.

پنل ورودی همین گره را ببین؛ فیلد آنجا هست؟ مسیر تودرتو را دقیق بخوان.

با $('نام گره').item.json به گره درست ارجاع بده یا مسیر را درست کن.

با چند آیتم، همه خروجی‌ها مقدار یکسان دارند.

.first() یا .last() به‌جای .item.

Expression را بخوان؛ با دو آیتم متفاوت اجرا کن.

.item برای داده مربوط به همان آیتم.

پس از افزودن یک گره Code یا Merge، Expressionهای .item به گره‌های قبل خطا می‌دهند یا مقدار نامربوط برمی‌گردانند.

پیوند آیتم در آن گره حفظ نشده است.

پیش و پس از آن گره را با چند آیتم بیازما.

داده لازم را پیش از آن گره در خود آیتم نگه دار؛ یا در Code پیوند را حفظ کن (درس بعد).

تمرین کوتاه

تمرین · 10 دقیقه

هدف: انتخاب ارجاع درست.

گام‌ها: برای هر مورد Expression را بنویس.

  1. در گره «Send Reply»، شناسه سفارشی که این پاسخ برایش ساخته شده، از گره «Get Order» (چند آیتم).
  2. نشانی ایمیل مسئول از گره «Settings» که فقط یک آیتم با فیلد manager_email دارد.
  3. تعداد کل سفارش‌های گره «Get Orders».
  4. متن تیکت فعلی بدون فاصله‌های ابتدا و انتها.

معیار پذیرش: ۱ با .item؛ ۲ با .first() (یا .item اگر پیوند دارد)؛ ۳ با .all().length؛ ۴ با $json و trim().

راه‌حل نمونه

۱: {{ $('Get Order').item.json.id }}. ۲: {{ $('Settings').first().json.manager_email }}؛ چون Settings یک آیتم دارد و به آیتم خاصی مربوط نیست. ۳: {{ $('Get Orders').all().length }}. ۴: {{ $json.text.trim() }}.

چالش

تمرین · 30 دقیقه

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

  1. برای گره پایانی (یا API مقصد)، قرارداد ورودی را بنویس: فیلدها، نوع، اجباری یا اختیاری.
  2. یک گره Edit Fields پیش از آن بگذار که دقیقاً همین قرارداد را بسازد و هیچ فیلد اضافه‌ای جلو نبرد.
  3. همه Expressionهای ورک‌فلو را فهرست کن و برای هرکدام بنویس به کدام آیتم اشاره می‌کند ($json، .item، .first()) و چرا.
  4. ورک‌فلو را با سه آیتم متفاوت (که یکی‌شان فیلد تهی دارد) اجرا کن و خروجی را بررسی کن.

خروجی مورد انتظار: قرارداد ورودی، ورک‌فلوی اصلاح‌شده، جدول Expressionها با دلیل، و نتیجه اجرای سه‌آیتمی.

معیار پذیرش:

  • هیچ .first()ای برای داده‌ای که به هر آیتم مربوط است باقی نمانده است.
  • خروجی پایانی فقط فیلدهای قرارداد را دارد.
  • مقدار تهی با تصمیم روشن مدیریت شده است.
  • داده نمونه ساختگی یا ناشناس است.

پرسش‌های سنجش

جمع‌بندی

  • $json همیشه آیتم ورودی همین گره است.
  • $('نام گره').item آیتم پیوندخورده است؛ .first()، .last() و .all() بدون توجه به پیوند.
  • همیشه با دست‌کم دو آیتم متفاوت بیازما؛ ایراد .first() با یک آیتم پنهان می‌ماند.
  • با Edit Fields خروجی را به شکل قرارداد گره بعد بساز و فقط فیلدهای لازم را ببر.
  • برای مقدار پیش‌فرض، ?? را از || جدا بدان.
  • پس از Code، Merge یا تجمیع، پیوند آیتم را بیازما.

پرسش‌های سنجش

در گره «Build Reply» (ورودی: آیتم تیکت با فیلدهای id و customer_ref)، Expressionی بنویس که متن «تیکت T-0007 برای سفارش BS-1002» را بسازد؛ شناسه سفارش در گره «Get Order» است.

پاسخ نمونه و معیار ارزیابی

تیکت {{ $json.id }} برای سفارش {{ $('Get Order').item.json.id }}

  • $json برای تیکت (1 امتیاز)
  • $('Get Order').item.json برای سفارش (1 امتیاز)
  • $json.order.id ← داده سفارش در ورودی این گره نیست؛ باید به گره Get Order ارجاع بدهی.

برای هر مورد بگو .item یا .first() یا .all() و چرا: (الف) نرخ تبدیل ارز از گره «Get Rate» که یک آیتم دارد، برای همه سفارش‌ها؛ (ب) نام مشتری هر سفارش از گره «Get Customer» که برای هر سفارش یک آیتم ساخته؛ (ج) مجموع مبلغ همه سفارش‌های گره «Get Orders».

پاسخ نمونه و معیار ارزیابی

(الف) .first()، چون یک مقدار مشترک است و به آیتم خاصی پیوند ندارد. (ب) .item، چون هر سفارش مشتری خودش را دارد. (ج) .all() و جمع روی فهرست، چون به همه آیتم‌ها نیاز است.

  • الف first (1 امتیاز)
  • ب item (1 امتیاز)
  • ج all (1 امتیاز)
  • ب first ← همه سفارش‌ها نام مشتری اول را می‌گیرند.

گره «Format» این Expression را دارد و نتیجه برای همه آیتم‌ها خالی است. ورودی Format از گره «Split Out» می‌آید که سفارش‌ها را جدا کرده است. علت و اصلاح؟

Expression و ساختار.

Expression in Format:  {{ $json.data[0].status }}
Input item example:    {"id": "BS-1001", "status": "shipped", ...}
پاسخ نمونه و معیار ارزیابی

پس از Split Out هر آیتم خودش یک سفارش است و دیگر فیلد data ندارد؛ مسیر data[0] مربوط به پاسخ پیش از تقسیم است. اصلاح: {{ $json.status }}.

  • تغییر شکل آیتم پس از Split Out را می‌بیند (1 امتیاز)
  • اصلاح به $json.status (1 امتیاز)
  • Split Out را حذف کن ← Split Out لازم است؛ Expression باید با شکل تازه هم‌خوان شود.

فیلد discount گاهی 0 و گاهی null است. می‌خواهی وقتی null است، 0 بگذاری و وقتی 0 است، همان 0 بماند. کدام Expression؟

  • {{ $json.discount || 0 }}
  • {{ $json.discount ?? 0 }}
  • {{ $json.discount }}
  • {{ $json.discount || 'none' }}
پاسخ نمونه و معیار ارزیابی
  • a ← در این مورد نتیجه یکسان است، ولی || برای رشته خالی یا false هم جایگزین می‌گذارد و نیت را نمی‌رساند؛ برای پیش‌فرض null، ?? دقیق است.
  • c ← null بدون تغییر جلو می‌رود.
  • d ← صفر را به رشته none تبدیل می‌کند و نوع عدد را می‌شکند.

API ثبت تیکت فقط customer_ref (رشته)، category (رشته) و text (رشته) را می‌پذیرد. آیتم ورودی این است: {"id": "T-0007", "customer": {"ref": "C-12", "phone": "0912xxxxxxx"}, "category": "order_shipping", "body": " سفارش کی می‌رسه؟ "}. تنظیم Edit Fields را بنویس.

پاسخ نمونه و معیار ارزیابی

فقط سه فیلد (گزینه حذف فیلدهای دیگر): customer_ref = {{ $json.customer.ref }}، category = {{ $json.category }}، text = {{ $json.body.trim() }}. تلفن جلو نمی‌رود.

  • مسیر تودرتو customer.ref (1 امتیاز)
  • trim برای متن (1 امتیاز)
  • نبردن تلفن و فیلدهای اضافه (1 امتیاز)
  • همه فیلدها را نگه دار ← تلفن مشتری بی‌دلیل به سرویس بعد می‌رود؛ API هم ممکن است فیلد اضافه را رد کند.

فایل‌های درس

داده و هفت تمرین Expression با پاسخ

expression-lab.md

ابزارها و جایگزین‌ها

  • n8n 2.x — تمرین Expression — n8n Cloud در صورت دسترسی قانونی — مسیر بدون نصب

منابع

Understand n8n's data structure n8n accessed 2026-10-16

Reference previous nodes n8n accessed 2026-10-16

Course

n8n Fundamentals