خدمات Google المتقدمة

تتيح لك الخدمات المتقدّمة في "برمجة تطبيقات Google" الربط ببعض واجهات Google API العامة من خلال إعدادات أقلّ من استخدام واجهات HTTP. الخدمات المتقدّمة هي برامج تضمين بسيطة لواجهات برمجة التطبيقات من Google. وتعمل هذه الخدمات بشكل مشابه للخدمات المضمّنة في برمجة تطبيقات، فهي مثلاً توفّر ميزة الإكمال التلقائي، وتتولّى برمجة تطبيقات عملية منح الأذونات تلقائيًا. فعِّل خدمة متقدّمة قبل استخدامها في نص برمجي.

تفعيل الخدمات المتقدّمة

لاستخدام إحدى خدمات Google المتقدّمة، اتّبِع التعليمات التالية:

الخطوة 1: تفعيل الخدمة المتقدّمة

فعِّل خدمة متقدّمة باستخدام أداة تعديل النصوص البرمجية في "برمجة التطبيقات" أو من خلال تعديل ملف البيان.

الطريقة (أ): استخدام المحرِّر

افتح مشروع برمجة تطبيقات.
على يمين الشاشة، انقر على أداة التعديل .
على يمين الصفحة، انقر على إضافة خدمة بجانب الخدمات.
اختَر إحدى خدمات Google المتقدّمة وانقر على إضافة.

الطريقة (ب): استخدام ملف البيان

فعِّل الخدمات المتقدّمة من خلال تعديل ملف البيان. على سبيل المثال، لتفعيل خدمة Google Drive المتقدّمة، أضِف الحقل enabledAdvancedServices إلى العنصر dependencies:

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

بعد تفعيل خدمة متقدّمة، ستصبح متاحة في ميزة "الإكمال التلقائي".

الخطوة 2: تفعيل Google Cloud API (مشاريع Google Cloud العادية فقط)

إذا كنت تستخدم مشروعًا تلقائيًا على السحابة الإلكترونية في Google (تم إنشاؤه تلقائيًا بواسطة برمجة تطبيقات)، يمكنك تخطّي هذه الخطوة. يتم تفعيل واجهة برمجة التطبيقات تلقائيًا عند إضافة الخدمة في الخطوة 1.

في حال استخدام مشروع عادي على Google Cloud، فعِّل يدويًا واجهة برمجة التطبيقات المتوافقة مع الخدمة المتقدّمة. لتفعيل واجهة برمجة التطبيقات يدويًا، اتّبِع الخطوات التالية:

افتح مشروع على السحابة الإلكترونية المرتبط بالبرنامج النصي في ** وحدة تحكّم Google Cloud**.
في أعلى وحدة التحكّم، انقر على شريط البحث واكتب جزءًا من اسم واجهة برمجة التطبيقات (على سبيل المثال، "تقويم")، ثم انقر على الاسم عند ظهوره.
انقر على تفعيل واجهة برمجة التطبيقات.
أغلِق Google Cloud Console وارجع إلى أداة تعديل النصوص البرمجية.

كيفية تحديد تواقيع الطرق

تستخدم الخدمات المتقدّمة بشكل عام العناصر وأسماء الطرق والمعلَمات نفسها التي تستخدمها واجهات برمجة التطبيقات العامة المقابلة، على الرغم من أنّه يتم ترجمة تواقيع الطرق لاستخدامها في Apps Script. توفّر وظيفة الإكمال التلقائي في أداة تعديل النصوص البرمجية عادةً معلومات كافية للبدء. توضّح القواعد التالية كيف ينشئ Apps Script توقيع طريقة من واجهة برمجة تطبيقات Google علنية.

يمكن أن تقبل الطلبات الموجّهة إلى واجهات Google API أنواعًا مختلفة من البيانات، بما في ذلك مَعلمات المسار أو مَعلمات طلب البحث أو نص الطلب أو مرفق تحميل الوسائط. يمكن أن تقبل بعض الخدمات المتقدّمة أيضًا عناوين طلبات HTTP معيّنة (على سبيل المثال، خدمة "تقويم Google" المتقدّمة).

يحتوي توقيع الطريقة المقابلة في "برمجة تطبيقات Google" على الوسيطات التالية:

نص الطلب (عادةً ما يكون موردًا)، ككائن JavaScript
المسار أو المَعلمات المطلوبة، كوسيطات فردية إذا كانت الطريقة تتطلّب مَعلمات مسار متعدّدة، ستظهر بالترتيب الذي تم إدراجها به في عنوان URL لنقطة نهاية واجهة برمجة التطبيقات.
مرفق تحميل الوسائط، كمعلَمة Blob
المَعلمات الاختيارية (عادةً مَعلمات طلب البحث)، كعنصر JavaScript يتم فيه ربط أسماء المَعلمات بالقيم.
عناوين طلب HTTP، ككائن JavaScript يربط أسماء العناوين بقيمها.

إذا لم تتضمّن الطريقة أي عناصر في فئة معيّنة، يتم حذف هذا الجزء من التوقيع.

يُرجى الانتباه إلى الاستثناءات التالية:

بالنسبة إلى الطرق التي تقبل تحميل الوسائط، يتم ضبط المَعلمة uploadType تلقائيًا.
إنّ الطرق التي تحمل الاسم delete في Google API تحمل الاسم remove في "برمجة تطبيقات Google"، لأنّ delete هي كلمة محجوزة في JavaScript.
إذا تم ضبط إحدى الخدمات المتقدّمة لقبول عناوين طلبات HTTP، وقمت بضبط عنصر JavaScript لعناوين الطلبات، عليك أيضًا ضبط عنصر JavaScript للمعلمات الاختيارية (على عنصر فارغ إذا كنت لا تستخدم معلمات اختيارية).

مثال: Calendar.Events.insert

لإنشاء حدث في التقويم، اتّبِع الخطوات التالية:

تعرض مستندات Google Calendar API بنية طلب HTTP المقابل:

فعل HTTP: POST
عنوان URL للطلب: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
نص الطلب: مورد Event
مَعلمات طلب البحث: sendUpdates وsupportsAttachments وما إلى ذلك

في برمجة تطبيقات، يتم تحديد توقيع الطريقة من خلال إعادة ترتيب هذه المدخلات:

النص الأساسي: مورد الحدث (كائن JavaScript).
المسار: calendarId (سلسلة).
المَعلمات الاختيارية: مَعلمات طلب البحث (عنصر JavaScript).

يبدو طلب الإجراء الناتج على النحو التالي:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

الخدمات المتقدّمة أو HTTP؟

ترتبط كل خدمة متقدّمة من Google بواجهة برمجة تطبيقات عامة من Google. في Apps Script، يمكنك الوصول إلى واجهات برمجة التطبيقات هذه باستخدام الخدمات المتقدّمة أو عن طريق تقديم طلبات واجهة برمجة التطبيقات مباشرةً باستخدام UrlFetch.

في حال استخدام طريقة الخدمة المتقدّمة، تتولّى "برمجة التطبيقات" معالجة مسار منح الإذن وتوفّر ميزة الإكمال التلقائي. فعِّل الخدمة المتقدّمة قبل استخدامها.

في حال استخدام طريقة UrlFetch للوصول إلى واجهة برمجة التطبيقات مباشرةً، ستتعامل مع واجهة Google API على أنّها واجهة برمجة تطبيقات خارجية. باستخدام هذه الطريقة، يمكنك الاستفادة من جميع جوانب واجهة برمجة التطبيقات. ومع ذلك، عليك التعامل مع عملية تفويض واجهة برمجة التطبيقات.

يقارن الجدول التالي بين الطريقتَين:

الميزة	الخدمة المتقدّمة	‫UrlFetch (HTTP)
التفويض	يتم التعامل معه تلقائيًا	يجب معالجة الطلب يدويًا
الإكمال التلقائي	متاح	غير متوفر
نطاق الوظائف	قد تكون مجموعة فرعية من واجهة برمجة التطبيقات	الوصول الكامل إلى جميع ميزات واجهة برمجة التطبيقات
التعقيد	أسهل	أكثر تعقيدًا (يتطلّب إنشاء العناوين وتحليل الردود)

مقارنة الرموز

توضّح نماذج الرموز الفرق في التعقيد بين إنشاء حدث في "تقويم Google" باستخدام الخدمة المتقدّمة مقارنةً باستخدام UrlFetchApp.

الخدمة المتقدّمة:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

بالنسبة إلى الطريقة UrlFetchApp، حدِّد يدويًا نطاقات OAuth المطلوبة في ملف البيان للبرنامج النصي.

استخدِم خدمة متقدّمة كلما أمكن ذلك، ولا تستخدِم طريقة UrlFetch إلا عندما لا تتوفّر الخدمة المتقدّمة أو لا تقدّم الوظيفة التي تحتاج إليها.

التوافق مع الخدمات المتقدّمة

بما أنّ الخدمات المتقدّمة هي أغلفة بسيطة حول واجهات Google APIs، فإنّ أي مشكلة تواجهها أثناء استخدامها تكون عادةً مشكلة في واجهة برمجة التطبيقات الأساسية، وليس في Apps Script.

إذا واجهت مشكلة أثناء استخدام إحدى الخدمات المتقدّمة، يُرجى الإبلاغ عنها باتّباع تعليمات الدعم الخاصة بواجهة برمجة التطبيقات الأساسية.

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