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

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

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

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

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

سند Discovery را واکشی کنید

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

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

یک درخواست بنویسید

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

  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. اگر مکان (منطقه) خود را می‌دانید و سند Discovery دارای ویژگی endpoints است، بررسی کنید که آیا مکان شما در لیست endpoints وجود دارد یا خیر. اگر چنین است، endpointUrl از لیست endpoints که location آن با شما مطابقت دارد، بردارید.

  2. اگر ویژگی endpoints در سند Discovery وجود ندارد یا مکان شما در لیست endpoints وجود ندارد یا می‌خواهید نقطه پایانی جهانی را هدف قرار دهید، ویژگی rootUrl را از سطح بالای سند Discovery بگیرید.

    به عنوان مثال، ویژگی rootUrl در سند Discovery برای سرویس Usage API عبارت است از:

    https://serviceusage.googleapis.com/
  3. servicePath از سطح بالای سند Discovery بگیرید. برای مثال، ویژگی servicePath در سند Discovery برای سرویس 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

برای تماس با سرویس Usage API نیازی به کلید API ندارید. با این حال، اگر API مورد نظر شما به یک کلید API نیاز دارد، می‌توانید کلید API را به رشته درخواست URI اضافه کنید:

REQUEST_URI?key=API_KEY

تماس بگیرید و پاسخ را رسیدگی کنید

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

نمونه ها

بخش زیر یک مثال ساده از یک کتابخانه سرویس گیرنده API را ارائه می دهد.

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

در زیر نمونه ای از یک کتابخانه کلاینت بسیار ساده نوشته شده در Python3 آورده شده است. مشتری یک رابط برای تعامل با سرویس 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 برای سرویس Usage 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 ساخته می‌شود، سپس از Service Usage API برای فعال کردن Compute Engine API در پروژه my-project استفاده می‌شود.