Discovery API จะมีรายการ Google API สําหรับดึงข้อมูลเมตาที่เครื่องอ่านได้ "เอกสารการค้นพบ" สําหรับ API แต่ละรายการ
เอกสารนี้มีไว้สําหรับนักพัฒนาซอฟต์แวร์ที่ต้องการเขียนไลบรารีของไคลเอ็นต์ ปลั๊กอิน IDE และเครื่องมืออื่นๆ สําหรับการโต้ตอบกับ Google API
พื้นหลังของบริการ Discovery
แนวคิด
บริการ Discovery ของ Google APIs สร้างขึ้นจากแนวคิดพื้นฐาน 2 ข้อ ได้แก่
- ไดเรกทอรี API: รายการ API ทั้งหมดที่รองรับบริการ API Discovery แต่ละรายการในไดเรกทอรีจะแสดงรายละเอียดเกี่ยวกับ API ที่รองรับ ซึ่งรวมถึงชื่อ, คําอธิบายแบบย่อของสิ่งที่ API ทํางาน และลิงก์เอกสาร API อาจมีรายการไดเรกทอรีหลายรายการ โดยที่รายการหนึ่งสําหรับแต่ละเวอร์ชันที่รองรับ
- เอกสารการค้นพบ: คําอธิบายของ API ที่เครื่องสามารถอ่านได้ เอกสารการค้นพบจะอธิบายแพลตฟอร์มของ API เวอร์ชันที่เจาะจง เอกสารมีรายละเอียดเกี่ยวกับวิธีต่างๆ ในการเข้าถึงแต่ละ API ผ่านการเรียก HTTP ของ RESTful เอกสารการค้นพบจะมีคําอธิบายข้อมูลและวิธีการที่เชื่อมโยงกับ API รวมถึงข้อมูลเกี่ยวกับขอบเขต OAuth ที่ใช้ได้ และคําอธิบายของสคีมา วิธี พารามิเตอร์ และค่าพารามิเตอร์ที่ใช้ได้
โมเดลข้อมูล
ทรัพยากรคือเอนทิตีข้อมูลแต่ละรายการที่มีตัวระบุที่ไม่ซ้ํากัน บริการ Discovery ของ Google APIs ทํางานบนทรัพยากร 2 ประเภทตามแนวคิดข้างต้น
รายการไดเรกทอรี API: รายการ API
แต่ละรายการในไดเรกทอรีจะมีคู่ name/version ของ API ที่มีข้อมูลดังต่อไปนี้
- ข้อมูลระบุตัวตนและรายละเอียด: ชื่อ เวอร์ชัน ชื่อ และคําอธิบาย
- ข้อมูลเอกสาร: ไอคอนและลิงก์เอกสาร
- ข้อมูลสถานะ รวมถึงป้ายกํากับสถานะ และตัวบ่งชี้ว่านี่เป็นเวอร์ชัน API ที่ต้องการหรือไม่
- ลิงก์เอกสารการค้นพบ, URI ของเอกสารการค้นพบสําหรับ API นี้ (ระบุเป็น URL แบบเต็ม เช่น https://servicemanagement.googleapis.com/$discovery/rest?version=v1)
ทรัพยากรเอกสารการค้นพบ: คําอธิบายของ API ที่เครื่องสามารถอ่านได้
นอกเหนือจากข้อมูลที่ระบุในไดเรกทอรี API แล้ว เอกสาร Discovery ยังประกอบด้วยข้อมูลต่อไปนี้
- สคีมา ซึ่งเป็นรายการสคีมาทรัพยากร API ที่อธิบายข้อมูลที่คุณมีสิทธิ์เข้าถึงในแต่ละ API สคีมาบริการ Discovery ของ Google API จะอิงตามสคีมา JSON
- เมธอด รวมถึงรายการเมธอด API และพารามิเตอร์ที่ใช้ได้สําหรับแต่ละเมธอด
- ขอบเขต OAuth ซึ่งระบุรายการขอบเขต OAuth ที่พร้อมใช้งานสําหรับ API นี้
- เอกสารประกอบในบรรทัด ซึ่งจะให้คําอธิบายคร่าวๆ เกี่ยวกับสคีมา เมธอด พารามิเตอร์ และค่าพารามิเตอร์ที่มีอยู่
คอลเล็กชันไดเรกทอรีเดียวคือคอนเทนเนอร์แนวคิดของทรัพยากรไดเรกทอรี API รายการเดียว รวมถึงทรัพยากรเอกสารการค้นพบสําหรับ API ที่รองรับแต่ละรายการ
โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับทรัพยากรไดเรกทอรี API และทรัพยากรเอกสาร Discovery ในเอกสารการใช้ API และข้อมูลอ้างอิง
การดำเนินการ
คุณเรียกใช้คอลเล็กชันสําหรับทรัพยากรและทรัพยากรได้ 2 วิธีในบริการ Discovery ของ Google APIs ดังที่อธิบายไว้ในตารางต่อไปนี้
| การดำเนินการ | คำอธิบาย | การแมป HTTP ของ REST |
|---|---|---|
| list | แสดงรายการ API ทั้งหมดที่รองรับ | GET ใน URI ทรัพยากรไดเรกทอรี |
รูปแบบการโทร
REST
การดําเนินการบริการ Discovery ของ Google API ที่รองรับจะแมปกับคํากริยาของ REST HTTP GET โดยตรงตามที่อธิบายไว้ในการดําเนินการ
รูปแบบเฉพาะสําหรับ URI บริการ Discovery ของ Google APIs มีดังนี้
https://discovery.googleapis.com/discovery/v1/apis?parameters
โดยที่ api คือตัวระบุสําหรับทรัพยากรเอกสารการค้นพบ และ version เป็นตัวระบุของ API เวอร์ชันที่เจาะจงและ _parameters_ เป็นพารามิเตอร์ที่จะใช้กับการค้นหา โปรดดูรายละเอียดในสรุปพารามิเตอร์การค้นหาในเอกสารประกอบอ้างอิง
รายละเอียดเกี่ยวกับชุด URI ทั้งหมดที่ใช้สําหรับการดําเนินการที่รองรับแต่ละรายการใน API ได้สรุปไว้ในเอกสารเอกสารอ้างอิงบริการการค้นพบของ Google API
ตัวอย่างบริการใน Google APIs Discovery Service มีดังนี้
แสดงรายการ API ทั้งหมดที่รองรับบริการ Google APIs Discovery
GET https://discovery.googleapis.com/discovery/v1/apis
รับเอกสารการค้นพบสําหรับ Google Cloud Service Management API เวอร์ชัน 1:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1