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