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

مقدمة

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

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

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

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

الخطوة 1: جلب مستند "اقتراحات"

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

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

الخطوة 2: إنشاء طلب

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

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

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

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

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

/example/path/var

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

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

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

1. استخدِم السمة rootUrl من المستوى الأعلى في مستند"اقتراحات".
   على سبيل المثال، خاصية rootUrl في مستند أثناء التصفّح لـ Google Cloud Service Management API هي:

   https://servicemanagement.googleapis.com/

2. اسحَب servicePath من المستوى الأعلى من مستند"اقتراحات".
   على سبيل المثال، السمة servicePath في مستند "اقتراحات" لواجهة برمجة تطبيقات إدارة خدمة Google Cloud فارغة.

3. اربطهما معًا للحصول على:

   https://servicemanagement.googleapis.com/

4. يجب الحصول على السمة path وتوسيعها كنموذج معرّف موارد منتظم (URI) ودمج نتائج عملية التوسيع هذه مع معرّف الموارد المنتظم (URI) من الخطوة السابقة.
   على سبيل المثال، في واجهة برمجة تطبيقات إدارة خدمة get في Google Cloud Service Management API، تكون قيمة السمة path هي v1/services/{serviceName}. لذلك، فإن معرّف الموارد المنتظم (URI) الكامل للطريقة هو:

   https://servicemanagement.googleapis.com/v1/services/{serviceName}

يجب توفير مفتاح واجهة برمجة تطبيقات لاستدعاء Google Cloud Service Management API. لذلك، بعد تطبيق مفتاح واجهة برمجة تطبيقات، يكون معرّف الموارد المنتظم (URI) الكامل للحصول على تعريف خدمة خدمة استكشاف واجهة برمجة التطبيقات هو:

https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY

الخطوة 3: إجراء مكالمة ومعالجة الرد

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

أمثلة

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

عميل API بسيط

في ما يلي مثال على مكتبة عميل بسيطة جدًا مكتوبة بلغة Python3 . ينشئ العميل واجهة للتفاعل مع Google Cloud Service Management API، ثم يحصل على تعريف خدمة خدمة Discovery API باستخدام هذه الواجهة.

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

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)

# Step 2.a: Construct base URI
BASE_URL = discovery['rootUrl'] + 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 (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))

تتمثل المكونات الرئيسية للعميل في:

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