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());

المَعلمات

الاسمTypeالوصف
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);

المَعلمات

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

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

الاسمTypeالوصف
contentTypeStringنوع المحتوى (القيمة التلقائية هي "application/x-www-form-urlcipher" ). إليك مثال آخر على نوع المحتوى هو "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]);

المَعلمات

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

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

الاسمTypeالوصف
urlStringعنوان URL المطلوب جلبه. ويمكن أن يحتوي عنوان URL على ما يصل إلى 2,082 حرفًا.
contentTypeStringنوع المحتوى (القيمة التلقائية هي "application/x-www-form-urlcipher" ). إليك مثال آخر على نوع المحتوى هو "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]);
}

المَعلمات

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

استرجاع الكرة

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

التفويض

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

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

getRequest(url, params)

تعرض الطلب الذي يتم إجراؤه في حال استدعاء العملية.

ولا تؤدي هذه الطريقة إلى إصدار الطلب.

المَعلمات

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

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

الاسمTypeالوصف
contentTypeStringنوع المحتوى (القيمة التلقائية هي "application/x-www-form-urlcipher" ). إليك مثال آخر على نوع المحتوى هو "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