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

מבוא

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

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

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

שלבים אלה מתוארים בפירוט רב בקטעים הבאים. אפשר גם לעיין בדוגמה של הלקוח של ממשקי API פשוטים בקטע 'דוגמאות' כדי לראות את ההוראות שממופים לקוד.

שלב 1: אחזור של מסמך Discovery

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

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

שלב 2: כותבים בקשה

חישוב בקשה מורכב משני שלבים נפרדים:

1. מחברים את גוף הבקשה.
2. אנחנו יוצרים את כתובת ה-URL של הבקשה.

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

יצירת כתובת ה-URL של הבקשה היא תהליך קצת יותר מורכב.

הנכס path של כל שיטה ב-API משתמש בתחביר URI של תבנית 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:

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

שלב 3: מתקשרים וטיפול בתגובה

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

דוגמאות

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