บทนำ

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

ลองใช้เลยใน API Explorer

รับเอกสารการค้นพบสําหรับ Google Cloud Service Management API เวอร์ชัน 1:

GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1