Class UrlFetchApp

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
UrlFetchApp

يمكنك جلب الموارد والتواصل مع المضيفين الآخرين على الإنترنت.

تتيح هذه الخدمة للنصوص البرمجية التواصل مع التطبيقات الأخرى أو الوصول إلى موارد أخرى على الويب عن طريق جلب عناوين URL. ويمكن للنص البرمجي استخدام خدمة جلب عناوين URL لإصدار طلبات HTTP وHTTPS وتلقّي الردود. تستخدم خدمة "جلب عنوان URL" البنية الأساسية لشبكة Google لأغراض الكفاءة والقياس.

إنّ الطلبات المقدَّمة باستخدام هذه الخدمة تنشأ من مجموعة محدّدة من نطاقات عناوين IP. يمكنك البحث عن القائمة الكاملة لعناوين IP إذا كنت بحاجة إلى إضافة هذه الطلبات إلى القائمة المسموح بها أو الموافقة عليها.

تتطلب هذه الخدمة نطاق https://www.googleapis.com/auth/script.external_request. في معظم الحالات، تكتشف "برمجة التطبيقات" النطاقات التي يحتاج إليها النص البرمجي تلقائيًا وتتضمّنها، ولكن إذا كنت تضبط نطاقاتك بشكل صريح، عليك إضافة هذا النطاق يدويًا لاستخدام UrlFetchApp.

راجع أيضًا

الطُرق

الطريقةنوع الإرجاعوصف قصير
fetch(url)HTTPResponseيتم تقديم طلب لجلب عنوان URL.
fetch(url, params)HTTPResponseتقدّم طلبًا لجلب عنوان URL باستخدام معلمات متقدمة اختيارية.
fetchAll(requests)HTTPResponse[]تقديم طلبات متعددة لجلب عناوين URL متعددة باستخدام معلمات متقدمة اختيارية.
getRequest(url)Objectتعرض الطلب الذي تم تقديمه إذا تم استدعاء العملية.
getRequest(url, params)Objectتعرض الطلب الذي تم تقديمه إذا تم استدعاء العملية.

المستندات التفصيلية

fetch(url)

يتم تقديم طلب لجلب عنوان URL.

ويعمل هذا مع HTTP وكذلك HTTPS.

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

المَعلمات

الاسمالنوعالوصف
urlStringعنوان URL للاسترجاع. يمكن أن يتضمّن عنوان URL ما يصل إلى 2,082 حرفًا.

تذكرة ذهاب وعودة

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.
var response = UrlFetchApp.fetch('http://www.google.com/');
Logger.log(response.getContentText());
// Make a POST request with form data.
var resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
var 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')
var options = {
  'method' : 'post',
  'payload' : formData
};
UrlFetchApp.fetch('https://httpbin.org/post', options);
// Make a POST request with a JSON payload.
var data = {
  'name': 'Bob Smith',
  'age': 35,
  'pets': ['fido', 'fluffy']
};
var 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);

المَعلمات

الاسمالنوعالوصف
urlStringعنوان URL للاسترجاع. يمكن أن يتضمّن عنوان URL ما يصل إلى 2,082 حرفًا.
paramsObjectعنصر JavaScript اختياري يحدد مَعلمات متقدمة كما هو موضّح أدناه.

المعلمات المتقدمة

الاسمالنوعالوصف
contentTypeStringنوع المحتوى (يتم ضبطه تلقائيًا على 'application/x-www-form-urlencoded'). من الأمثلة الأخرى على نوع المحتوى هو 'application/xml; charset=utf-8'.
headersObjectربط مفتاح/قيمة JavaScript لرؤوس HTTP للطلب
methodStringطريقة HTTP للطلب: get أو delete أو patch أو post أو put. والقيمة التلقائية هي get.
payloadStringالحمولة (أي نص طريقة POST) للطلب. لا تقبل بعض طرق HTTP (مثل GET) الحمولة. ويمكن أن تكون سلسلة أو مصفوفة بايت أو كائن ثنائي كبير أو كائن JavaScript. يتم تفسير كائن JavaScript على أنه خريطة لأسماء حقول القيم، حيث يمكن أن تكون القيم سلاسل أو كائن ثنائي كبير.
useIntranetBooleanتمّ الإيقاف. يؤدي هذا إلى توجيه الجلب لحل عنوان URL المحدد ضمن الشبكة الداخلية المرتبطة بنطاقك من خلال إيقاف (SDC) (متوقف)
validateHttpsCertificatesBooleanإذا تجاهل false استرجاع أي شهادات غير صالحة لطلبات HTTPS. والقيمة التلقائية هي true.
followRedirectsBooleanإذا لم يتّبع جلب البيانات false عمليات إعادة توجيه HTTP تلقائيًا، سيعرض استجابة HTTP الأصلية. والقيمة التلقائية هي true.
muteHttpExceptionsBooleanإذا لم يتم إجراء عملية الجلب في true، لن يتم إرسال استثناء إذا كان رمز الاستجابة يشير إلى تعذُّر التشغيل، وبدلاً من ذلك يتم عرض HTTPResponse. والقيمة التلقائية هي false.
escapingBooleanإذا لم يتم تجاوز false حرف محجوز في عنوان URL. والقيمة التلقائية هي 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.
var resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
var 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')
var request1 = {
  'url': 'https://httpbin.org/post',
  'method' : 'post',
  'payload' : formData
};
// A request may also just be a URL.
var request2 = 'https://httpbin.org/get?key=value';
UrlFetchApp.fetchAll([request1, request2]);

المَعلمات

الاسمالنوعالوصف
requestsObject[]مصفوفة من عناوين URL أو كائنات JavaScript تحدّد الطلبات على النحو المحدّد أدناه.

المعلمات المتقدمة

الاسمالنوعالوصف
urlStringعنوان URL للجلب. يمكن أن يتضمّن عنوان URL ما يصل إلى 2,082 حرفًا.
contentTypeStringنوع المحتوى (يتم ضبطه تلقائيًا على 'application/x-www-form-urlencoded'). من الأمثلة الأخرى على نوع المحتوى هو 'application/xml; charset=utf-8'.
headersObjectربط مفتاح/قيمة JavaScript لرؤوس HTTP للطلب
methodStringطريقة HTTP للطلب: get أو delete أو patch أو post أو put. والقيمة التلقائية هي get.
payloadStringالحمولة (أي نص طريقة POST) للطلب. لا تقبل بعض طرق HTTP (مثل GET) الحمولة. ويمكن أن تكون سلسلة أو مصفوفة بايت أو كائن ثنائي كبير أو كائن JavaScript. يتم تفسير كائن JavaScript على أنه خريطة لأسماء حقول القيم، حيث يمكن أن تكون القيم سلاسل أو كائن ثنائي كبير.
useIntranetBooleanتمّ الإيقاف. يؤدي هذا إلى توجيه الجلب لحل عنوان URL المحدد ضمن الشبكة الداخلية المرتبطة بنطاقك من خلال إيقاف (SDC) (متوقف)
validateHttpsCertificatesBooleanإذا تجاهل false استرجاع أي شهادات غير صالحة لطلبات HTTPS. والقيمة التلقائية هي true.
followRedirectsBooleanإذا لم يتّبع جلب البيانات false عمليات إعادة توجيه HTTP تلقائيًا، سيعرض استجابة HTTP الأصلية. والقيمة التلقائية هي true.
muteHttpExceptionsBooleanإذا كانت السياسة true، لا تجلب عملية الجلب استثناءً إذا كان رمز الاستجابة يشير إلى تعذُّر التشغيل، وبدلاً من ذلك يتم عرض HTTPResponse. والقيمة التلقائية هي false.
escapingBooleanفي حال استخدام false، لا يتم تخطي الأحرف المحجوزة في عنوان URL. والقيمة التلقائية هي 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.
var response = UrlFetchApp.getRequest("http://www.google.com/");
for(i in response) {
  Logger.log(i + ": " + response[i]);
}

المَعلمات

الاسمالنوعالوصف
urlStringعنوان URL المراد البحث عنه يمكن أن يتضمّن عنوان URL ما يصل إلى 2,082 حرفًا.

تذكرة ذهاب وعودة

Object — خريطة لاسم الحقل بالقيمة. تحتوي الخريطة على المفاتيح التالية على الأقل: url وmethod وcontentType وpayload وheaders.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة تفويضًا مع واحد أو أكثر من النطاقات التالية:

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

getRequest(url, params)

تعرض الطلب الذي تم تقديمه إذا تم استدعاء العملية.

وهذه الطريقة لا تُصدر الطلب في الواقع.

المَعلمات

الاسمالنوعالوصف
urlStringعنوان URL المراد البحث عنه يمكن أن يتضمّن عنوان URL ما يصل إلى 2,082 حرفًا.
paramsObjectعنصر JavaScript اختياري يحدد مَعلمات متقدمة كما هو موضّح أدناه.

المعلمات المتقدمة

الاسمالنوعالوصف
contentTypeStringنوع المحتوى (يتم ضبطه تلقائيًا على 'application/x-www-form-urlencoded'). من الأمثلة الأخرى على نوع المحتوى هو 'application/xml; charset=utf-8'.
headersObjectربط مفتاح/قيمة JavaScript لرؤوس HTTP للطلب
methodStringطريقة HTTP للطلب: get أو delete أو patch أو post أو put. والقيمة التلقائية هي get.
payloadStringالحمولة (أي نص طريقة POST) للطلب. لا تقبل بعض طرق HTTP (مثل GET) الحمولة. ويمكن أن تكون سلسلة أو مصفوفة بايت أو كائن ثنائي كبير أو كائن JavaScript. يتم تفسير كائن JavaScript على أنه خريطة لأسماء حقول القيم، حيث يمكن أن تكون القيم سلاسل أو كائن ثنائي كبير.
useIntranetBooleanتمّ الإيقاف. يؤدي هذا إلى توجيه الجلب لحل عنوان URL المحدد ضمن الشبكة الداخلية المرتبطة بنطاقك من خلال إيقاف (SDC) (متوقف)
validateHttpsCertificatesBooleanإذا تجاهل false استرجاع أي شهادات غير صالحة لطلبات HTTPS. والقيمة التلقائية هي true.
followRedirectsBooleanإذا لم يتّبع جلب البيانات false عمليات إعادة توجيه HTTP تلقائيًا، سيعرض استجابة HTTP الأصلية. والقيمة التلقائية هي true.
muteHttpExceptionsBooleanإذا لم يتم إجراء عملية الجلب في true، لن يتم إرسال استثناء إذا كان رمز الاستجابة يشير إلى تعذُّر التشغيل، وبدلاً من ذلك يتم عرض HTTPResponse. والقيمة التلقائية هي false.
escapingBooleanإذا لم يتم تجاهل false حرف محجوز في عنوان URL. والقيمة التلقائية هي true.

تذكرة ذهاب وعودة

Object — خريطة لاسم الحقل بالقيمة. تحتوي الخريطة على المفاتيح التالية على الأقل: url وmethod وcontentType وpayload وheaders.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة تفويضًا مع واحد أو أكثر من النطاقات التالية:

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