پرش به محتویات

مستندات نود درخواست HTTP#

درخواست HTTP یکی از چندمنظوره‌ترین نودها در n98n است. این امکان را به شما می‌دهد تا درخواست‌های HTTP بسازید و داده‌ها را از هر برنامه یا سرویس با API REST پرس و جو کنید. می‌توانید از نود درخواست HTTP به صورت معمولی یا به عنوان قسمت متصل به یک عامل هوش مصنوعی برای استفاده به عنوان یک ابزار بهره ببرید.

هنگام استفاده از این نود، در حال ایجاد یک تماس API REST هستید. نیاز است که با مفاهيم پایه API و مفاهیم مرتبط آشنا باشید.

دو روش برای ساخت درخواست HTTP وجود دارد: پیکربندی پارامترهای نود یا وارد کردن یک دستور curl.

اعتبارنامه‌ها

مراجعه کنید به اعتبارنامه‌های درخواست HTTP برای راهنمایی در راه‌اندازی احراز هویت.

پارامترهای نود#

روش#

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

  • DELETE
  • GET
  • HEAD
  • OPTIONS
  • PATCH
  • POST
  • PUT

URL#

نشانی endpoint که می‌خواهید استفاده کنید را وارد کنید.

احراز هویت#

n98n پیشنهاد می‌کند در صورت امکان از گزینه نوع اعتبارنامه‌ از قبل تعریف‌شده استفاده کنید. این روش مدیریت و پیکربندی اعتبارنامه‌ها را آسان‌تر می‌کند، در مقایسه با تنظیم اعتبارنامه‌های عمومی.

اعتبارنامه‌های از پیش تعریف‌شده#

اعتبارنامه‌هایی برای ادغام‌هایی که توسط n98n پشتیبانی می‌شود، شامل نودهای داخلی و کامیونیتی. از نوع اعتبارنامه‌ از قبل تعریف‌شده برای عملیات‌های سفارشی بدون نیاز به تنظیمات اضافی استفاده کنید. برای اطلاعات بیشتر به عملیات API سفارشی مراجعه کنید.

اعتبارنامه‌های عمومی#

اعتبارنامه‌هایی برای ادغام‌هایی که توسط n98n پشتیبانی نمی‌شوند. باید فرآیند احراز هویت را به صورت دستی پیکربندی کنید، شامل تعیین APIهای مورد نیاز، پارامترهای لازم، و روش احراز هویت.

می‌توانید یکی از روش‌های زیر را انتخاب کنید:

  • احراز هویت پایه
  • احراز هویت سفارشی
  • امضای احراز هویت (Digest)
  • احراز هویت از طریق هدرها
  • API OAuth1
  • API OAuth2
  • احراز هویت استعلام (Query)

برای اطلاعات بیشتر در مورد راه‌اندازی هر نوع اعتبارنامه‌، به اعتبارنامه‌ درخواست HTTP مراجعه کنید.

ارسال پارامترهای استعلام#

پارامترهای استعلام مانند فیلترهایی روی درخواست‌های HTTP عمل می‌کنند. اگر API مورد استفاده شما این قابلیت را پشتیبانی می‌کند و درخواست شما نیاز به فیلتر دارد، این گزینه را فعال کنید.

پارامترهای استعلام خود را با یکی از گزینه‌های زیر مشخص کنید:

  • با استفاده از فیلدهای زیر: زوج‌های نام/مقدار برای پارامترهای استعلام وارد کنید. برای افزودن زوج‌های بیشتری، گزینه افزودن پارامتر را انتخاب کنید. نام، نام فیلد فیلتر شده است و مقدار، مقدار فیلتر.
  • با استفاده از JSON: برای تعریف پارامترهای استعلام، JSON وارد کنید.

برای راهنمایی دقیق، به مستندات API سرویس خود مراجعه کنید.

ارسال هدرها#

از این گزینه برای ارسال هدرها با درخواست خود استفاده کنید. هدرها شامل متادیتا یا کانتکست درباره درخواست شما هستند.

هدرها را با یکی از گزینه‌های زیر تعریف کنید:

  • با استفاده از فیلدهای زیر: زوج‌های نام/مقدار برای پارامترهای هدر وارد کنید. برای افزودن زوج‌های بیشتر، گزینه افزودن پارامتر را انتخاب کنید. نام، هدر موردنظر است و مقدار، مقدار هدر.
  • با استفاده از JSON: برای تعیین پارامترهای هدر، JSON وارد کنید.

برای راهنمایی، به مستندات API سرویس خود مراجعه کنید.

ارسال Body#

اگر نیاز دارید یک بدنه (Body) همراه با درخواست API خود ارسال کنید، این گزینه را فعال کنید.

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

لود URL فرم#

از این گزینه برای ارسال بدنه به صورت application/x-www-form-urlencoded استفاده کنید.

بدنه را با یکی از گزینه‌های زیر مشخص کنید:

  • با استفاده از فیلدهای زیر: زوج‌های نام/مقدار برای پارامترهای بدنه وارد کنید. نام باید نام فیلد فرم باشد و مقدار، مقدار دلخواه برای آن فیلد.
  • با استفاده از تک فیلد: زوج‌های نام/مقدار خود را در یک پارامتر بدنه با فرمت fieldname1=value1&fieldname2=value2 وارد کنید.

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

فرم-دیتا#

از این گزینه برای ارسال بدنه به صورت multipart/form-data استفاده کنید.

پیکربندی پارامترهای بدنه خود را با انتخاب نوع پارامتر انجام دهید:

  • فرم دیتا: زوج‌های نام/مقدار وارد کنید.
  • n98n Binary File: محتویات فایل باینری را که در اختیار نود است، بارگذاری کنید.
  • نام: شناسه فیلد موردنظر برای تنظیم.
  • نام فیلد ورودی داده: نام فیلد ورودی که حاوی داده فایل باینری است.

برای افزودن پارامترهای بیشتر، گزینه افزودن پارامتر را انتخاب کنید.

برای راهنمایی، به مستندات API سرویس خود مراجعه کنید.

JSON#

از این گزینه برای ارسال بدنه به صورت JSON استفاده کنید.

بدنه را با یکی از گزینه‌های زیر تعریف کنید:

  • با استفاده از فیلدهای زیر: زوج‌های نام/مقدار برای پارامترهای بدنه وارد کنید. برای افزودن پارامترهای بیشتر، گزینه افزودن پارامتر را بزنید.
  • با استفاده از JSON: JSON موردنظر را وارد کنید.

برای مطالعه دقیق‌تر، به مستندات API خود مراجعه کنید.

فایل باینری n8n#

از این گزینه برای ارسال محتویات فایلی در n98n به عنوان بدنه استفاده کنید.

نام فیلد ورودی فایل را وارد کنید که حاوی فایل است، در قسمت نام فیلد داده ورودی.

برای قالب‌بندی صحیح فایل، به مستندات API خود مراجعه کنید.

Raw#

برای ارسال داده خام در بدنه، از این گزینه استفاده کنید.

  • نوع محتوا: هدر Content-Type موردنظر برای بدنه خام را وارد کنید. برای لیست کامل MIME types، به مستندات IANA Media types مراجعه کنید.
  • بدنه: محتویات خام بدنه را وارد کنید.

برای اطلاعات بیشتر، به مستندات API خود مراجعه کنید.

گزینه‌های نود#

در قسمت افزودن گزینه، می‌توانید این گزینه‌ها را مشاهده و انتخاب کنید. این گزینه‌ها برای همه پارامترها در دسترس هستند، مگر اینکه به صورت خاص ذکر شده باشد.

قالب آرایه در پارامترهای استعلام#

در دسترس بودن گزینه

این گزینه فقط زمانی قابل استفاده است که گزینه ارسال پارامترهای استعلام فعال باشد.

از این گزینه برای کنترل قالب آرایه‌های داخل پارامترهای استعلام بهره ببرید. گزینه‌های موجود:

  • بدون براکت: آرایه‌ها به صورت نام=مقدار برای هر آیتم در آرایه قالب‌بندی می‌شوند، مانند: foo=bar&foo=qux.
  • فقط براکت‌ها: پس از نام هر آرایه، با براکت‌های مربعی قرار می‌گیرد، مانند: foo[]=bar&foo[]=qux.
  • براکت‌ها با اندیس: براکت همراه با شاخص بعد از نام آرایه قرار می‌گیرد، مانند: foo[0]=bar&foo[1]=qux.

برای راهنمایی، به مستندات API سرویس خود مراجعه کنید.

دسته‌بندی (Batching)#

نحوه دسته‌بندی تعداد زیادی آیتم ورودی را کنترل کنید:

  • تعداد در هر دسته: تعداد آیتم‌هایی که در هر دسته قرار می‌گیرند را وارد کنید.
  • بازه دسته‌بندی: مدت زمان بین هر درخواست دسته‌ای، به میلی‌ثانیه. مقدار صفر به معنی عدم تاخیر است.

نادیده‌گیری از مشکلات SSL#

به صورت پیش‌فرض، n98n تنها اگر اعتبارنامه‌ گواهینامه SSL موفق باشد، پاسخ را دانلود می‌کند. اگر می‌خواهید پاسخ را حتی در صورت شکست اعتبارنامه‌، دانلود کنید، این گزینه را فعال کنید.

حروف کوچک در هدرها#

انتخاب کنید که آیا نام‌های هدر به صورت حروف کوچک باشند (فعال، پیش‌فرض) یا خیر (غیرفعال).

ریدایرکت‌ها#

انتخاب کنید که درخواست‌ها به ریدایرکت‌ها دنبال شوند (پیش‌فرض فعال) یا نه (غیرفعال). در صورت فعال بودن، حداکثر تعداد ریدایرکت‌هایی که درخواست باید دنبال کند، در حداکثر ریدایرکت‌ها وارد کنید.

پاسخ#

از این گزینه برای تنظیم جزئیاتی درباره پاسخ مورد انتظار API استفاده کنید، از جمله:

  • شامل هدرها و وضعیت پاسخ: به صورت پیش‌فرض، تنها بدنه برگردانده می‌شود. با فعال کردن این گزینه، پاسخ کامل (هدرها و وضعیت پاسخ) به همراه بدنه برمی‌گردد.
  • هرگز خطا نده: پیش‌فرض، در صورت دریافت پاسخ با کد 2xx، موفقیت درنظر گرفته می‌شود. با فعال کردن این گزینه، در هر صورت موفقیت برمی‌گردد.
  • قالب پاسخ: قالبی که در آن داده‌ها برگردانده می‌شوند را انتخاب کنید:
  • خودکار (پیش‌فرض): نود بر اساس داده‌های برگردانده شده، پاسخ را تشخیص و قالب‌بندی می‌کند.
  • فایل: برای قرار دادن پاسخ در یک فایل این گزینه را انتخاب کنید. نام فیلدی که در آن فایل قرار می‌گیرد را وارد کنید در قرار دادن خروجی در فیلد.
  • JSON: برای قالب‌بندی پاسخ به صورت JSON.
  • متن: برای قالب‌بندی پاسخ به صورت متن ساده، نام فیلد خروجی را وارد کنید در قرار دادن خروجی در فیلد.

صفحه‌بندی (Pagination)#

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

قبل از پیکربندی صفحه‌بندی، ابتدا داده‌های API را بررسی کنید

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

درک مفهوم صفحه‌بندی

صفحه‌بندی یعنی تقسیم یک مجموعه بزرگ داده به چندین صفحه. اندازه هر صفحه بر اساس محدودیتی که تعیین می‌کنید، متفاوت است.

برای مثال، درخواست API به endpoint /users. API قصد دارد اطلاعات مربوط به 300 کاربر را برگرداند، اما این مقدار داده، بیش از حد است که در یک پاسخ ارسال شود.

اگر API قابلیت صفحه‌بندی را پشتیبانی کند، می‌توانید داده را به صورت تدریجی دریافت کنید. برای این کار، درخواست به /users با محدودیت صفحه و شماره صفحه یا URL آن ارسال می‌شود تا API مشخص کند کدام صفحه را برگرداند. در این مثال، فرض کنید محدودیت 10 است و از صفحه 0 شروع می‌کنید. API 10 کاربر اول را در پاسخ برمی‌گرداند. سپس دوباره درخواست می‌دهید، شماره صفحه را افزایش می‌دهید و نتیجه بعدی را دریافت می‌کنید.

تنظیمات صفحه‌بندی را پیکربندی کنید:

  • حالت صفحه‌بندی:
  • خاموش: صفحه‌بندی را غیرفعال کنید.
  • بروزرسانی پارامتر در هر درخواست: هنگامی که نیاز دارید پارامترهای دینامیک در هر درخواست تنظیم کنید.
  • پاسخ شامل URL بعدی: در صورتیکه پاسخ API شامل URL صفحه بعد است، از این گزینه استفاده کنید و با یک عبارت، URL بعدی را تنظیم کنید.

برای نمونه، به کتاب‌کار درخواست HTTP | صفحه‌بندی مراجعه کنید.

در n8n، متغیرهای داخلی برای کار با درخواست‌ها و پاسخ‌های نود HTTP در زمان صفحه‌بندی وجود دارد:

Variable توضیحات
$pageCount تعداد صفحه‌بندی. تعداد صفحاتی که نود بارگذاری کرده است را پیگیری می‌کند.
$request شیء درخواست ارسالی توسط نود HTTP.
$response شیء پاسخ از تماس HTTP. شامل $response.body، $response.headers، و $response.statusCode. محتویات body و headers بستگی به داده‌هایی دارد که توسط API ارسال شده است. 
1
2
3
4
5
6
7
/// note | تفاوت‌های API
روش‌های مختلف API صفحه‌بندی را به روش‌های متفاوتی پیاده‌سازی می‌کنند. برای جزئیات، مستندات API مورد استفاده خود را بررسی کنید. باید مواردی مانند موارد زیر را بدانید:

* آیا API آدرس URL صفحه بعدی را ارائه می‌دهد؟
* آیا محدودیت‌های خاصی بر اندازه صفحه یا شماره صفحه در API وجود دارد؟
* ساختار داده‌هایی که API برمی‌گرداند چگونه است؟
///

پراکسی (Proxy)#

در صورت نیاز به مشخص کردن یک سرور پراکسی HTTP، از این گزینه استفاده کنید.

آدرس پراکسی مورد نظر را وارد کنید.

تایم‌اوت#

برای تنظیم مدت زمانی که نود باید برای دریافت هدرهای پاسخ سرور منتظر بماند (و شروع بدنه پاسخ)، از این گزینه بهره ببرید. درخواست‌هایی که این زمان را رد کنند، متوقف می‌شود.

زمان تایم‌اوت را بر حسب میلی‌ثانیه وارد کنید.

گزینه‌های فقط ابزار#

گزینه‌های زیر فقط زمانی فعال می‌شوند که نود به عنوان ابزار به یک عامل هوش مصنوعی متصل باشد.

بهینه‌سازی پاسخ#

این گزینه مشخص می‌کند که آیا پاسخ ابزار برای کاهش حجم داده‌های ارسالی به LLM به صورت بهینه‌سازی شود یا خیر. این کار می‌تواند هزینه‌ها را کاهش دهد و باعث شود LLM جزئیات مهم را نادیده بگیرد، که اغلب منجر به نتایج بهتر می‌شود.

در هنگام بهینه‌سازی پاسخ، نوع پاسخ مورد انتظار را انتخاب می‌کنید که سایر گزینه‌های قابل پیکربندی را تعیین می‌کند. انواع پاسخ‌های پشتیبانی شده عبارتند از:

JSON#

هنگام انتظار پاسخ JSON، می‌توانید بخش‌هایی از داده‌های JSON که می‌خواهید به عنوان پاسخ استفاده کنید، با گزینه‌های زیر مشخص کنید:

  • فیلد شامل داده‌ها: این فیلد بخش خاصی از شی JSON را که شامل داده‌های مرتبط است، شناسایی می‌کند. می‌توانید این فیلد را خالی بگذارید تا کل پاسخ استفاده شود.
  • شامل فیلدها: تعیین می‌کند که کدام فیلدها در شی پاسخ قرار بگیرند. سه گزینه وجود دارد:
    • همه: شامل تمام فیلدها در شی پاسخ.
    • انتخاب شده: فقط فیلدهای مشخص شده را شامل کنید.
      • فیلدها: لیستی با جداکننده ویرگول برای فیلدها. می‌توانید از نوتیشن نقطه‌ای برای فیلدهای تو در تو استفاده کنید. می‌توانید فیلدها را از پنل ورودی کشیده و به لیست فیلدها اضافه کنید.
    • استثنا: شامل تمام فیلدها به جز فیلدهای مشخص شده در زیر.
      • فیلدها: لیستی با جداکننده ویرگول از فیلدهای موردنظر برای استثنا. می‌توانید از نوتیشن نقطه‌ای بهره ببرید و فیلدها را کشیده و به لیست اضافه کنید.

HTML#

هنگام انتظار پاسخ HTML، می‌توانید قسمت مرتبط از یک سند HTML را برای پاسخ شناخته و آن را بهینه‌سازی کنید با گزینه‌های زیر:

  • گزینشگر (CSS): المنت مشخص یا نوع المنت برای شامل‌شدن در پاسخ HTML. پیش‌فرض، عنصر body است.
  • بازگرداندن فقط محتوا: آیا می‌خواهید تگ‌های HTML و ویژگی‌های آن را پاک کنید و تنها محتوا باقی بماند. این باعث کاهش توکن‌ها می‌شود و درک مدل آسان‌تر است.
    • عناصر برای حذف: لیستی از جدا شده با ویرگول از انتخابنودای CSS برای حذف هنگام استخراج محتوا.
  • کاهش اندازه پاسخ: آیا می‌خواهید اندازه پاسخ محدود شود تا توکن‌ها صرفه‌جویی شود.
    • حداکثر تعداد کاراکترهای پاسخ: حداکثر تعداد کاراکتر در پاسخ HTML. مقدار پیش‌فرض 1000 است.

متن#

برای انتظار پاسخ متن کلی، این گزینه‌ها برای بهینه‌سازی نتایج وجود دارد:

  • کاهش اندازه پاسخ: تصمیم به محدود کردن پاسخ برای صرفه‌جویی در توکن‌ها.
    • حداکثر کاراکترهای پاسخ: حداکثر تعداد کاراکتر در پاسخ متن. مقدار پیش‌فرض، 1000 است.

وارد کردن دستور curl#

curl ابزاری خط فرمان و کتابخانه‌ای برای انتقال داده با URL است.

می‌توانید از curl برای فراخوانی APIهای REST بهره ببرید. اگر توصیف API سرویس موردنظر شما نمونه‌هایی از curl دارد، می‌توانید آن‌ها را کپی کرده و در n98n برای پیکربندی نود درخواست HTTP وارد کنید.

برای وارد کردن یک دستور curl:

  1. از تب پارامترهای نود درخواست HTTP، گزینه وارد کردن cURL را انتخاب کنید. پنجره مودال وارد کردن دستور cURL باز می‌شود.
  2. دستور curl خود را در جعبه متن قرار دهید.
  3. روی وارد کردن کلیک کنید. n98n پیکربندی درخواست را به فیلدهای نود بارگذاری می‌کند. این عملیات، هر پیکربندی قبلی را جایگزین می‌کند.

قالب‌ها و نمونه‌ها#

Browse HTTP Request integration templates, or search all templates

مسائل رایج#

برای سوالات یا مشکلات رایج و راه‌حل‌های پیشنهادی، به مسائل رایج مراجعه کنید.