Class UrlFetchApp

برنامه‌ی UrlFetch

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

این سرویس به اسکریپت‌ها اجازه می‌دهد تا با دریافت URLها با سایر برنامه‌ها ارتباط برقرار کنند یا به منابع دیگر در وب دسترسی پیدا کنند. یک اسکریپت می‌تواند از سرویس URL Fetch برای صدور درخواست‌های HTTP و HTTPS و دریافت پاسخ استفاده کند. سرویس URL Fetch از زیرساخت شبکه گوگل برای اهداف کارایی و مقیاس‌پذیری استفاده می‌کند.

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

این سرویس به دامنه https://www.googleapis.com/auth/script.external_request نیاز دارد. در بیشتر موارد، Apps Script به طور خودکار دامنه‌هایی را که یک اسکریپت نیاز دارد شناسایی و لحاظ می‌کند، اما اگر دامنه‌های خود را به صراحت تنظیم می‌کنید، باید این دامنه را به صورت دستی برای استفاده UrlFetchApp اضافه کنید.

همچنین ببینید

روش‌ها

روش نوع بازگشتی شرح مختصر
fetch(url) HTTPResponse درخواستی برای دریافت یک URL ارسال می‌کند.
fetch(url, params) HTTPResponse با استفاده از پارامترهای پیشرفته اختیاری، درخواستی برای دریافت یک URL ارسال می‌کند.
fetch All(requests) HTTPResponse[] با استفاده از پارامترهای پیشرفته اختیاری، چندین درخواست برای دریافت چندین URL ارسال می‌کند.
get Request(url) Object درخواستی را که در صورت فراخوانی عملیات انجام شده است، برمی‌گرداند.
get Request(url, params) Object درخواستی را که در صورت فراخوانی عملیات انجام می‌شود، برمی‌گرداند.

مستندات دقیق

fetch(url)

درخواستی برای دریافت یک URL ارسال می‌کند.

این هم روی HTTP و هم روی HTTPS کار می‌کند.

// The code below logs the HTML code of the Google home page.
const response = UrlFetchApp.fetch('http://www.google.com/');
Logger.log(response.getContentText());

پارامترها

نام نوع توضیحات
url String آدرس اینترنتی (URL) برای دریافت. این آدرس اینترنتی می‌تواند تا ۲۰۸۲ کاراکتر داشته باشد.

بازگشت

HTTPResponse — داده‌های پاسخ HTTP.

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/script.external_request

fetch(url, params)

با استفاده از پارامترهای پیشرفته اختیاری، درخواستی برای دریافت یک URL ارسال می‌کند.

این هم روی HTTP و هم روی HTTPS کار می‌کند.

// Make a GET request and log the returned content.
const response = UrlFetchApp.fetch('http://www.google.com/');
Logger.log(response.getContentText());
// Make a POST request with form data.
const resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
const formData = {
  name: 'Bob Smith',
  email: 'bob@example.com',
  resume: resumeBlob,
};
// Because payload is a JavaScript object, it is interpreted as
// as form data. (No need to specify contentType; it automatically
// defaults to either 'application/x-www-form-urlencoded'
// or 'multipart/form-data')
const options = {
  method: 'post',
  payload: formData,
};
UrlFetchApp.fetch('https://httpbin.org/post', options);
// Make a POST request with a JSON payload.
const data = {
  name: 'Bob Smith',
  age: 35,
  pets: ['fido', 'fluffy'],
};
const options = {
  method: 'post',
  contentType: 'application/json',
  // Convert the JavaScript object to a JSON string.
  payload: JSON.stringify(data),
};
UrlFetchApp.fetch('https://httpbin.org/post', options);

پارامترها

نام نوع توضیحات
url String آدرس اینترنتی (URL) برای دریافت. این آدرس اینترنتی می‌تواند تا ۲۰۸۲ کاراکتر داشته باشد.
params Object شیء جاوا اسکریپت اختیاری که پارامترهای پیشرفته‌ای را مطابق تعریف زیر مشخص می‌کند.

پارامترهای پیشرفته

نام نوع توضیحات
content Type String نوع محتوا (پیش‌فرض روی 'application/x-www-form-urlencoded') است. مثال دیگری از نوع محتوا 'application/xml; charset=utf-8' است.
headers Object یک نقشه کلید/مقدار جاوا اسکریپت از هدرهای HTTP برای درخواست
method String متد HTTP برای درخواست: get ، delete ، patch ، post یا put . مقدار پیش‌فرض get است.
payload String بار داده (یعنی بدنه POST) برای درخواست. برخی از روش‌های HTTP (به عنوان مثال، GET) بار داده را نمی‌پذیرند. این می‌تواند یک رشته، یک آرایه بایت، یک blob یا یک شیء جاوا اسکریپت باشد. یک شیء جاوا اسکریپت به عنوان نگاشتی از نام‌های فیلدهای فرم به مقادیر تفسیر می‌شود، که در آن مقادیر می‌توانند رشته یا blob باشند.
use Intranet Boolean منسوخ شده. این دستور، fetch را برای حل URL مشخص شده در اینترانت لینک شده به دامنه شما از طریق SDC (منسوخ شده) راهنمایی می‌کند.
validate Https Certificates Boolean اگر مقدار آن false واکشی هرگونه گواهی نامعتبر برای درخواست‌های HTTPS را نادیده می‌گیرد. مقدار پیش‌فرض true است.
follow Redirects Boolean اگر مقدار آن false واکشی به طور خودکار ریدایرکت‌های HTTP را دنبال نمی‌کند؛ بلکه پاسخ HTTP اصلی را برمی‌گرداند. مقدار پیش‌فرض true است.
mute Http Exceptions Boolean اگر true اگر کد پاسخ نشان‌دهنده‌ی شکست باشد، fetch هیچ استثنایی ایجاد نمی‌کند و در عوض HTTPResponse را برمی‌گرداند. مقدار پیش‌فرض false است.
escaping Boolean اگر کاراکترهای رزرو شده false در URL به صورت escape شده نباشند، مقدار پیش‌فرض true است.

بازگشت

HTTPResponse — داده‌های پاسخ HTTP.

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/script.external_request

fetchAll(requests)

با استفاده از پارامترهای پیشرفته اختیاری، چندین درخواست برای دریافت چندین URL ارسال می‌کند.

این هم روی HTTP و هم روی HTTPS کار می‌کند.

// Make both a POST request with form data, and a GET request.
const resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
const formData = {
  name: 'Bob Smith',
  email: 'bob@example.com',
  resume: resumeBlob,
};
// Because payload is a JavaScript object, it is interpreted as
// as form data. (No need to specify contentType; it defaults to either
// 'application/x-www-form-urlencoded' or 'multipart/form-data')
const request1 = {
  url: 'https://httpbin.org/post',
  method: 'post',
  payload: formData,
};
// A request may also just be a URL.
const request2 = 'https://httpbin.org/get?key=value';
UrlFetchApp.fetchAll([request1, request2]);

پارامترها

نام نوع توضیحات
requests Object[] آرایه‌ای از URLها یا اشیاء جاوا اسکریپت که درخواست‌ها را مطابق تعریف زیر مشخص می‌کنند.

پارامترهای پیشرفته

نام نوع توضیحات
url String آدرس اینترنتی (URL) برای دریافت. این آدرس اینترنتی می‌تواند تا ۲۰۸۲ کاراکتر داشته باشد.
content Type String نوع محتوا (پیش‌فرض روی 'application/x-www-form-urlencoded') است. مثال دیگری از نوع محتوا 'application/xml; charset=utf-8' است.
headers Object یک نقشه کلید/مقدار جاوا اسکریپت از هدرهای HTTP برای درخواست
method String متد HTTP برای درخواست: get ، delete ، patch ، post یا put . مقدار پیش‌فرض get است.
payload String بار داده (یعنی بدنه POST) برای درخواست. برخی از روش‌های HTTP (به عنوان مثال، GET) بار داده را نمی‌پذیرند. این می‌تواند یک رشته، یک آرایه بایت، یک blob یا یک شیء جاوا اسکریپت باشد. یک شیء جاوا اسکریپت به عنوان نگاشتی از نام‌های فیلدهای فرم به مقادیر تفسیر می‌شود، که در آن مقادیر می‌توانند رشته یا blob باشند.
use Intranet Boolean منسوخ شده. این دستور، fetch را برای حل URL مشخص شده در اینترانت لینک شده به دامنه شما از طریق SDC (منسوخ شده) راهنمایی می‌کند.
validate Https Certificates Boolean اگر مقدار آن false واکشی هرگونه گواهی نامعتبر برای درخواست‌های HTTPS را نادیده می‌گیرد. مقدار پیش‌فرض true است.
follow Redirects Boolean اگر مقدار آن false واکشی به طور خودکار ریدایرکت‌های HTTP را دنبال نمی‌کند؛ بلکه پاسخ HTTP اصلی را برمی‌گرداند. مقدار پیش‌فرض true است.
mute Http Exceptions Boolean اگر مقدار true ، اگر کد پاسخ نشان‌دهنده‌ی شکست باشد، واکشی هیچ استثنایی ایجاد نمی‌کند و در عوض HTTPResponse را برمی‌گرداند. مقدار پیش‌فرض false است.
escaping Boolean اگر false ، کاراکترهای رزرو شده در URL از حالت escape خارج نمی‌شوند. مقدار پیش‌فرض true است.

بازگشت

HTTPResponse[] — آرایه‌ای از داده‌های پاسخ HTTP از هر درخواست ورودی.

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/script.external_request

getRequest(url)

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

این روش در واقع درخواست را صادر نمی‌کند.

// The code below logs the value for every key of the returned map.
const response = UrlFetchApp.getRequest('http://www.google.com/');
for (const i in response) {
  Logger.log(`${i}: ${response[i]}`);
}

پارامترها

نام نوع توضیحات
url String آدرس اینترنتی (URL) مورد نظر برای جستجو. این آدرس اینترنتی می‌تواند تا ۲۰۸۲ کاراکتر داشته باشد.

بازگشت

Object - نقشه‌ای از نام فیلد به مقدار. این نقشه حداقل دارای کلیدهای زیر است: url ، method ، contentType ، payload و headers .

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/script.external_request

getRequest(url, params)

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

این روش در واقع درخواست را صادر نمی‌کند.

پارامترها

نام نوع توضیحات
url String آدرس اینترنتی (URL) مورد نظر برای جستجو. این آدرس اینترنتی می‌تواند تا ۲۰۸۲ کاراکتر داشته باشد.
params Object یک شیء جاوا اسکریپت اختیاری که پارامترهای پیشرفته‌ای را مطابق تعریف زیر مشخص می‌کند.

پارامترهای پیشرفته

نام نوع توضیحات
content Type String نوع محتوا (پیش‌فرض روی 'application/x-www-form-urlencoded') است. مثال دیگری از نوع محتوا 'application/xml; charset=utf-8' است.
headers Object یک نقشه کلید/مقدار جاوا اسکریپت از هدرهای HTTP برای درخواست
method String متد HTTP برای درخواست: get ، delete ، patch ، post یا put . مقدار پیش‌فرض get است.
payload String بار داده (یعنی بدنه POST) برای درخواست. برخی از روش‌های HTTP (به عنوان مثال، GET) بار داده را نمی‌پذیرند. این می‌تواند یک رشته، یک آرایه بایت، یک blob یا یک شیء جاوا اسکریپت باشد. یک شیء جاوا اسکریپت به عنوان نگاشتی از نام‌های فیلدهای فرم به مقادیر تفسیر می‌شود، که در آن مقادیر می‌توانند رشته یا blob باشند.
use Intranet Boolean منسوخ شده. این دستور، fetch را برای حل URL مشخص شده در اینترانت لینک شده به دامنه شما از طریق SDC (منسوخ شده) راهنمایی می‌کند.
validate Https Certificates Boolean اگر مقدار آن false واکشی هرگونه گواهی نامعتبر برای درخواست‌های HTTPS را نادیده می‌گیرد. مقدار پیش‌فرض true است.
follow Redirects Boolean اگر مقدار آن false واکشی به طور خودکار ریدایرکت‌های HTTP را دنبال نمی‌کند؛ بلکه پاسخ HTTP اصلی را برمی‌گرداند. مقدار پیش‌فرض true است.
mute Http Exceptions Boolean اگر true اگر کد پاسخ نشان‌دهنده‌ی شکست باشد، fetch هیچ استثنایی ایجاد نمی‌کند و در عوض HTTPResponse را برمی‌گرداند. مقدار پیش‌فرض false است.
escaping Boolean اگر کاراکترهای رزرو شده false در URL قابل escape نباشند، مقدار پیش‌فرض true است.

بازگشت

Object - نقشه‌ای از نام فیلد به مقدار. این نقشه حداقل دارای کلیدهای زیر است: url ، method ، contentType ، payload و headers .

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/script.external_request