Credential، HTTP Request و صفحه‌بندی

کلید را در Credential بگذار، هر API را با گره HTTP Request صدا بزن، همه صفحه‌ها را با صفحه‌بندی داخلی بخوان و پاسخ‌های خطا را به‌جای پنهان کردن ببین.

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

  • برای یک API، Credential مناسب (از پیش تعریف‌شده یا عمومی مثل Header Auth) بسازد و کلید را هرگز در خود گره ننویسد.
  • گره HTTP Request را با روش، پارامتر، هدر و بدنه درست تنظیم کند و از Import cURL با آگاهی از محدودیتش استفاده کند.
  • صفحه‌بندی داخلی را با $pageCount یا نشانی صفحه بعد تنظیم کند و شرط توقف را بیازماید.
  • تصمیم بگیرد کی گزینه «Never Error» یا گرفتن کد وضعیت لازم است و پاسخ خطا را بی‌صدا رد نکند.

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

گزارش ماهانه فروش برگ سبز همیشه «کمی کمتر از حساب‌ها» بود. ورک‌فلو فقط صفحه اول API سفارش‌ها را می‌خواند: ۵۰ سفارش از حدود ۳۰۰. ورک‌فلوی دیگری کلید سامانه را مستقیم در هدر گره نوشته بود؛ وقتی ورک‌فلو برای کمک‌گرفتن در انجمن به اشتراک گذاشته شد، کلید هم با آن رفت. سومی گزینه «هیچ‌وقت خطا نده» را روشن کرده بود تا ورک‌فلو «قرمز نشود»؛ ماه‌ها پاسخ‌های 401 به‌عنوان داده معتبر پردازش شدند.

گره HTTP Request دروازه n8n به هر API است، حتی آن‌هایی که گره آماده ندارند. این درس سه مهارت آن را با API آزمایشی می‌سازد: کلید امن، همه صفحه‌ها، و خطای دیده‌شده.

مفاهیم کلیدی

یادآوری: کلید API، توکن Bearer و جای امن کلید را در درس سوم دوره HTTP، و صفحه‌بندی با next_page را در درس JSON دیدی.

  • Credential (اعتبارنامه): محلی در n8n که کلید یا اطلاعات ورود را رمزگذاری‌شده نگه می‌دارد و گره‌ها فقط به آن اشاره می‌کنند.
  • Predefined Credential Type (نوع اعتبارنامه از پیش تعریف‌شده): Credentialی که n8n برای یک سرویس مشخص آماده کرده است.
  • Header Auth (احراز هویت با هدر): Credential عمومی که یک هدر با نام و مقدار مشخص به هر درخواست اضافه می‌کند.
  • Pagination (صفحه‌بندی): خواندن داده بزرگ در چند درخواست پشت سر هم، صفحه به صفحه.
  • Import cURL (وارد کردن cURL): ساختن تنظیمات گره HTTP Request از یک دستور curl.

مدل ذهنی

گره HTTP Request را مثل پیک ببین و Credential را مثل کارت ورود ساختمان مقصد که در صندوق امانات شرکت است. پیک کارت را هر بار از صندوق برمی‌دارد و پس می‌دهد؛ روی کاغذ مأموریت نوشته نمی‌شود. صفحه‌بندی یعنی پیک می‌داند پرونده چند جلد است و تا جلد آخر برمی‌گردد. و «Never Error» یعنی به پیک بگویی «حتی اگر در را باز نکردند، بگو موفق بودی».

صفحه‌بندی با شماره صفحه در گره HTTP Request: گره HTTP Request با Credential هدر Authorization را اضافه می‌کند؛ صفحه ۱ با pageCount صفر می‌خواند؛ پاسخ next_page برابر ۲ دارد؛ صفحه ۲ و ۳ خوانده می‌شود؛ در صفحه ۳ next_page تهی است و صفحه‌بندی متوقف می‌شود.

صفحه‌بندی با شماره صفحه در گره HTTP Request

این تشبیه کجا غلط است؟ کارت ورود را اگر کسی از صندوق بردارد، دیده می‌شود. Credential n8n با یک کلید رمزگذاری نگه داشته می‌شود که در پوشه داده n8n (همان volume) استsrc-n8n-docker-compose؛ هر کس به آن پوشه و پایگاه داده برسد، به همه Credentialها می‌رسد. Credential امن‌تر از نوشتن کلید در گره است، نه امن مطلق.

گام‌به‌گام

گام ۱: Credential درست

مستندات گره HTTP Request توصیه می‌کند هر جا n8n برای سرویس نوع از پیش تعریف‌شده دارد، از آن استفاده کنی، چون ساده‌تر است؛ برای بقیه API‌ها گزینه‌های عمومی مثل Basic، Header، OAuth1، OAuth2 و Query auth هستsrc-n8n-http-request-node. برای API آزمایشی برگ سبز:

  • نوع: Header Auth؛ نام هدر: Authorization؛ مقدار: Bearer local-demo-token.
  • نام Credential را گویا بگذار: «Barg Sabz Mock API (local)».
  • برای هر سرویس و هر محیط Credential جدا با کمترین اختیار (درس کلید در دوره HTTP).

کلید را هرگز در فیلد هدر یا نشانی خود گره ننویس: خروجی ورک‌فلو و اشتراک‌گذاری آن را با خود می‌برد. Query auth (کلید در نشانی) را فقط اگر API راه دیگری ندارد به کار ببر؛ نشانی‌ها در لاگ‌ها ثبت می‌شوند.

گام ۲: تنظیم درخواست

گره HTTP Request پارامترها و هدرها را «با فیلدها» یا «با JSON» می‌گیرد، و بدنه را با نوع‌های Form URLencoded، Form-Data، JSON، فایل باینری و Rawsrc-n8n-http-request-node. برای POST /tickets بدنه JSON با سه فیلد بفرست، که از Expression آیتم ورودی پر می‌شوند.

Import cURL سریع است: دستور curl مستندات API را بچسبان. ولی مستندات می‌گوید پیکربندی فعلی گره را بازنویسی می‌کند و مقدارها را به‌شکل رشته وارد می‌کند؛ برای حفظ نوع عدد و بولی بهتر است بدنه را «با JSON» بچسبانیsrc-n8n-http-request-node. و اگر دستور curl کلید دارد، پس از وارد کردن، آن را از گره پاک کن و Credential بگذار.

گام ۳: صفحه‌بندی داخلی

درس قبل گفت گره HTTP Request خودش صفحه‌ها را تکرار نمی‌کند و باید صفحه‌بندی را مدیریت کنی؛ گزینه صفحه‌بندی همین کار است. دو حالت رایج در مستنداتsrc-n8n-pagination-cookbook:

حالتتنظیمکی
Update a Parameter in Each Requestپارامتر query با نام page و مقدار {{ $pageCount + 1 }}API شماره صفحه می‌گیرد
Response Contains Next URLنشانی بعدی از پاسخ، مثلاً {{ $response.body["next-page"] }}API نشانی صفحه بعد را می‌دهد

$pageCount تعداد صفحه‌های خوانده‌شده است و از صفر شروع می‌شود؛ برای همین + 1src-n8n-pagination-cookbook. شرط توقف را هم بگذار: برای API آزمایشی، وقتی $response.body.next_page تهی است. نام دقیق تنظیم توقف را در نسخه n8n خودت ببین؛ مهم این است که بیازمایی صفحه آخر خوانده می‌شود و حلقه بی‌پایان نمی‌شود. برای ایمنی، سقف تعداد صفحه هم بگذار.

گام ۴: خطا را نبین‌نکن

گزینه Never Error پاسخ را با هر کد وضعیتی موفق برمی‌گرداند، و Include Response Headers and Status هدرها و کد وضعیت را کنار بدنه می‌آوردsrc-n8n-http-request-node. قاعده:

  • به‌طور پیش‌فرض بگذار گره روی 4xx و 5xx خطا بدهد؛ مسیر خطا را در درس بعد می‌سازی.
  • Never Error را فقط وقتی روشن کن که خودت کد وضعیت را با If بررسی می‌کنی؛ مثلاً 404 در «سفارش پیدا نشد» یک نتیجه عادی است، نه خطا. آن وقت Include Response Headers and Status هم روشن کن تا statusCode را داشته باشی.

گام ۵: دسته‌بندی درخواست‌ها

گره HTTP Request گزینه Batching دارد: تعداد آیتم در هر دسته و فاصله بین دسته‌ها به میلی‌ثانیهsrc-n8n-http-request-node. برای API با سقف نرخ ساده، این از ساختن Loop Over Items و Wait (درس قبل) ساده‌تر است.

مثال‌ها

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

خواندن همه سفارش‌ها و ثبت تیکت با Credential. حدود ۲۲ دقیقه.

اجرای محلی
  1. API آزمایشی (shared/barg-sabz-mock-api.py) را با --host 0.0.0.0 اجرا کن (مثل درس دوم).
  2. Credential از نوع Header Auth با نام «Barg Sabz Mock API (local)» بساز.
  3. گره HTTP Request: GET http://host.docker.internal:8787/orders با پارامتر limit برابر ۳ و Credential بالا. صفحه‌بندی را با حالت Update a Parameter و {{ $pageCount + 1 }} تنظیم کن و شرط توقف را بر اساس next_page بگذار.
  4. اجرا کن: باید سه درخواست ببینی و در مجموع هفت سفارش. اگر خروجی به‌شکل سه آیتم (هر صفحه یکی) است، با Split Out روی data آن‌ها را جدا کن.
  5. یک گره HTTP Request دیگر: POST /tickets با بدنه JSON و همان Credential. یک بار با هدر Idempotency-Key و یک بار بدون آن اجرا کن و GET /tickets را ببین.
  6. یک بار Credential را به کلید غلط عوض کن و ببین گره چه خطایی می‌دهد. سپس Never Error و Include Response Headers and Status را روشن کن و ببین خروجی چه شکلی می‌شود. برگردان.
سرویس میزبانی‌شده (در دسترس قانونی)

در n8n Cloud (اگر در دسترس قانونی است) API محلی در دسترس نیست. صفحه‌بندی را با یک API عمومی آزمایشی که مستنداتش صفحه‌بندی دارد، یا فقط با خواندن assets/pagination-trace.md و ساختن تنظیمات گره بدون اجرا تمرین کن. Credential را برای یک سرویس واقعی که دسترسی قانونی داری، با نوع از پیش تعریف‌شده بساز.

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

assets/pagination-trace.md پاسخ سه صفحه را دارد. تنظیمات گره را بنویس، تعداد درخواست و سفارش‌ها را پیش‌بینی کن و به پرسش‌های فایل جواب بده.

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

اشتباهنتیجهکار درست
کلید در هدر یا نشانی خود گرهبا خروجی ورک‌فلو منتشر می‌شودCredential
خواندن فقط صفحه اولگزارش ناقص بی‌صداصفحه‌بندی و مقایسه شمار کل
{{ $pageCount }} بدون + 1صفحه صفر یا تکرار صفحه اول$pageCount از صفر است
صفحه‌بندی بدون شرط توقف و سقفدرخواست بی‌فایده یا بی‌پایانشرط توقف از پاسخ + سقف صفحه
Never Error برای «سبز ماندن»401 و 500 داده معتبر حساب می‌شوندخطا بدهد، یا کد را خودت بررسی کن
Import cURL و فراموش کردن کلید داخلشکلید در گره می‌ماندپس از وارد کردن، Credential بگذار

اشکال‌زدایی

گره با 401 شکست می‌خورد، در حالی که curl با همان کلید کار می‌کند.

در Credential نام هدر یا قالب مقدار فرق دارد (مثلاً Bearer جا افتاده) یا Credential دیگری انتخاب شده است.

Credential انتخاب‌شده در گره و مقدار هدر را (بدون نمایش کلید در لاگ) با مستندات API مقایسه کن.

نام Authorization و مقدار Bearer <کلید>؛ Credential درست را انتخاب کن.

گزارش همیشه دقیقاً ۵۰ ردیف (یا مضربی از اندازه صفحه) دارد.

صفحه‌بندی خاموش است یا زود متوقف می‌شود.

تعداد درخواست‌ها را در اجرا ببین؛ next_page آخرین پاسخ را بخوان.

صفحه‌بندی را روشن و شرط توقف را با پاسخ واقعی هم‌خوان کن؛ شمار کل را با منبع مقایسه کن.

صفحه‌بندی تا سقف ادامه می‌دهد و صفحه‌های آخر خالی‌اند.

شرط توقف هرگز درست نمی‌شود؛ مثلاً مسیر فیلد غلط است و همیشه تهی یا همیشه پر است.

شرط را روی پاسخ آخرین صفحه دستی بیازما.

مسیر درست $response.body.next_page و مقایسه دقیق با تهی.

تمرین کوتاه

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

هدف: تنظیم درست برای سه API.

گام‌ها: برای هر API، نوع Credential و حالت صفحه‌بندی را بنویس.

  1. سرویسی که n8n برایش گره و Credential آماده دارد.
  2. API داخلی که کلید را در هدر X-API-Key می‌خواهد و در پاسخ "next": "https://.../items?cursor=abc" می‌دهد.
  3. API که کلید را فقط در پارامتر نشانی ?key= می‌پذیرد و پارامتر page دارد.

معیار پذیرش: ۱ نوع از پیش تعریف‌شده؛ ۲ Header Auth با نام X-API-Key و Response Contains Next URL با $response.body.next؛ ۳ Query auth با هشدار لاگ و Update a Parameter با $pageCount + 1.

راه‌حل نمونه

۱: Credential از پیش تعریف‌شده و صفحه‌بندی همان گره آماده. ۲: Header Auth با نام X-API-Key؛ صفحه‌بندی Response Contains Next URL با {{ $response.body.next }} و توقف وقتی تهی است. ۳: Query auth چون راه دیگری نیست، با این آگاهی که نشانی در لاگ سرورها ثبت می‌شود و کلید باید کم‌اختیار و قابل چرخش باشد؛ صفحه‌بندی Update a Parameter با page = {{ $pageCount + 1 }}.

چالش

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

موقعیت: یکی از اتصال‌های کار خودت (از کارت‌های درخواست دوره HTTP) را در n8n با گره HTTP Request بساز. اگر سرویس واقعی در دسترس نیست یا داده‌اش حساس است، از API آزمایشی برگ سبز یا داده ساختگی استفاده کن.

  1. Credential درست با نام گویا و کمترین اختیار.
  2. اگر داده چندصفحه‌ای است، صفحه‌بندی با شرط توقف و سقف؛ شمار کل را با منبع مقایسه کن.
  3. تصمیم درباره Never Error: کدام کدهای وضعیت «نتیجه عادی»اند و کدام خطا؟
  4. خروجی ورک‌فلو را بگیر و بررسی کن هیچ کلیدی در فایل نیست.

خروجی مورد انتظار: ورک‌فلو (یا خروجی JSON آن بدون Credential)، جدول کدهای وضعیت و رفتار، و نتیجه مقایسه شمار کل.

معیار پذیرش:

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

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

جمع‌بندی

  • کلید فقط در Credential؛ نوع از پیش تعریف‌شده هر جا هست، وگرنه Header Auth یا OAuth.
  • Credential امن‌تر از گره است، نه امن مطلق؛ پوشه داده n8n کلید رمزگذاری را دارد.
  • Import cURL سریع است ولی تنظیم را بازنویسی می‌کند و ممکن است کلید را داخل گره بگذارد.
  • صفحه‌بندی: $pageCount از صفر است؛ شرط توقف از پاسخ و سقف صفحه، و آزمون صفحه آخر.
  • Never Error فقط وقتی کد وضعیت را خودت بررسی می‌کنی.
  • Batching گره برای سقف نرخ ساده کافی است.

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

همکارت ورک‌فلویش را برای کمک در یک انجمن عمومی گذاشته است. در فایل خروجی این بخش دیده می‌شود. چه مشکلی هست و چه کارهایی به ترتیب لازم است؟

بخشی از فایل خروجی ورک‌فلو (ساختگی).

"parameters": {
  "url": "https://orders.barg-sabz.example.com/orders",
  "sendHeaders": true,
  "headerParameters": {"parameters": [{"name": "Authorization", "value": "Bearer FAKE-ADMIN-7Q2X"}]}
}
پاسخ نمونه و معیار ارزیابی

کلید مستقیم در هدر گره نوشته شده و با فایل خروجی منتشر شده است. ترتیب: (۱) باطل‌کردن کلید و ساختن کلید تازه با کمترین اختیار؛ (۲) ساختن Credential از نوع Header Auth و حذف هدر دستی از گره؛ (۳) برداشتن یا ویرایش پست انجمن؛ (۴) بررسی مصرف و دسترسی‌های سامانه در بازه نشت.

  • کلید در گره و نشت آن (1 امتیاز)
  • باطل‌کردن کلید اول (1 امتیاز)
  • انتقال به Credential (1 امتیاز)
  • فقط پست را پاک کن ← کلیدی که منتشر شده، نشت کرده است؛ باید باطل شود.

API سفارش‌ها پارامتر page (از ۱) دارد و پاسخش {"data": [...], "next_page": 2} است و در صفحه آخر next_page برابر null. تنظیم صفحه‌بندی گره HTTP Request را بنویس.

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

Pagination Mode: Update a Parameter in Each Request؛ Type: Query؛ Name: page؛ Value: {{ $pageCount + 1 }}؛ توقف وقتی {{ $response.body.next_page === null }} (یا معادل در تنظیم توقف نسخه جاری)؛ به‌علاوه سقف تعداد صفحه برای ایمنی.

  • حالت Update a Parameter با page (1 امتیاز)
  • $pageCount + 1 (1 امتیاز)
  • شرط توقف بر اساس next_page و سقف (1 امتیاز)
  • {{ $pageCount }} ← $pageCount از صفر شروع می‌شود؛ صفحه اول API شماره ۱ است.

ورک‌فلوی «سفارشم کجاست؟» برای شماره سفارش ناموجود از API پاسخ 404 می‌گیرد و گره قرمز می‌شود. همکارت می‌خواهد Never Error را روشن کند. موافقی؟ طرح کاملت را بنویس.

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

به شرط اینکه کد وضعیت را خودمان بررسی کنیم. Never Error و Include Response Headers and Status را روشن کن؛ بعد If: اگر statusCode برابر 200 ← ادامه پاسخ؛ اگر 404 ← مسیر «سفارش پیدا نشد» (درخواست شماره درست از مشتری)؛ هر کد دیگر (401، 5xx) ← مسیر خطا و هشدار. بدون این If، Never Error خطاهای واقعی را پنهان می‌کند.

  • Never Error فقط با بررسی کد (1 امتیاز)
  • 404 به‌عنوان نتیجه عادی با مسیر جدا (1 امتیاز)
  • کدهای دیگر به مسیر خطا (1 امتیاز)
  • Never Error و تمام ← 401 و 500 هم موفق حساب می‌شوند.

دستور curl مستندات یک API را با Import cURL وارد گره کرده‌ای. بدنه شامل "qty": 3 و "urgent": true بود. پس از وارد کردن، API خطای نوع داده می‌دهد. محتمل‌ترین علت؟

  • Import cURL مقدارها را به‌شکل رشته وارد کرده است؛ بدنه را با حالت JSON بچسبان.
  • API از n8n پشتیبانی نمی‌کند.
  • Credential اشتباه است.
  • باید صفحه‌بندی را روشن کرد.
پاسخ نمونه و معیار ارزیابی
  • b ← API فقط HTTP می‌بیند؛ ابزار فرستنده برایش مهم نیست.
  • c ← Credential غلط معمولاً 401 یا 403 می‌دهد، نه خطای نوع.
  • d ← صفحه‌بندی ربطی به نوع بدنه ندارد.

تیم سه ورک‌فلو دارد که همه با یک Credential «Orders Admin» به سامانه سفارش وصل‌اند: گزارش هفتگی (فقط خواندن)، ربات پیام‌رسان (فقط خواندن) و بایگانی سفارش‌های لغوشده (خواندن و تغییر). چه پیشنهادی داری؟

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

سه Credential جدا با کمترین اختیار: دو Credential فقط‌خواندنی برای گزارش و ربات (ربات چون رو به بیرون است اهمیت بیشتری دارد) و یکی با اختیار تغییر محدود برای بایگانی. نام‌های گویا، صاحب مشخص، و Credential جدا برای محیط آزمون و تولید. اگر سامانه اختیار جزئی ندارد، دست‌کم کلید جدا تا نشت یکی همه را از کار نیندازد.

  • Credential جدا برای هر کار (1 امتیاز)
  • کمترین اختیار به‌ویژه برای ربات (1 امتیاز)
  • یکی کافی است ← نشت Credential ربات یعنی دسترسی تغییر سفارش‌ها برای مهاجم.

فایل‌های درس

API آزمایشی با صفحه‌بندی و کلید

barg-sabz-mock-api.py

پاسخ سه صفحه سفارش و پرسش‌های مسیر بدون نصب

pagination-trace.md

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

  • n8n 2.x — Credential و HTTP Request — n8n Cloud در صورت دسترسی قانونی — مسیر بدون نصب
  • Python 3.9 یا بالاتر — API آزمایشی — مسیر بدون نصب

منابع

Use Docker Compose n8n accessed 2026-10-16; stable 2.43.6, beta 2.44.2 at access time

HTTP Request node n8n accessed 2026-10-16

Pagination in the HTTP Request node n8n accessed 2026-10-20

دوره

n8n از پایه