Class UrlFetchApp

UrlFetchApp

استرداد الموارد والتواصل مع المضيفين الآخرين عبر الإنترنت

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

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

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

انظر أيضًا

• HTTPResponse
• ضبط النطاقات الصريحة

الطُرق

الطريقة	نوع القيمة التي تم إرجاعها	وصف قصير
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.
const response = UrlFetchApp.fetch('http://www.google.com/');
Logger.log(response.getContentText());

المعلمات

الاسم	النوع	الوصف
url	String	تمثّل هذه السمة عنوان 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.
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: '[e-mail]',
  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 المطلوب استرجاعه. يمكن أن يتضمّن عنوان URL ما يصل إلى 2,082 حرفًا.
params	Object	كائن JavaScript اختياري يحدّد المَعلمات المتقدّمة على النحو الموضّح أدناه.

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

الاسم	النوع	الوصف
contentType	String	نوع المحتوى (القيمة التلقائية هي ‎'application/x-www-form-urlencoded'‎). مثال آخر على نوع المحتوى هو 'application/xml; charset=utf-8'.
headers	Object	خريطة مفتاح/قيمة JavaScript لعناوين HTTP للطلب
method	String	طريقة HTTP للطلب: get أو delete أو patch أو post أو put القيمة التلقائية هي get.
payload	String	الحمولة (أي نص POST) للطلب لا تقبل بعض طرق HTTP (مثل GET) حمولة. يمكن أن تكون سلسلة أو مصفوفة بايت أو كائن ثنائي كبير أو عنصر JavaScript. يتم تفسير كائن JavaScript على أنّه خريطة لأسماء حقول النموذج إلى القيم، حيث يمكن أن تكون القيم عبارة عن سلاسل أو كائنات ثنائية كبيرة.
useIntranet	Boolean	تمّ الإيقاف. يؤدي ذلك إلى توجيه عملية الجلب لحلّ عنوان URL المحدّد ضمن شبكة الإنترانت المرتبطة بنطاقك من خلال SDC (التي تم إيقافها نهائيًا).
validateHttpsCertificates	Boolean	إذا false تجاهل عملية الجلب أي شهادات غير صالحة لطلبات HTTPS. القيمة التلقائية هي true.
followRedirects	Boolean	إذا لم يتم تلقائيًا تتبُّع عمليات إعادة التوجيه عبر HTTP عند استخدام false، سيتم عرض استجابة HTTP الأصلية. القيمة التلقائية هي true.
muteHttpExceptions	Boolean	إذا لم يؤدِ جلب البيانات إلى طرح استثناء عند ظهور رمز استجابة يشير إلى حدوث خطأ، بل يعرض HTTPResponse بدلاً من ذلك.true القيمة التلقائية هي false.
escaping	Boolean	إذا لم يتم تخطّي 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.
const resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
const formData = {
  name: 'Bob Smith',
  email: '[e-mail]',
  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 أو كائنات JavaScript تحدّد الطلبات كما هو موضّح أدناه.

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

الاسم	النوع	الوصف
url	String	عنوان URL المطلوب استرجاعه يمكن أن يتضمّن عنوان URL ما يصل إلى 2,082 حرفًا.
contentType	String	نوع المحتوى (القيمة التلقائية هي ‎'application/x-www-form-urlencoded'‎). مثال آخر على نوع المحتوى هو 'application/xml; charset=utf-8'.
headers	Object	خريطة مفتاح/قيمة JavaScript لعناوين HTTP للطلب
method	String	طريقة HTTP للطلب: get أو delete أو patch أو post أو put القيمة التلقائية هي get.
payload	String	الحمولة (أي نص POST) للطلب لا تقبل بعض طرق HTTP (مثل GET) حمولة. يمكن أن تكون سلسلة أو مصفوفة بايت أو كائن ثنائي كبير أو عنصر JavaScript. يتم تفسير كائن JavaScript على أنّه خريطة لأسماء حقول النموذج إلى القيم، حيث يمكن أن تكون القيم عبارة عن سلاسل أو كائنات ثنائية كبيرة.
useIntranet	Boolean	تمّ الإيقاف. يؤدي ذلك إلى توجيه عملية الجلب لحلّ عنوان URL المحدّد ضمن شبكة الإنترانت المرتبطة بنطاقك من خلال SDC (التي تم إيقافها نهائيًا).
validateHttpsCertificates	Boolean	إذا false تجاهل عملية الجلب أي شهادات غير صالحة لطلبات HTTPS. القيمة التلقائية هي true.
followRedirects	Boolean	إذا لم يتم تلقائيًا تتبُّع عمليات إعادة التوجيه عبر HTTP عند استخدام false، سيتم عرض استجابة HTTP الأصلية. القيمة التلقائية هي true.
muteHttpExceptions	Boolean	إذا كانت القيمة true، لن يؤدي جلب البيانات إلى طرح استثناء إذا كان رمز الاستجابة يشير إلى حدوث خطأ، بل سيتم عرض القيمة HTTPResponse بدلاً من ذلك. القيمة التلقائية هي false.
escaping	Boolean	إذا كانت القيمة 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.
const response = UrlFetchApp.getRequest('http://www.google.com/');
for (const i in response) {
  Logger.log(`${i}: ${response[i]}`);
}

المعلمات

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

الإرجاع

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

التفويض

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

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

---

getRequest(url, params)

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

لا تنفّذ هذه الطريقة الطلب فعليًا.

المعلمات

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

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

الاسم	النوع	الوصف
contentType	String	نوع المحتوى (القيمة التلقائية هي ‎'application/x-www-form-urlencoded'‎). مثال آخر على نوع المحتوى هو 'application/xml; charset=utf-8'.
headers	Object	خريطة مفتاح/قيمة JavaScript لعناوين HTTP للطلب
method	String	طريقة HTTP للطلب: get أو delete أو patch أو post أو put القيمة التلقائية هي get.
payload	String	الحمولة (أي نص POST) للطلب لا تقبل بعض طرق HTTP (مثل GET) حمولة. يمكن أن تكون سلسلة أو مصفوفة بايت أو كائن ثنائي كبير أو عنصر JavaScript. يتم تفسير كائن JavaScript على أنّه خريطة لأسماء حقول النموذج إلى القيم، حيث يمكن أن تكون القيم عبارة عن سلاسل أو كائنات ثنائية كبيرة.
useIntranet	Boolean	تمّ الإيقاف. يؤدي ذلك إلى توجيه عملية الجلب لحلّ عنوان URL المحدّد ضمن شبكة الإنترانت المرتبطة بنطاقك من خلال SDC (التي تم إيقافها نهائيًا).
validateHttpsCertificates	Boolean	إذا false تجاهل عملية الجلب أي شهادات غير صالحة لطلبات HTTPS. القيمة التلقائية هي true.
followRedirects	Boolean	إذا لم يتم تلقائيًا تتبُّع عمليات إعادة التوجيه عبر HTTP عند استخدام false، سيتم عرض استجابة HTTP الأصلية. القيمة التلقائية هي true.
muteHttpExceptions	Boolean	إذا لم يؤدِ جلب البيانات إلى طرح استثناء عند ظهور رمز استجابة يشير إلى حدوث خطأ، بل يعرض HTTPResponse بدلاً من ذلك.true القيمة التلقائية هي false.
escaping	Boolean	في حال عدم تخطّي false أحرف محجوزة في عنوان URL القيمة التلقائية هي true.

الإرجاع

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

التفويض

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

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