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