تتيح الخدمات المتقدّمة في "برمجة التطبيقات" للمطوّرين المتمرّسين إمكانية الربط ببعض واجهات Google API العامة من خلال إعدادات أقلّ من استخدام واجهات HTTP. الخدمات المتقدّمة هي في الأساس أغلفة بسيطة حول واجهات Google APIs. وتعمل هذه الإضافات بشكل مشابه للخدمات المضمّنة في "برمجة تطبيقات Google"، فهي توفّر مثلاً ميزة الإكمال التلقائي، وتتولّى "برمجة تطبيقات Google" عملية منح الأذونات تلقائيًا. ومع ذلك، يجب تفعيل خدمة متقدّمة قبل أن تتمكّن من استخدامها في نص برمجي.
للاطّلاع على واجهات Google API المتاحة كخدمات متقدّمة، ابحث عن قسم خدمات Google المتقدّمة في المراجع. إذا كنت تريد استخدام إحدى واجهات Google API غير المتاحة كخدمة متقدّمة، ما عليك سوى الربط بها كما تفعل مع أي واجهة برمجة تطبيقات خارجية أخرى.
الخدمات المتقدّمة أو HTTP؟
ترتبط كل خدمة من خدمات Google المتقدّمة بواجهة برمجة تطبيقات عامة من Google. في "برمجة التطبيقات"، يمكنك الوصول إلى واجهات برمجة التطبيقات هذه من خلال الخدمات المتقدّمة أو ببساطة عن طريق تقديم طلبات واجهة برمجة التطبيقات مباشرةً باستخدام UrlFetch.
في حال استخدام طريقة الخدمة المتقدّمة، تتولّى "برمجة التطبيقات" عملية التفويض وتوفّر ميزة الإكمال التلقائي. ومع ذلك، يجب تفعيل الخدمة المتقدّمة قبل أن تتمكّن من استخدامها. بالإضافة إلى ذلك، لا توفّر بعض الخدمات المتقدّمة سوى مجموعة فرعية من الوظائف المتاحة في واجهة برمجة التطبيقات.
في حال استخدام طريقة UrlFetch للوصول إلى واجهة برمجة التطبيقات مباشرةً، ستتعامل مع واجهة Google API على أنّها واجهة برمجة تطبيقات خارجية. باستخدام هذه الطريقة، يمكن الاستفادة من جميع جوانب واجهة برمجة التطبيقات. ومع ذلك، يتطلّب ذلك أن تتولّى بنفسك عملية تفويض الوصول إلى واجهة برمجة التطبيقات. يجب أيضًا إنشاء أي عناوين مطلوبة وتحليل الردود من واجهة برمجة التطبيقات.
بشكل عام، من الأسهل استخدام خدمة متقدّمة حيثما أمكن ذلك، ولا تستخدم طريقة UrlFetch إلا عندما لا توفّر الخدمة المتقدّمة الوظيفة التي تحتاج إليها.
المتطلّبات
قبل استخدام خدمة متقدّمة، يجب استيفاء المتطلبات التالية:
- يجب تفعيل الخدمة المتقدّمة في مشروع النص البرمجي.
يجب التأكّد من تفعيل واجهة برمجة التطبيقات المتوافقة مع الخدمة المتقدّمة في مشروع 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 المتقدّمة، اتّبِع التعليمات التالية:
- افتح مشروع Apps Script.
- على يمين الشاشة، انقر على أداة التعديل .
- على يمين الصفحة، انقر على إضافة خدمة بجانب الخدمات.
- اختَر إحدى خدمات Google المتقدّمة وانقر على إضافة.
بعد تفعيل خدمة متقدّمة، ستتوفّر في ميزة الإكمال التلقائي.
كيفية تحديد تواقيع الطرق
تستخدم الخدمات المتقدّمة بشكل عام الكائنات وأسماء الطرق والمعلَمات نفسها التي تستخدمها واجهات برمجة التطبيقات العامة المقابلة، على الرغم من أنّه يتم ترجمة تواقيع الطرق لاستخدامها في Apps Script. تقدّم وظيفة الإكمال التلقائي في محرّر النصوص البرمجية عادةً معلومات كافية للبدء، ولكن توضّح القواعد أدناه كيف تنشئ "برمجة تطبيقات Google" توقيع طريقة من واجهة برمجة تطبيقات عامة من Google.
يمكن أن تقبل الطلبات المقدَّمة إلى واجهات Google API أنواعًا مختلفة من البيانات، بما في ذلك مَعلمات المسار ومَعلمات طلب البحث ونص الطلب و/أو مرفق تحميل الوسائط. يمكن لبعض الخدمات المتقدّمة أيضًا قبول عناوين طلبات HTTP معيّنة (على سبيل المثال، خدمة "تقويم Google" المتقدّمة).
يحتوي توقيع الطريقة المقابل في Google Apps Script على الوسيطات التالية:
- نص الطلب (عادةً ما يكون موردًا)، ككائن JavaScript
- المسار أو المَعلمات المطلوبة، كوسيطات فردية
- مرفق تحميل الوسائط، كمعلَمة
Blob - مَعلمات اختيارية، على شكل كائن JavaScript يربط أسماء المَعلمات بالقيم
- عناوين طلب HTTP، ككائن JavaScript يربط أسماء العناوين بقيمها
إذا لم تتضمّن الطريقة أي عناصر في فئة معيّنة، يتم حذف هذا الجزء من التوقيع.
هناك بعض الاستثناءات الخاصة التي يجب الانتباه إليها:
- بالنسبة إلى الطرق التي تقبل تحميل الوسائط، يتم ضبط المَعلمة
uploadTypeتلقائيًا. - إنّ الطرق التي تحمل الاسم
deleteفي Google API تحمل الاسمremoveفي "برمجة تطبيقات Google"، لأنّdeleteهي كلمة محجوزة في JavaScript. - إذا تم ضبط إحدى الخدمات المتقدّمة لقبول عناوين طلبات HTTP، وقمت بضبط عنصر JavaScript لعناوين الطلبات، عليك أيضًا ضبط عنصر JavaScript للمعلمات الاختيارية (على عنصر فارغ إذا كنت لا تستخدم معلمات اختيارية).
التوافق مع الخدمات المتقدّمة
الخدمات المتقدّمة هي مجرد أغلفة بسيطة تتيح استخدام واجهات برمجة التطبيقات من Google ضمن "برمجة تطبيقات Google". وبالتالي، فإنّ أي مشكلة تواجهها أثناء استخدامها تكون عادةً مشكلة في واجهة برمجة التطبيقات الأساسية، وليس في Apps Script نفسها.
إذا واجهت مشكلة أثناء استخدام إحدى الخدمات المتقدّمة، يجب الإبلاغ عنها باتّباع تعليمات الدعم الخاصة بواجهة برمجة التطبيقات الأساسية. تتوفّر روابط تؤدي إلى تعليمات الدعم هذه في كل دليل من أدلة الخدمات المتقدّمة في قسم المراجع في Apps Script.