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

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

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

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

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

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

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

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

المتطلبات

قبل أن تتمكّن من استخدام خدمة متقدّمة، يجب استيفاء ال requirements التالية:

1. يجب تفعيل الخدمة المتقدّمة في مشروع النص البرمجي.

2. يجب التأكّد من تفعيل واجهة برمجة التطبيقات المقابلة للخدمة المتقدّمة في مشروع Cloud Platform (GCP) الذي يستخدمه النص البرمجي.

   إذا كان مشروع النصوص البرمجية يستخدم مشروعًا تلقائيًا على Google Cloud Platform تم إنشاؤه في 8 نيسان (أبريل) 2019 أو بعد هذا التاريخ، يتم تفعيل واجهة برمجة التطبيقات تلقائيًا بعد تفعيل الخدمة المتقدّمة وحفظ مشروع النصوص البرمجية. قد يُطلب منك أيضًا الموافقة على بنود خدمة Google Cloud وGoogle APIs في حال عدم الموافقة عليها من قبل.

   إذا كان مشروع النصوص البرمجية يستخدم مشروعًا عاديًا على Google Cloud Platform أو مشروعًا تلقائيًا قديمًا على Google Cloud Platform، عليك تفعيل واجهة برمجة التطبيقات المقابلة للخدمة المتقدّمة في مشروع Google Cloud Platform يدويًا. يجب أن يكون لديك إذن بتعديل مشروع GCP لإجراء هذا التغيير.

اطّلِع على مشاريع Cloud Platform لمزيد من المعلومات.

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

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

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

ملاحظة: إذا كنت تستخدم مشروعًا عاديًا على Google Cloud Platform (أو مشروعًا تلقائيًا قديمًا على Google Cloud Platform تم إنشاؤه قبل 8 نيسان (أبريل) 2019)، عليك أيضًا تفعيل واجهة برمجة التطبيقات المقابلة للخدمة المتقدّمة يدويًا. فعِّل واجهة برمجة التطبيقات باتّباع الخطوات التالية:

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

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

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

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

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

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

1. نص الطلب (عادةً ما يكون موردًا) بتنسيق عنصر JavaScript
2. المسار أو المَعلمات المطلوبة، كوسيطات فردية
3. مرفق تحميل الوسائط، كوسيطة Blob
4. المَعلمات الاختيارية، مثل كائن JavaScript الذي يربط أسماء المَعلمات بالقيمة
5. رؤوس طلبات HTTP، بصفتها كائن JavaScript يحدّد أسماء الرؤوس إلى قيم الرؤوس

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

هناك بعض الاستثناءات الخاصة التي يجب أخذها في الاعتبار:

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

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

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

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