บทนำ
คุณสามารถใช้ Google API Discovery Service เพื่อสร้างเครื่องมือต่างๆ มากมายเพื่อใช้กับ Google API อย่างไรก็ตาม วัตถุประสงค์หลักของเอกสารการค้นพบคือการทําให้ Google สร้างไลบรารีของไคลเอ็นต์ได้ในภาษาโปรแกรมต่างๆ ส่วนนี้จะอธิบายถึงวิธีการสร้างไลบรารีไคลเอ็นต์ที่กําหนดเองสําหรับ Google API
ไลบรารีของไคลเอ็นต์ที่เสถียรและสมบูรณ์เป็นเครื่องมือซึ่งอาจใช้เวลาในการพัฒนาหลายเดือน อย่างไรก็ตาม คําแนะนําทั่วไปสําหรับการสร้างไลบรารีไคลเอ็นต์แบบง่ายสําหรับ Google APIs อาจแบ่งออกเป็น 3 ขั้นตอนง่ายๆ ดังนี้
- กําลังดึงข้อมูลเอกสารการค้นพบและการสร้างแพลตฟอร์ม API
- การเขียนคําขอ
- การโทรออกและดึงข้อมูลการตอบกลับ
ขั้นตอนเหล่านี้ได้รับการอธิบายโดยละเอียดในส่วนต่อไปนี้ นอกจากนี้คุณยังดูตัวอย่างไคลเอ็นต์ API แบบง่ายได้ในส่วน "ตัวอย่าง" เพื่อดูวิธีการแมปคําสั่งเหล่านี้กับโค้ด
ขั้นตอนที่ 1: ดึงเอกสารการค้นพบ
ก่อนที่จะเริ่มใช้ไลบรารีของไคลเอ็นต์ มีข้อกําหนดพื้นฐานบางประการที่ส่งผลต่อวิธีดําเนินการตามแนวทางการพัฒนาของคุณ ตัวอย่างเช่น ภาษาโปรแกรมที่คุณต้องการอาจพิมพ์หรือไม่พิมพ์ก็ได้ หากเป็นการพิมพ์ ก็อาจเป็นการพิมพ์แบบคงที่หรือแบบไดนามิกก็ได้ แต่อาจมีการรวบรวมหรือตีความไว้ ข้อกําหนดเหล่านี้เป็นแนวทางในการใช้และการใช้เอกสารการค้นพบ
งานแรกที่ต้องทําคือการดึงข้อมูลเอกสารการค้นพบ กลยุทธ์สําหรับกําหนดเวลาที่เอกสารจะถูกดึงข้อมูลจะขึ้นอยู่กับข้อกําหนดที่คุณระบุไว้ ตัวอย่างเช่น ในภาษาที่พิมพ์แบบคงที่ คุณอาจดึงเอกสาร Discovery ในช่วงต้นของกระบวนการ จากนั้นสร้างโค้ดเพื่อจัดการ API เฉพาะซึ่งอธิบายโดยเอกสาร Discovery คุณอาจสร้างรหัสขึ้นมาสําหรับภาษาที่พิมพ์ยาก และสร้างไลบรารีที่คอมไพล์แล้ว สําหรับภาษาที่พิมพ์แบบไดนามิก คุณสามารถสร้างโครงสร้างการเขียนโปรแกรมแบบ Lazy Loading เพื่อเชื่อมต่อกับ API ได้ทันทีที่ใช้แพลตฟอร์มการเขียนโปรแกรม
ขั้นตอนที่ 2: เขียนคําขอ
การเขียนคําขอประกอบด้วย 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 ที่สมบูรณ์ ให้ทําตามขั้นตอนต่อไปนี้
ดึงข้อมูลพร็อพเพอร์ตี้
rootUrl
จากระดับบนสุดของเอกสาร Discovery
ตัวอย่างเช่น พร็อพเพอร์ตี้rootUrl
ในเอกสารการค้นพบสําหรับ Google Cloud Service Management API คือhttps://servicemanagement.googleapis.com/
เลือก
servicePath
จากระดับบนสุดของเอกสาร Discovery
เช่น พร็อพเพอร์ตี้servicePath
ในเอกสาร Discovery สําหรับ Google Cloud Service Management API ว่างเปล่านําสมาชิกเหล่านั้นมารวมกันเพื่อรับรางวัล
https://servicemanagement.googleapis.com/
นําพร็อพเพอร์ตี้
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