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

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

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

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

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

يمكنك تفعيل خدمة متقدّمة باستخدام محرِّر Apps Script أو من خلال تعديل البيان.

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

1. افتح مشروع Apps Script.
2. على يمين الشاشة، انقر على أداة التعديل code.
3. على يمين الصفحة، انقر على إضافة خدمة add بجانب الخدمات.
4. اختَر إحدى خدمات 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 Cloud (تم إنشاؤه تلقائيًا بواسطة Apps Script)، يمكنك تخطّي هذه الخطوة. يتم تفعيل واجهة برمجة التطبيقات تلقائيًا عند إضافة الخدمة في الخطوة 1.

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

1. افتح مشروع Cloud المرتبط بالبرنامج النصي في ** وحدة تحكّم Google Cloud**.

2. في أعلى وحدة التحكّم، انقر على شريط البحث واكتب جزءًا من اسم واجهة برمجة التطبيقات (على سبيل المثال، "تقويم")، ثم انقر على الاسم عند ظهوره.

3. انقر على تفعيل واجهة برمجة التطبيقات.

4. أغلِق Google Cloud Console وارجع إلى محرّر النصوص البرمجية.

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

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

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

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

1. نص الطلب (عادةً ما يكون موردًا)، ككائن JavaScript
2. المسار أو المَعلمات المطلوبة، كوَسائط فردية إذا كانت الطريقة تتطلّب مَعلمات مسار متعدّدة، ستظهر بالترتيب الذي تم إدراجها به في عنوان URL لنقطة نهاية واجهة برمجة التطبيقات.
3. مرفق تحميل الوسائط، كمعلَمة Blob
4. المَعلمات الاختيارية (عادةً مَعلمات طلب البحث)، كعنصر JavaScript يربط أسماء المَعلمات بالقيم.
5. عناوين طلب 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 وما إلى ذلك

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

1. النص الأساسي: مورد الحدث (كائن JavaScript).
2. المسار: calendarId (سلسلة).
3. المَعلمات الاختيارية: مَعلمات طلب البحث (كائن 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.

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

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

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

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

توضّح نماذج الرموز الفرق في التعقيد بين إنشاء حدث في التقويم باستخدام الخدمة المتقدّمة واستخدام 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);

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

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

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

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