สร้างไลบรารีของไคลเอ็นต์

คุณสามารถใช้บริการค้นหา Google APIs เพื่อสร้างเครื่องมือต่างๆ ที่จะใช้กับ Google APIs ได้ อย่างไรก็ตาม วัตถุประสงค์หลักของเอกสาร Discovery คือการอนุญาตให้ Google สร้างไลบรารีของไคลเอ็นต์ ในภาษาโปรแกรมต่างๆ เอกสารนี้อธิบายวิธีสร้างไลบรารีของไคลเอ็นต์ที่กำหนดเองสำหรับ Google APIs

ไลบรารีของไคลเอ็นต์ที่เสถียรและมีฟีเจอร์ครบถ้วนเป็นเครื่องมือที่ซับซ้อนซึ่งอาจใช้เวลาหลายเดือนในการ พัฒนา อย่างไรก็ตาม วิธีการทั่วไปในการสร้างไลบรารีของไคลเอ็นต์อย่างง่ายสำหรับ Google APIs สามารถแบ่งออกเป็น 3 ขั้นตอนง่ายๆ ดังนี้

1. การดึงข้อมูลเอกสารการค้นพบและการสร้างพื้นผิว API
2. การเขียนคำขอ
3. การโทรออกและดึงข้อมูลการตอบกลับ

เราจะอธิบายขั้นตอนเหล่านี้โดยละเอียดในส่วนต่อไปนี้ นอกจากนี้ คุณยังดูตัวอย่างไคลเอ็นต์ API อย่างง่ายในส่วนตัวอย่างเพื่อดูวิธี จับคู่วิธีการเหล่านี้กับโค้ดได้ด้วย

ดึงข้อมูลเอกสารการค้นพบ

ก่อนที่จะเริ่มใช้ไลบรารีของไคลเอ็นต์ คุณต้องมีข้อกำหนดพื้นฐานบางอย่างซึ่งส่งผลต่อ วิธีที่คุณจะดำเนินการตามเส้นทางการพัฒนา ตัวอย่างเช่น ภาษาโปรแกรมที่คุณเลือกอาจเป็นแบบมีหรือไม่มีการพิมพ์ หากเป็นแบบมีการพิมพ์ ก็อาจเป็นแบบคงที่หรือแบบไดนามิก โดยอาจมีการคอมไพล์หรือตีความ ข้อกำหนดเหล่านี้จะช่วยกำหนดแนวทาง ในการใช้และใช้เอกสาร Discovery

งานพัฒนาแรกคือการดึงข้อมูลเอกสาร Discovery กลยุทธ์สำหรับเวลาที่แน่นอนในการดึงข้อมูลเอกสารจะกำหนดโดยข้อกำหนดที่คุณระบุ ตัวอย่างเช่น ในภาษาที่ต้องระบุประเภทตัวแปรแบบคงที่ คุณอาจดึงข้อมูลเอกสาร Discovery ตั้งแต่เนิ่นๆ ในกระบวนการ แล้วสร้างโค้ดเพื่อจัดการ API ที่เฉพาะเจาะจงซึ่งอธิบายไว้ในเอกสาร Discovery สำหรับ ภาษาที่มีการพิมพ์อย่างเข้มงวด คุณอาจสร้างโค้ดบางส่วนและสร้างไลบรารีที่คอมไพล์แล้ว สำหรับภาษาที่พิมพ์แบบไดนามิก คุณสามารถสร้างโครงสร้างการเขียนโปรแกรมแบบเลซีเพื่อเชื่อมต่อกับ API ได้ทันทีเมื่อใช้พื้นผิวการเขียนโปรแกรม

เขียนคำขอ

การเขียนคำขอมี 2 ขั้นตอนแยกกัน ดังนี้

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. หากคุณทราบตำแหน่ง (ภูมิภาค) และเอกสาร Discovery มีพร็อพเพอร์ตี้ endpoints ให้ตรวจสอบว่าตำแหน่งของคุณอยู่ในรายการ endpoints หรือไม่ หากเป็นเช่นนั้น ให้ใช้ endpointUrl จากรายการ endpoints ที่มี location ตรงกับของคุณ

2. หากไม่มีพร็อพเพอร์ตี้ endpoints ในเอกสาร Discovery หรือไม่มีตำแหน่งของคุณในรายการ endpoints หรือคุณต้องการกำหนดเป้าหมายไปยังปลายทางทั่วโลก ให้ดึงพร็อพเพอร์ตี้ rootUrl จากระดับบนสุดของเอกสาร Discovery

   ตัวอย่างเช่น พร็อพเพอร์ตี้ rootUrl ใน เอกสารการค้นพบสำหรับ Service Usage API คือ

   https://serviceusage.googleapis.com/

3. รับ servicePath จากระดับบนสุดของเอกสาร Discovery ตัวอย่างเช่น พร็อพเพอร์ตี้ servicePath ในเอกสาร Discovery สำหรับ Service Usage API ว่างเปล่า

4. ต่อกันเพื่อรับ

   https://serviceusage.googleapis.com/

5. คว้าพร็อพเพอร์ตี้ path ขยายเป็นเทมเพลต URI แล้วรวมผลลัพธ์ ของการขยายนั้นกับ URI จากขั้นตอนก่อนหน้า ตัวอย่างเช่น ในเมธอด serviceusage.services.enable ของ Service Usage API เวอร์ชัน 1 ค่าของพร็อพเพอร์ตี้ 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 รูปแบบของข้อผิดพลาด มีการบันทึกไว้เป็นส่วนหนึ่งของคู่มือรูปแบบ JSON ของ Google

ตัวอย่าง

ส่วนต่อไปนี้แสดงตัวอย่างไลบรารีของไคลเอ็นต์ 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: ดึงข้อมูลเอกสารการค้นพบ ระบบจะดึงข้อมูลและแยกวิเคราะห์เอกสารการค้นพบสำหรับ Service Usage API เป็นโครงสร้างข้อมูล เนื่องจาก Python เป็นภาษาที่พิมพ์แบบไดนามิก คุณจึงดึงข้อมูลเอกสาร Discovery ได้ที่รันไทม์
• ขั้นตอนที่ 2.ก: สร้าง URI ฐาน ระบบจะคำนวณ URI ฐาน
• ขั้นตอนที่ 2.ข: เขียนคำขอ เมื่อเรียกใช้เมธอด ในคอลเล็กชัน ระบบจะขยายเทมเพลต URI ด้วยพารามิเตอร์ที่ส่งไปยังเมธอด และพารามิเตอร์ที่มีตำแหน่งเป็น query จะอยู่ในพารามิเตอร์การค้นหาของ URL สุดท้าย ระบบจะส่งคำขอไปยัง URL ที่สร้างขึ้นโดยใช้เมธอด HTTP ที่ระบุไว้ในเอกสารการค้นพบ
• ขั้นตอนที่ 3.ก: สร้างอินเทอร์เฟซไคลเอ็นต์ ไคลเอ็นต์ สร้างขึ้นโดยการลงไปในเอกสาร Discovery ที่แยกวิเคราะห์แล้วแบบเรียกซ้ำ สำหรับแต่ละ เมธอดในส่วน methods ระบบจะแนบเมธอดใหม่กับออบเจ็กต์ Collection เนื่องจากคอลเล็กชันซ้อนกันได้ เราจึงค้นหา resources และสร้างออบเจ็กต์ Collection แบบเรียกซ้ำสำหรับสมาชิกทั้งหมด หากพบ ระบบจะแนบคอลเล็กชันที่ซ้อนกันแต่ละรายการเป็นแอตทริบิวต์กับออบเจ็กต์ Collection ด้วย
• ขั้นตอนที่ 3.b: ใช้ไคลเอ็นต์ ซึ่งแสดงให้เห็นว่ามีการใช้พื้นผิว API ที่สร้างขึ้นอย่างไร ก่อนอื่นจะสร้างออบเจ็กต์บริการจากเอกสาร Discovery จากนั้นจะใช้ Service Usage API เพื่อเปิดใช้ Compute Engine API ในโปรเจ็กต์ my-project