ساخت کتابخانه مشتری

مقدمه

می‌توانید از Google APIs Discovery Service برای ساخت انواع ابزارهای مختلف برای استفاده با Google API استفاده کنید. با این حال، هدف اصلی سند Discovery این است که به Google اجازه دهد تا کتابخانه های مشتری را به زبان های برنامه نویسی مختلف ایجاد کند. این بخش نحوه ایجاد یک کتابخانه مشتری سفارشی برای Google API را توضیح می دهد.

یک کتابخانه مشتری پایدار و با ویژگی های کامل ابزار پیچیده ای است که توسعه آن ممکن است ماه ها طول بکشد. با این حال، دستورالعمل های کلی برای ساخت یک کتابخانه کلاینت ساده برای Google API را می توان به سه مرحله ساده تقسیم کرد:

  1. واکشی سند Discovery و ساختن سطح API
  2. نوشتن یک درخواست
  3. برقراری تماس و دریافت پاسخ

این مراحل در قسمت های بعدی با جزئیات بیشتر توضیح داده شده است. همچنین می‌توانید به نمونه سرویس گیرنده Simple APIs در بخش Examples نگاهی بیندازید تا ببینید این دستورالعمل‌ها چگونه به کد منطبق می‌شوند.

مرحله 1 : سند Discovery را واکشی کنید

قبل از شروع اجرای کتابخانه مشتری، برخی الزامات اساسی وجود دارد که بر نحوه ادامه مسیر توسعه خود تأثیر می گذارد. برای مثال، زبان برنامه نویسی انتخابی شما ممکن است تایپ شده یا بدون تایپ باشد. اگر تایپ شود می تواند به صورت استاتیک یا پویا تایپ شود. ممکن است تالیف یا تفسیر شود. این الزامات رویکرد شما را برای مصرف و استفاده از سند Discovery راهنمایی می کند.

اولین وظیفه توسعه واکشی سند Discovery است. استراتژی شما برای اینکه دقیقا چه زمانی سند باید واکشی شود، با الزاماتی که شناسایی کرده اید تعیین می شود. به عنوان مثال، در یک زبان تایپ ایستا، ممکن است سند Discovery را در مراحل اولیه واکشی کنید و سپس کدی را برای مدیریت API خاصی که توسط سند Discovery توضیح داده شده است، تولید کنید. برای یک زبان با تایپ قوی، ممکن است مقداری کد ایجاد کنید و یک کتابخانه کامپایل شده بسازید. برای یک زبان تایپ شده پویا، می‌توانید ساختارهای برنامه‌نویسی را با تنبلی بسازید تا همزمان با استفاده از سطح برنامه‌نویسی، به API متصل شوند.

مرحله 2 : یک درخواست بنویسید

نوشتن یک درخواست شامل دو مرحله جداگانه است:

  1. تنظیم بدن درخواست.
  2. ساخت URL درخواست

شما باید بدنه درخواست را، در صورت وجود، از یک نمایش مناسب زبان به قالب سیم درست تبدیل کنید. به عنوان مثال، در یک کتابخانه کلاینت جاوا، ممکن است یک کلاس برای هر نوع درخواست وجود داشته باشد که امکان دستکاری داده‌های درخواست را به صورت ایمن می‌دهد و در JSON قابل سریال‌سازی است.

ساخت URL درخواست فرآیند کمی پیچیده تر است.

ویژگی path هر روش در API از دستور URI Template v04 استفاده می کند. این ویژگی ممکن است شامل متغیرهایی باشد که توسط بریس های فرفری احاطه شده اند. در اینجا یک مثال از یک ویژگی path با متغیرها آورده شده است:

/example/path/var

در مسیر بالا، var یک متغیر است. مقدار این متغیر از بخش parameters سند Discovery برای آن روش می‌آید. نام هر متغیر دارای یک مقدار متناظر در شیء parameters است. در مثال بالا، پارامتری به نام var در قسمت parameters وجود دارد (و خاصیت location آن path است که نشان می دهد متغیر مسیر است).

هنگام درخواست، باید مقدار var را در URL جایگزین کنید. برای مثال، اگر کاربر کتابخانه انتخابی را انجام دهد که var را روی مقدار foo قرار دهد، URL جدید /example/path/foo خواهد بود.

همچنین توجه داشته باشید که ویژگی path یک URI نسبی است. برای محاسبه URI مطلق، مراحل زیر را دنبال کنید:

  1. ویژگی rootUrl را از سطح بالای سند Discovery بگیرید.
    به عنوان مثال، ویژگی rootUrl در سند Discovery برای Google Cloud Service Management API این است:

    https://servicemanagement.googleapis.com/

  2. servicePath را از سطح بالای سند Discovery بگیرید.
    برای مثال، ویژگی servicePath در سند Discovery برای Google Cloud Service Management API خالی است.

  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 یک کلید API لازم است. بنابراین، پس از اعمال یک کلید API، URI کامل برای دریافت تعریف سرویس API Discovery Service به صورت زیر است:

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

مرحله 3 : تماس بگیرید و پاسخ را مدیریت کنید

پس از ارسال درخواست، باید پاسخ را در بازنمایی زبان مناسب از حالت سریال خارج کنید، و مراقب باشید که شرایط خطایی که ممکن است رخ دهد - هم در انتقال HTTP اصلی و هم در پیام های خطای ایجاد شده از سرویس API. قالب خطاها به عنوان بخشی از راهنمای سبک JSON Google مستند شده است.

مثال ها

برای نمونه‌های عینی کتابخانه‌ها و ابزارهای سرویس گیرنده که با استفاده از سرویس اکتشاف Google APIs پیاده‌سازی شده‌اند، به سند کتابخانه‌ها و نمونه‌ها مراجعه کنید. علاوه بر این، بخش زیر یک مثال ساده از یک کتابخانه سرویس گیرنده API را ارائه می دهد.

سرویس گیرنده APIهای ساده

در زیر نمونه ای از یک کتابخانه کلاینت بسیار ساده نوشته شده در Python3 آورده شده است. مشتری یک رابط برای تعامل با Google Cloud Service Management API ایجاد می کند، سپس با استفاده از آن رابط، تعریف سرویس API Discovery Service را دریافت می کند.

هشدار : کد زیر یک نسخه ساده شده از یک کتابخانه معمولی مشتری است. این یک پیاده سازی ناقص است که برای نشان دادن برخی از جنبه های ساخت یک کتابخانه مشتری ارائه شده است. این کد آماده تولید نیست.

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 : سند Discovery را واکشی کنید .
    سند Discovery برای Google Cloud Service Management API بازیابی و در یک ساختار داده تجزیه می شود. از آنجایی که پایتون یک زبان تایپ پویا است، سند Discovery را می توان در زمان اجرا واکشی کرد.
  • مرحله 2.a : URI پایه را بسازید .
    URI پایه محاسبه می شود.
  • مرحله 2.b : درخواست را بنویسید .
    هنگامی که یک متد در مجموعه ای فراخوانی می شود، الگوی URI با پارامترهای ارسال شده به متد گسترش می یابد و پارامترهای دارای مکان query جو در پارامترهای پرس و جو URL قرار می گیرند. در نهایت یک درخواست با استفاده از روش HTTP که در سند Discovery مشخص شده است، به URL تشکیل شده ارسال می شود.
  • مرحله 3.a : ساختن سطح مشتری .
    سطح کلاینت با نزول بازگشتی بر روی سند Discovery تجزیه شده ساخته می شود. برای هر متد در بخش methods یک متد جدید به شی Collection پیوست می‌شود. از آنجا که مجموعه‌ها را می‌توان تودرتو کرد، ما به دنبال resources می‌گردیم و در صورت یافتن یک شی Collection برای همه اعضای آن به صورت بازگشتی می‌سازیم. هر مجموعه تو در تو نیز به عنوان یک ویژگی به شی Collection متصل می شود.
  • مرحله 3.b : از مشتری استفاده کنید .
    این نشان می دهد که چگونه از سطح API ساخته شده استفاده می شود. ابتدا یک شیء سرویس از سند Discovery ساخته می‌شود، سپس تعریف سرویس API Discovery Service از طریق Google Cloud Service Management API بازیابی می‌شود.