خدمات Google المتقدمة

أتاحت الخدمات المتقدمة في "برمجة تطبيقات Google" للمطوّرين ذوي الخبرة إمكانية الاتصال ببعض واجهات Google APIs العامة من خلال إعداد أقل مقارنةً باستخدام واجهات HTTP. الخدمات المتقدمة هي في الأساس برامج تضمين رفيعة حول Google APIs هذه. وهي تعمل مثل الخدمات المضمَّنة في لغة "برمجة تطبيقات Google"، على سبيل المثال، توفِّر ميزة الإكمال التلقائي، وتتعامل لغة "برمجة تطبيقات Google" مع مسار التفويض تلقائيًا. ومع ذلك، يجب تفعيل خدمة متقدمة قبل أن تتمكّن من استخدامها في نص برمجي.

لمعرفة واجهات Google API المتوفرة كخدمات متقدمة، ابحث عن القسم خدمات Google المتقدمة في المرجع. إذا أردت استخدام واجهة برمجة تطبيقات من Google غير متوفّرة كخدمة متقدمة، ما عليك سوى الربط بها مثل أي واجهة برمجة تطبيقات خارجية أخرى.

هل يتم استخدام خدمات متقدمة أم بروتوكول HTTP؟

ترتبط كل خدمة من خدمات Google المتقدمة بواجهة برمجة تطبيقات عامة من Google. في "برمجة التطبيقات"، يمكنك الوصول إلى واجهات برمجة التطبيقات هذه من خلال خدمات متقدّمة أو ببساطة من خلال تقديم طلبات البيانات من واجهة برمجة التطبيقات مباشرةً باستخدام UrlFetch.

إذا كنت تستخدم طريقة الخدمة المتقدمة، ستتعامل "برمجة التطبيقات" مع مسار التفويض وتقدِّم دعم الإكمال التلقائي. ومع ذلك، يجب تفعيل الخدمة المتقدمة قبل أن تتمكّن من استخدامها. بالإضافة إلى ذلك، لا توفر بعض الخدمات المتقدمة سوى مجموعة فرعية من الوظائف المتاحة في واجهة برمجة التطبيقات.

إذا كنت تستخدم طريقة UrlFetch للوصول إلى واجهة برمجة التطبيقات مباشرةً، يعني ذلك في الأساس أنّك تتعامل مع Google API على أنها واجهة برمجة تطبيقات خارجية. بهذه الطريقة، يمكن استخدام جميع جوانب واجهة برمجة التطبيقات. ومع ذلك، فإنه يتطلب منك التعامل مع تفويض واجهة برمجة التطبيقات بنفسك. يجب أيضًا إنشاء أي عناوين مطلوبة وتحليل استجابات واجهة برمجة التطبيقات.

بشكل عام، من الأسهل استخدام خدمة متقدّمة كلما أمكن ذلك واستخدام طريقة UrlFetch فقط عندما لا توفّر الخدمة المتقدمة الوظائف التي تريدها.

المتطلّبات

قبل أن تتمكن من استخدام خدمة متقدمة، يجب أن تستوفي المتطلبات التالية:

  1. يجب تفعيل الخدمة المتقدمة في مشروع النصوص البرمجية.

  2. يجب التأكّد من أنّ واجهة برمجة التطبيقات المقابلة للخدمة المتقدّمة مفعّلة في مشروع 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، يُرجى اتّباع التعليمات التالية:

  1. افتح مشروع "برمجة تطبيقات Google".
  2. على يمين الصفحة، انقر على أداة التعديل .
  3. على يمين الصفحة، بجانب الخدمات، انقر على إضافة خدمة .
  4. اختَر خدمة متقدّمة من Google وانقر على إضافة.

بعد تفعيل خدمة متقدمة، تصبح متاحة في وضع الإكمال التلقائي.

كيفية تحديد توقيعات الطريقة

تستخدم الخدمات المتقدمة بشكل عام الكائنات وأسماء الطرق والمعلمات نفسها مثل واجهات برمجة التطبيقات العامة المقابلة، على الرغم من ترجمة توقيعات الطرق للاستخدام في برمجة التطبيقات. توفّر عادةً وظيفة الإكمال التلقائي في محرِّر النص البرمجي معلومات كافية للبدء، ولكن توضّح القواعد أدناه كيفية إنشاء "برمجة تطبيقات Google" لتوقيع طريقة من واجهة برمجة تطبيقات عامة من Google API.

يمكن أن تقبل الطلبات إلى Google APIs مجموعة متنوّعة من أنواع البيانات المختلفة، بما في ذلك مَعلمات المسار و/أو مَعلمات طلب البحث و/أو نص الطلب و/أو مرفق تحميل الوسائط. يمكن لبعض الخدمات المتقدمة أيضًا قبول رؤوس طلبات HTTP محددة (على سبيل المثال، خدمة التقويم المتقدمة).

يحتوي توقيع الطريقة المقابل في "برمجة تطبيقات Google" على الوسيطات التالية:

  1. نص الطلب (عادةً ما يكون موردًا)، ككائن JavaScript.
  2. المسار أو المَعلمات المطلوبة، كوسيطات فردية.
  3. مرفق تحميل الوسائط، كوسيطة Blob.
  4. معلمات اختيارية، ككائن JavaScript تعيين أسماء المعلمات إلى قيم.
  5. عناوين طلبات HTTP، ككائن JavaScript تعيين أسماء العناوين لقيم العناوين.

إذا لم تحتوي الطريقة على أي عناصر في فئة معينة، فسيتم حذف هذا الجزء من التوقيع.

هناك بعض الاستثناءات الخاصة التي يجب أن تكون على دراية بها:

  • بالنسبة إلى الطرق التي تقبل تحميل الوسائط، يتم ضبط المَعلمة uploadType تلقائيًا.
  • إنّ الطرق التي تحمل اسم delete في Google API تتم تسميتها remove في "برمجة تطبيقات Google"، بما أنّ delete هي كلمة محجوزة في JavaScript.
  • إذا تم إعداد خدمة متقدمة لقبول عناوين طلبات HTTP، وضبطت كائن JavaScript لعناوين الطلب، عليك أيضًا ضبط كائن JavaScript للمعلَمات الاختيارية (على كائن فارغ إذا كنت لا تستخدم معلَمات اختيارية).

الدعم للخدمات المتقدّمة

الخدمات المتقدمة هي برامج تضمين رفيعة تتيح استخدام واجهات برمجة تطبيقات Google ضمن "برمجة التطبيقات". وبالتالي، فإنّ أي مشكلة تحدث أثناء استخدامها هي عادةً مشكلة في واجهة برمجة التطبيقات الأساسية وليس في "برمجة التطبيقات" نفسها.

إذا واجهت مشكلة أثناء استخدام خدمة متقدّمة، يجب الإبلاغ عنها باستخدام تعليمات الدعم الخاصة بواجهة برمجة التطبيقات الأساسية. يتم تقديم الروابط إلى تعليمات الدعم هذه في كل دليل خدمة متقدم في قسم مراجع برمجة التطبيقات.