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

บทนำ

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

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

1. กําลังดึงข้อมูลเอกสารการค้นพบและการสร้างแพลตฟอร์ม API
2. การเขียนคําขอ
3. การโทรออกและดึงข้อมูลการตอบกลับ

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

ขั้นตอนที่ 1: ดึงเอกสารการค้นพบ

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

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

ขั้นตอนที่ 2: เขียนคําขอ

การเขียนคําขอประกอบด้วย 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 ในเอกสารการค้นพบสําหรับ 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 จากขั้นตอนก่อนหน้า
   เช่น ในเมธอดบริการ Google Cloud Service Management API ของ get ค่าของพร็อพเพอร์ตี้ path คือ v1/services/{serviceName} ดังนั้น URI แบบเต็มของเมธอดคือ

   https://servicemanagement.googleapis.com/v1/services/{serviceName}

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