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