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