إنشاء مكتبة برامج للعملاء

يمكنك استخدام خدمة Google APIs Discovery Service لإنشاء مجموعة متنوعة من الأدوات المختلفة لاستخدامها مع Google APIs. ومع ذلك، فإنّ الغرض الأساسي من مستند Discovery هو السماح لشركة Google بإنشاء مكتبات برامج للعملاء بلغات برمجة مختلفة. يوضّح هذا المستند كيفية إنشاء مكتبة برامج مخصّصة لعميل Google APIs.

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

1. استرجاع مستند Discovery وإنشاء مساحة واجهة برمجة التطبيقات
2. إنشاء طلب
3. إجراء مكالمة واسترداد الردّ

يتم وصف هذه الخطوات بمزيد من التفصيل في الأقسام التالية. يمكنك أيضًا الاطّلاع على نموذج برنامج Simple APIs client في قسم "الأمثلة" لمعرفة كيفية ربط هذه التعليمات بالرمز.

استرجاع مستند Discovery

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

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

إنشاء طلب

يتضمّن إنشاء الطلبات خطوتَين منفصلتَين:

1. إنشاء نص الطلب
2. إنشاء عنوان URL للطلب

عليك تحويل نص الطلب، إن وُجد، من تمثيل مناسب للغة إلى تنسيق النقل الصحيح. على سبيل المثال، في مكتبة عميل Java، قد يكون هناك فئة لكل نوع طلب تتيح معالجة بيانات الطلب الآمنة من حيث النوع ويمكن تسلسلها إلى JSON.

إنشاء عنوان URL للطلب هو عملية أكثر تعقيدًا بعض الشيء.

تستخدِم السمة path لكل طريقة في واجهة برمجة التطبيقات بنية نموذج معرّف الموارد المنتظم (URI) الإصدار 04. قد تحتوي هذه السمة على متغيرات محاطة بأقواس معقوفة. في ما يلي مثال على السمة path مع متغيرات:

/example/path/var

في المسار أعلاه، var هو متغيّر. تأتي قيمة هذا المتغيّر من القسم parameters في مستند Discovery الخاص بهذه الطريقة. يحتوي كل اسم متغيّر على قيمة مقابلة في الكائن parameters. في المثال أعلاه، هناك معلَمة باسم var في القسم parameters (وقيمتها location هي path، للإشارة إلى أنّها متغيّر مسار).

عند تقديم طلب، عليك استبدال القيمة var في عنوان URL. على سبيل المثال، إذا اختار مستخدم المكتبة خيارًا يضبط var على القيمة foo، سيكون عنوان URL الجديد هو /example/path/foo.

يُرجى أيضًا العِلم أنّ السمة path هي معرّف موارد منتظم (URI) نسبي. لاحتساب معرّف الموارد الموحّد المطلق، اتّبِع الخطوات التالية:

1. إذا كنت تعرف موقعك الجغرافي (المنطقة)، وكان مستند Discovery يتضمّن السمة endpoints، تحقّق مما إذا كان موقعك الجغرافي مدرجًا في قائمة endpoints. إذا كان الأمر كذلك، احصل على endpointUrl من قائمة endpoints التي تتطابق فيها قيمة location مع القيمة التي أدخلتها.

2. إذا لم يكن هناك موقع إلكتروني endpoints في مستند Discovery أو لم يكن موقعك الجغرافي مضمّنًا في قائمة endpoints أو أردت استهداف نقطة النهاية العامة، يمكنك الحصول على الموقع الإلكتروني rootUrl من المستوى الأعلى لمستند Discovery.

   على سبيل المثال، تكون قيمة السمة rootUrl في مستند الاكتشاف الخاص بواجهة برمجة التطبيقات Service Usage API كما يلي:

   https://serviceusage.googleapis.com/

3. احصل على servicePath من المستوى الأعلى لمستند Discovery. على سبيل المثال، تكون السمة servicePath في مستند Discovery الخاص بواجهة برمجة التطبيقات Service Usage API فارغة.

4. يمكنك ربطها معًا للحصول على:

   https://serviceusage.googleapis.com/

5. احصل على السمة path، ووسِّعها كنموذج URI، وادمج النتائج الناتجة عن هذا التوسيع مع URI من الخطوة السابقة. على سبيل المثال، في الطريقة serviceusage.services.enable لواجهة برمجة التطبيقات v1 Service Usage API، تكون قيمة السمة path هي v1/{+name}:enable. وبالتالي، يكون معرّف الموارد المنتظم (URI) الكامل للطريقة كما يلي:

   https://serviceusage.googleapis.com/v1/{+name}:enable

لا تحتاج إلى مفتاح واجهة برمجة تطبيقات لطلب بيانات من Service Usage API. ومع ذلك، إذا كانت واجهة برمجة التطبيقات التي تستدعيها تتطلّب مفتاح واجهة برمجة تطبيقات، يمكنك إضافة مفتاح واجهة برمجة التطبيقات إلى سلسلة طلب البحث في معرّف الموارد المنتظم (URI) على النحو التالي:

REQUEST_URI?key=API_KEY

إجراء مكالمة والتعامل مع الرد

بعد إرسال الطلب، عليك إلغاء تسلسل الردّ إلى التمثيل المناسب للغة، مع الحرص على معالجة حالات الخطأ التي قد تحدث، سواء في نقل HTTP الأساسي أو رسائل الخطأ التي يتم إنشاؤها من خدمة واجهة برمجة التطبيقات. تم توثيق تنسيق الأخطاء كجزء من دليل أسلوب JSON من Google.

أمثلة

يعرض القسم التالي مثالاً بسيطًا على مكتبة برامج لواجهات برمجة التطبيقات.

برنامج واجهة برمجة التطبيقات البسيطة

في ما يلي مثال على مكتبة برامج بسيطة جدًا مكتوبة بلغة Python3. ينشئ العميل واجهة للتفاعل مع Service Usage API، ثم يستخدم هذه الواجهة لتفعيل Compute Engine API (compute.googleapis.com) في المشروع my-project.

تحذير: الرمز البرمجي أدناه هو إصدار مبسّط بشكل كبير من مكتبة برامج نموذجية للعملاء. وهي عملية تنفيذ غير مكتملة يتم توفيرها لتوضيح بعض جوانب إنشاء مكتبة برامج للعملاء. وهو ليس رمزًا برمجيًا جاهزًا للاستخدام.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
location = None # Set this to your location if appropriate
use_global_endpoint = True # Set this to False if you want to target the endpoint for your location

# Step 2.a: Construct base URI
BASE_URL = None
if not use_global_endpoint and location:
  if discovery['endpoints']:
    BASE_URL = next((item['endpointUrl'] for item in discovery['endpoints'] if item['location'] == location), None)
if not BASE_URL:
  BASE_URL = discovery['rootUrl']
BASE_URL += discovery['servicePath']

class Collection(object): pass

def createNewMethod(name, method):
  # Step 2.b Compose request
  def newMethod(**kwargs):
    body = kwargs.pop('body', None)
    url = urllib.parse.urljoin(BASE_URL, uritemplate.expand(method['path'], kwargs))
    for pname, pconfig in method.get('parameters', {}).items():
      if pconfig['location'] == 'path' and pname in kwargs:
        del kwargs[pname]
    if kwargs:
      url = url + '?' + urllib.parse.urlencode(kwargs)
    return h.request(url, method=method['httpMethod'], body=body,
                     headers={'content-type': 'application/json'})

  return newMethod

# Step 3.a: Build client surface
def build(discovery, collection):
  for name, resource in discovery.get('resources', {}).items():
    setattr(collection, name, build(resource, Collection()))
  for name, method in discovery.get('methods', {}).items():
    setattr(collection, name, createNewMethod(name, method))
  return collection

# Step 3.b: Use the client
service = build(discovery, Collection())
print (serviceusage.services.enable(name='projects/my-project/services/compute.googleapis.com'))

المكوّنات الأساسية للعميل هي:

• الخطوة 1: استرجاع مستند Discovery يتم استرداد مستند Discovery لواجهة برمجة التطبيقات Service Usage API وتحليله إلى بنية بيانات. بما أنّ Python هي لغة ذات كتابة ديناميكية، يمكن جلب مستند Discovery في وقت التشغيل.
• الخطوة 2.أ: إنشاء معرّف الموارد المنتظم الأساسي يتم احتساب معرّف الموارد المنتظم الأساسي.
• الخطوة 2(ب): إنشاء الطلب عند استدعاء طريقة في مجموعة، يتم توسيع نموذج URI باستخدام المَعلمات التي تم تمريرها إلى الطريقة، ويتم وضع المَعلمات التي تتضمّن الموقع query في مَعلمات طلب البحث لعنوان URL. وأخيرًا، يتم إرسال طلب إلى عنوان URL الذي تم إنشاؤه باستخدام طريقة HTTP المحدّدة في مستند Discovery.
• الخطوة 3 (أ): إنشاء مساحة عرض العميل يتم إنشاء واجهة العميل من خلال الانتقال بشكل متكرّر إلى أسفل مستند Discovery الذي تم تحليله. لكل طريقة في القسم methods، يتم إرفاق طريقة جديدة بالكائن Collection. بما أنّه يمكن تضمين المجموعات في مجموعات أخرى، نبحث عن resources وننشئ بشكل متكرّر عنصر Collection لجميع العناصر المضمّنة فيه إذا تم العثور على عنصر. يتم أيضًا إرفاق كل مجموعة مدمجة كسمة بكائن Collection.
• الخطوة 3.ب: استخدام العميل يوضّح هذا المثال كيفية استخدام مساحة واجهة برمجة التطبيقات المضمّنة. يتم أولاً إنشاء عنصر خدمة من مستند Discovery، ثم يتم استخدام واجهة برمجة التطبيقات Service Usage لتفعيل Compute Engine API في المشروع my-project.