יצירת ספריית לקוח

אתם יכולים להשתמש בשירות Google APIs Discovery כדי ליצור מגוון כלים שונים לשימוש עם ממשקי Google API. עם זאת, המטרה העיקרית של מסמך Discovery היא לאפשר ל-Google ליצור ספריות לקוח בשפות תכנות שונות. במסמך הזה מוסבר איך ליצור ספריית לקוח בהתאמה אישית ל-Google APIs.

ספריית לקוח יציבה עם כל התכונות היא כלי מורכב שיכול לקחת חודשים לפתח. עם זאת, ההוראות הכלליות ליצירת ספריית לקוח פשוטה ל-Google APIs ניתנות לפירוק לשלושה שלבים פשוטים:

1. אחזור של מסמך הגילוי ויצירת ממשק API
2. כתיבת בקשה
3. ביצוע שיחה ואחזור התשובה

השלבים האלה מפורטים בהמשך. אפשר גם לעיין בדוגמה Simple APIs client בקטע Examples כדי לראות איך ההוראות האלה משתקפות בקוד.

אחזור מסמך הגילוי

לפני שמתחילים להטמיע ספריית לקוח, יש כמה דרישות בסיסיות שמשפיעות על המשך תהליך הפיתוח. לדוגמה, שפת התכנות שתבחרו יכולה להיות שפה עם הקלדה או שפה ללא הקלדה. אם זו שפה עם הקלדה, היא יכולה להיות שפה עם הקלדה סטטית או שפה עם הקלדה דינמית. יכול להיות שהיא עוברת קומפילציה או פרשנות. הדרישות האלה יעזרו לכם להבין איך להשתמש במסמך Discovery.

משימת הפיתוח הראשונה היא אחזור מסמך הגילוי. השיטה שלכם לקביעת הרגע המדויק שבו המסמך יאוחזר נקבעת לפי הדרישות שזיהיתם. לדוגמה, בשפה עם הקלדה סטטית, אפשר לאחזר את מסמך הגילוי בשלב מוקדם בתהליך ואז ליצור קוד לטיפול בממשק ה-API הספציפי שמתואר במסמך הגילוי. בשפה עם הקלדה חזקה, יכול להיות שתצטרכו ליצור קוד ולבנות ספרייה שעברה קומפילציה. בשפה עם הקלדה דינמית, אפשר ליצור את מבני התכנות באופן עצלני כדי ליצור ממשק ל-API תוך כדי תנועה, בזמן השימוש בממשק התכנות.

כתיבת בקשה

כתיבת בקשות כוללת שני שלבים נפרדים:

1. כתיבת גוף הבקשה.
2. הרכבת כתובת ה-URL של הבקשה.

אם יש גוף בקשה, צריך להמיר אותו מייצוג מתאים לשפה לפורמט הנכון של העברת נתונים. לדוגמה, בספריית לקוח של Java, יכול להיות שיש מחלקה לכל סוג בקשה שמאפשרת מניפולציה של נתוני הבקשה בצורה בטוחה מבחינת סוג, וניתן לבצע סריאליזציה שלה ל-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. אם אתם יודעים מה המיקום (האזור) שלכם, ובמסמך הגילוי מופיעה המאפיין endpoints, בדקו אם המיקום שלכם מופיע ברשימה endpoints. אם כן, מעתיקים את endpointUrl מהרשימה endpoints שבה location זהה לערך שלכם.

2. אם אין נכס endpoints במסמך הגילוי או שהמיקום שלכם לא מופיע ברשימה endpoints או שאתם רוצים לטרגט את נקודת הקצה הגלובלית, צריך לאחזר את הנכס rootUrl מהרמה העליונה של מסמך הגילוי.

   לדוגמה, המאפיין rootUrl ב Discovery document של Service Usage API הוא:

   https://serviceusage.googleapis.com/

3. מעתיקים את servicePath מהרמה העליונה של מסמך ה-Discovery. לדוגמה, המאפיין servicePath במסמך הגילוי של Service Usage API ריק.

4. משרשרים אותם כדי לקבל:

   https://serviceusage.googleapis.com/

5. מעתיקים את המאפיין path, מרחיבים אותו כתבנית URI ומשלבים את התוצאות של ההרחבה עם ה-URI מהשלב הקודם. לדוגמה, בשיטה serviceusage.services.enable של Service Usage API v1, הערך של המאפיין path הוא v1/{+name}:enable. לכן, ה-URI המלא של השיטה הוא:

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

לא צריך מפתח API כדי לשלוח קריאה ל-Service Usage API. עם זאת, אם ה-API שאליו אתם שולחים קריאה דורש מפתח API, אתם יכולים להוסיף את מפתח ה-API למחרוזת השאילתה של ה-URI:

REQUEST_URI?key=API_KEY

ביצוע שיחה וטיפול בתגובה

אחרי ששולחים את הבקשה, צריך לבצע דה-סריאליזציה של התגובה לייצוג בשפה המתאימה, תוך הקפדה על טיפול בתנאי שגיאה שיכולים להתרחש – גם בתעבורת ה-HTTP הבסיסית וגם בהודעות שגיאה שנוצרות משירות ה-API. הפורמט של השגיאות מתועד כחלק ממדריך הסגנון של Google JSON.

דוגמאות

בקטע הבא מופיעה דוגמה פשוטה לספריית לקוח של ממשקי API.

לקוח Simple APIs

בהמשך מופיעה דוגמה לספריית לקוח פשוטה מאוד שנכתבה ב-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 document של Service Usage API מאוחזר ומנותח למבנה נתונים. מכיוון ש-Python היא שפה עם הקלדה דינמית, אפשר לאחזר את מסמך ה-Discovery בזמן הריצה.
• שלב 2.א: יוצרים את ה-URI הבסיסי. מחושב ה-URI הבסיסי.
• שלב 2.ב: כותבים את הבקשה. כשמפעילים שיטה באוסף, תבנית ה-URI מתרחבת עם הפרמטרים שמועברים לשיטה, והפרמטרים עם המיקום query מוכנסים לפרמטרים של השאילתה בכתובת ה-URL. לבסוף, נשלחת בקשה לכתובת ה-URL המורכבת באמצעות שיטת ה-HTTP שצוינה במסמך ה-Discovery.
• שלב 3א: פיתוח ממשק הלקוח. ממשק הלקוח נוצר על ידי ירידה רקורסיבית במסמך הגילוי המנותח. לכל method בקטע methods מצורף method חדש לאובייקט Collection. מכיוון שאפשר להטמיע אוספים בתוך אוספים, אנחנו מחפשים את resources ויוצרים באופן רקורסיבי אובייקט Collection לכל החברים שלו אם נמצא אחד. כל אוסף מקונן מצורף גם כמאפיין לאובייקט Collection.
• שלב 3.ב: שימוש בלקוח. הדוגמה הזו מדגימה איך משתמשים בממשק ה-API המובנה. קודם יוצרים אובייקט שירות ממסמך Discovery, ואז משתמשים ב-Service Usage API כדי להפעיל את Compute Engine API בפרויקט my-project.