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