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

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

لمعرفة واجهات Google APIs المتاحة كخدمات متقدّمة، ابحث عن القسم خدمات 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". توفر عادةً وظيفة الإكمال التلقائي في محرر النصوص البرمجية معلومات كافية للبدء، ولكن القواعد أدناه توضح كيفية إنشاء "برمجة تطبيقات Google" لتوقيع طريقة من واجهة Google API عامة.

يمكن أن تقبل الطلبات إلى واجهات 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. وبناءً على ذلك، عادةً ما تكون أي مشكلة تحدث أثناء استخدامها مشكلة في واجهة برمجة التطبيقات الأساسية، وليس في "برمجة التطبيقات" نفسها.

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