Credentials, HTTP Request and Pagination
Keep keys in credentials, call any API with the HTTP Request node, read every page with built-in pagination, and surface error responses.
بعد از این درس میتوانی
- برای یک 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
این تشبیه کجا غلط است؟ کارت ورود را اگر کسی از صندوق بردارد، دیده میشود. 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. حدود ۲۲ دقیقه.
اجرای محلی
- API آزمایشی (shared/barg-sabz-mock-api.py) را با
--host 0.0.0.0اجرا کن (مثل درس دوم). - Credential از نوع Header Auth با نام «Barg Sabz Mock API (local)» بساز.
- گره HTTP Request:
GET http://host.docker.internal:8787/ordersبا پارامترlimitبرابر ۳ و Credential بالا. صفحهبندی را با حالت Update a Parameter و{{ $pageCount + 1 }}تنظیم کن و شرط توقف را بر اساسnext_pageبگذار. - اجرا کن: باید سه درخواست ببینی و در مجموع هفت سفارش. اگر خروجی بهشکل سه آیتم (هر صفحه یکی) است، با Split Out روی
dataآنها را جدا کن. - یک گره HTTP Request دیگر:
POST /ticketsبا بدنه JSON و همان Credential. یک بار با هدرIdempotency-Keyو یک بار بدون آن اجرا کن وGET /ticketsرا ببین. - یک بار 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 و حالت صفحهبندی را بنویس.
- سرویسی که n8n برایش گره و Credential آماده دارد.
- API داخلی که کلید را در هدر
X-API-Keyمیخواهد و در پاسخ"next": "https://.../items?cursor=abc"میدهد. - 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 آزمایشی برگ سبز یا داده ساختگی استفاده کن.
- Credential درست با نام گویا و کمترین اختیار.
- اگر داده چندصفحهای است، صفحهبندی با شرط توقف و سقف؛ شمار کل را با منبع مقایسه کن.
- تصمیم درباره Never Error: کدام کدهای وضعیت «نتیجه عادی»اند و کدام خطا؟
- خروجی ورکفلو را بگیر و بررسی کن هیچ کلیدی در فایل نیست.
خروجی مورد انتظار: ورکفلو (یا خروجی 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