เอกสารนี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการเขียนไลบรารีของไคลเอ็นต์ ปลั๊กอิน IDE และ เครื่องมืออื่นๆ สำหรับการโต้ตอบกับ Google APIs Google APIs Discovery Service ช่วยให้คุณทำทุกอย่างที่กล่าวมาข้างต้นได้โดยการเปิดเผยข้อมูลเมตาที่เครื่องอ่านได้เกี่ยวกับ Google API อื่นๆ ผ่าน API ที่ใช้งานง่าย คู่มือนี้จะแสดงภาพรวมของแต่ละส่วนในเอกสาร Discovery รวมถึงเคล็ดลับที่เป็นประโยชน์ เกี่ยวกับวิธีใช้เอกสาร
การเรียก API ทั้งหมดเป็นคำขอ REST ที่ไม่มีการตรวจสอบสิทธิ์และอิงตาม JSON ซึ่งใช้ SSL กล่าวคือ URL ขึ้นต้นด้วย https
รูปแบบเอกสารการค้นพบ
ส่วนนี้จะแสดงภาพรวมของเอกสาร Discovery
ตัวอย่างทั้งหมดด้านล่างใช้เอกสารการค้นพบจาก Service Usage API
คุณโหลดเอกสารการค้นพบสำหรับ Service Usage API ได้โดยเรียกใช้GET
คำขอนี้
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1
รูปแบบของเอกสารการค้นพบมีข้อมูลที่จัดอยู่ใน 6 หมวดหมู่หลัก ดังนี้
- คำอธิบายพื้นฐานของ API
- ข้อมูลการตรวจสอบสิทธิ์สำหรับ API
- รายละเอียดทรัพยากรและสคีมาที่อธิบายข้อมูลของ API
- รายละเอียดเกี่ยวกับเมธอดของ API
- ข้อมูลเกี่ยวกับฟีเจอร์ที่กำหนดเองซึ่ง API รองรับ
- เอกสารประกอบในโค้ดที่อธิบายองค์ประกอบสำคัญ ของ API
ส่วนต่างๆ ของเอกสาร Discovery เหล่านี้มีคำอธิบายอยู่ด้านล่าง
คำอธิบาย API พื้นฐาน
เอกสาร Discovery มีชุดพร็อพเพอร์ตี้เฉพาะ API พร็อพเพอร์ตี้เหล่านี้ไม่จำเป็นต้อง ปรากฏตามลำดับนี้หรือในส่วนเดียวกันของเอกสารการค้นพบ
"id": "serviceusage:v1", "canonicalName": "Service Usage", "revision": "20240331", "servicePath": "", "baseUrl": "https://serviceusage.googleapis.com/", "kind": "discovery#restDescription", "description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.", "ownerDomain": "google.com", "version_module": true, "version": "v1", "fullyEncodeReservedExpansion": true, "name": "serviceusage", "title": "Service Usage API", "discoveryVersion": "v1", "rootUrl": "https://serviceusage.googleapis.com/", "protocol": "rest"
พร็อพเพอร์ตี้ระดับ API เหล่านี้มีรายละเอียดเกี่ยวกับ API เวอร์ชันหนึ่งๆ ซึ่งรวมถึง
name
, version
, title
และ
description
protocol
มีค่าคงที่เป็น
rest
เสมอ เนื่องจากบริการการค้นหา API รองรับเฉพาะวิธีการ RESTful ในการเข้าถึง
API
ฟิลด์ servicePath
ระบุคํานําหน้าเส้นทางสําหรับ API
เวอร์ชันนี้
การตรวจสอบสิทธิ์
ส่วน auth
มีรายละเอียดเกี่ยวกับขอบเขตการให้สิทธิ์ OAuth 2.0 สำหรับ API หากต้องการ
ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้ขอบเขตกับ OAuth 2.0 โปรดไปที่การใช้
OAuth 2.0 เพื่อเข้าถึง Google APIs
ส่วน auth
มีส่วน oauth2
และ scopes
ที่ซ้อนกันอยู่ ส่วน scopes
คือการแมปคีย์/ค่าจากค่าขอบเขตไปยังรายละเอียดเพิ่มเติมเกี่ยวกับขอบเขต
"auth": { "oauth2": { "scopes": { "https://www.googleapis.com/auth/cloud-platform": { "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account." }, "https://www.googleapis.com/auth/cloud-platform.read-only": { "description": "View your data across Google Cloud services and see the email address of your Google Account" }, "https://www.googleapis.com/auth/service.management": { "description": "Manage your Google API service configuration" } } } }
ส่วน auth
จะกำหนดขอบเขตสำหรับ API ที่เฉพาะเจาะจงเท่านั้น หากต้องการดูวิธีเชื่อมโยงขอบเขตเหล่านี้กับเมธอด API โปรดดูส่วนเมธอดด้านล่าง
แหล่งข้อมูลและสคีมา
การดำเนินการของ API จะทำงานกับออบเจ็กต์ข้อมูลที่เรียกว่า resources
เอกสารการค้นหา
สร้างขึ้นตามแนวคิดของทรัพยากร เอกสาร Discovery แต่ละรายการมีส่วนระดับบนสุด
resources
ที่จัดกลุ่มทรัพยากรทั้งหมดที่เชื่อมโยงกับ API ตัวอย่างเช่น Service Usage API มีทรัพยากร services
และทรัพยากร operations
ภายใต้ resources
ระดับบนสุด ดังนี้
"resources": { "services": { // Methods associated with the services resource } "operations": { // Methods associated with the operations resource } }
ภายในส่วนทรัพยากรแต่ละส่วนจะมีเมธอดที่เชื่อมโยงกับทรัพยากรนั้น เช่น Service Usage API มี 6 วิธีที่เชื่อมโยงกับทรัพยากร services
ได้แก่ get
, enable
, disable
, batchGet
, batchEnable
และ list
สคีมาจะบอกให้คุณทราบว่าทรัพยากรใน API มีลักษณะอย่างไร เอกสาร Discovery แต่ละรายการมีส่วนschemas
ระดับบนสุด ซึ่งมีคู่ชื่อ/ค่าของรหัสสคีมากับออบเจ็กต์
รหัสสคีมาจะไม่ซ้ำกันต่อ API และใช้เพื่อระบุสคีมาในส่วน
methods
ของเอกสารการค้นพบโดยไม่ซ้ำกัน ตัวอย่างเช่น ต่อไปนี้คือสคีมาบางส่วนในเอกสารการค้นพบ Service Usage API
"schemas": { "Method": { // JSON schema of the Method resource }, "Authentication": { // JSON schema of the Authentication resource }, "RubySettings": { // JSON schema of the RubySettings resource }, "EnableServiceResponse": { // JSON schema of the EnableServiceResponse resource } }
บริการตรวจหา API ใช้ JSON
Schema draft-03 สำหรับการแสดงสคีมา ต่อไปนี้คือข้อมูลโค้ดของสคีมา JSON
สำหรับEnableServiceResponse
ทรัพยากร รวมถึงGoogleApiServiceusagev1Service
ที่อ้างอิง นอกจากสคีมาเหล่านี้แล้ว ยังมีส่วนหนึ่งของการตอบกลับจริงสำหรับคำขอเปิดใช้ Pub/Sub API (pubsub.googleapis.com
) ด้วย
EnableServiceResponse สคีมา JSON ของทรัพยากร: |
การตอบกลับจริงสำหรับการเปิดใช้บริการ |
"EnableServiceResponse": { "id": "EnableServiceResponse", "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.", "properties": { "service": { "description": "The new state of the service after enabling.", "$ref": "GoogleApiServiceusageV1Service" } }, "type": "object" }, "GoogleApiServiceusageV1Service": { "description": "A service that is available for use by the consumer.", "properties": { "config": { "$ref": "GoogleApiServiceusageV1ServiceConfig", "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method." }, "name": { "type": "string", "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com" }, " |
"response": { "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse", "service": { "name": "projects/232342569935/services/pubsub.googleapis.com", "config": { "name": "pubsub.googleapis.com", "title": "Cloud Pub/Sub API", "documentation": { "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n" }, "quota": {}, "authentication": {}, "usage": { "requirements": [ "serviceusage.googleapis.com/tos/cloud" ] }, "monitoring": {} }, " |
ฟิลด์ในตัวหนาแสดงการแมประหว่างสคีมา JSON กับการตอบกลับจริง
ดังที่แสดงในตัวอย่างนี้ สคีมาอาจมีการอ้างอิงถึงสคีมาอื่นๆ หากคุณกำลังสร้าง
ไลบรารีของไคลเอ็นต์ สิ่งนี้จะช่วยให้คุณสร้างโมเดลออบเจ็กต์ของ API ในคลาสโมเดลข้อมูล
ได้อย่างมีประสิทธิภาพ ในEnableServiceResponse
ตัวอย่างด้านบน พร็อพเพอร์ตี้ service
คือการอ้างอิงถึงสคีมาที่มีรหัส GoogleApiServiceusageV1Service
ซึ่งเป็นสคีมาอีกรายการหนึ่งในเอกสารการค้นพบ Service Usage API คุณสามารถแทนที่พร็อพเพอร์ตี้
GoogleApiServiceusageV1Service
ในแหล่งข้อมูล EnableServiceResponse
ด้วยค่าของสคีมา GoogleApiServiceusageV1Service
(โปรดทราบว่าไวยากรณ์ $ref
มาจากข้อกำหนดของ JSON Schema)
เมธอดอาจอ้างอิงสคีมาเมื่อระบุเนื้อหาคำขอและการตอบกลับด้วย ดูรายละเอียดเพิ่มเติมได้ที่ส่วนวิธีการ
เมธอด
แกนหลักของเอกสารการค้นพบสร้างขึ้นจากเมธอด เมธอดคือการดำเนินการที่
ทำได้ใน API คุณจะเห็นส่วน methods
ในส่วนต่างๆ ของ
เอกสาร Discovery รวมถึงที่ระดับบนสุด (ซึ่งเราเรียกว่าเมธอดระดับ API) หรือที่ระดับ resources
"methods": { // API-level methods } "resources": { "resource1": { "methods": { // resource-level methods } "resources": { "nestedResource": { "methods": { // methods can even be found in nested-resources } } } } }
แม้ว่า API จะมีเมธอดระดับ API ได้ แต่ทรัพยากรต้องมีส่วน methods
methods
แต่ละส่วนmethods
คือแผนที่คีย์-ค่าจากชื่อเมธอดไปยังรายละเอียดอื่นๆ เกี่ยวกับเมธอดนั้น
ตัวอย่างด้านล่างแสดงวิธีการ 3 วิธี ได้แก่ get
, enable
และ disable
"methods": { "get": { //details about the "get" method }, "enable": { //details about the "enable" method }, "disable": { //details about the "disable" method } }
สุดท้ายนี้ ส่วนของแต่ละเมธอดจะแสดงรายละเอียดพร็อพเพอร์ตี้ต่างๆ เกี่ยวกับเมธอดนั้น ตัวอย่างของเมธอด enable
มีดังนี้
"enable": { "path": "v1/{+name}:enable", "request": { "$ref": "EnableServiceRequest" }, "parameterOrder": [ "name" ], "id": "serviceusage.services.enable", "response": { "$ref": "Operation" }, "description": "Enable a service so that it can be used with a project.", "httpMethod": "POST", "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable", "scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/service.management" ], "parameters": { "name": { "location": "path", "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.", "required": true, "type": "string", "pattern": "^[^/]+/[^/]+/services/[^/]+$" } } },
ส่วนนี้มีรายละเอียดทั่วไปของเมธอด เช่น ID
ที่ไม่ซ้ำกันเพื่อระบุเมธอด
httpMethod
ที่จะใช้ และpath
ของเมธอด (ดูรายละเอียดเกี่ยวกับวิธีใช้พร็อพเพอร์ตี้ path
เพื่อคำนวณ URL ของเมธอดแบบเต็มได้ที่ส่วนสร้างคำขอ) นอกจากพร็อพเพอร์ตี้ของเมธอดทั่วไปเหล่านี้แล้ว
ยังมีพร็อพเพอร์ตี้บางอย่างที่เชื่อมต่อเมธอดกับส่วนอื่นๆ ในเอกสาร Discovery ด้วย
ขอบเขต
ส่วน auth
ที่กำหนดไว้ก่อนหน้านี้ในเอกสารนี้มีข้อมูลเกี่ยวกับ
ขอบเขตทั้งหมดที่ API หนึ่งๆ รองรับ หากเมธอดรองรับขอบเขตใดขอบเขตหนึ่งเหล่านี้ เมธอดจะมีอาร์เรย์ขอบเขต
อาร์เรย์นี้มี 1 รายการสำหรับแต่ละขอบเขตที่เมธอดรองรับ
โปรดทราบว่าการเลือกขอบเขตการให้สิทธิ์ที่จะใช้ในแอปพลิเคชันขึ้นอยู่กับปัจจัยต่างๆ เช่น วิธีการที่เรียกใช้และพารามิเตอร์ที่ส่งพร้อมกับวิธีการ ดังนั้น นักพัฒนาแอปจึงต้องเป็นผู้พิจารณาว่าจะใช้ขอบเขตใด Discovery only documents which scopes are valid for a method.
คำขอและการตอบกลับ
หากเมธอดมีเนื้อหาคำขอหรือคำตอบ ระบบจะบันทึกเนื้อหาเหล่านี้ไว้ในส่วน request
หรือ response
ตามลำดับ เช่น สำหรับเมธอด enable
เนื้อหาของส่วน request
จะบ่งบอกว่าคำขอของเมธอดนั้นกำหนดโดย
สคีมา JSON ที่มีรหัส EnableServiceRequest
สคีมานี้จะอยู่ในส่วนสคีมาระดับบนสุด
พารามิเตอร์
หากเมธอดมีพารามิเตอร์ที่ผู้ใช้ควรระบุ พารามิเตอร์เหล่านี้จะ
บันทึกไว้ในส่วน parameters
ระดับเมธอด ส่วนนี้มี
การแมปคีย์/ค่าของชื่อพารามิเตอร์กับรายละเอียดเพิ่มเติมเกี่ยวกับพารามิเตอร์นั้น
เช่น เมธอด enable
มีพารามิเตอร์ 1 รายการคือ name
พารามิเตอร์จะอยู่ใน path
หรือ URL query
ก็ได้ โดยพร็อพเพอร์ตี้ location
จะระบุตำแหน่งที่ไคลเอ็นต์ไลบรารีควรวางพารามิเตอร์
นอกจากนี้ยังมีพร็อพเพอร์ตี้อื่นๆ อีกมากมายที่อธิบายพารามิเตอร์ ซึ่งรวมถึงข้อมูลพารามิเตอร์
type
(มีประโยชน์สำหรับภาษาที่ต้องระบุประเภทอย่างชัดเจน) พารามิเตอร์เป็น
required
หรือไม่ และพารามิเตอร์เป็น Enum หรือไม่ ดูรายละเอียดเพิ่มเติมเกี่ยวกับพร็อพเพอร์ตี้เหล่านี้ได้ในเอกสารอ้างอิง
สำหรับ API นี้
ลำดับพารามิเตอร์
Client Library สามารถจัดโครงสร้างอินเทอร์เฟซได้หลายวิธี วิธีหนึ่งคือการมีเมธอดที่มีพารามิเตอร์ API แต่ละรายการในลายเซ็นของเมธอด อย่างไรก็ตาม เนื่องจาก JSON เป็นรูปแบบที่ไม่มีลำดับ จึงเป็นเรื่องยากที่จะทราบโดยอัตโนมัติว่าจะจัดลำดับพารามิเตอร์ในลายเซ็นของเมธอดอย่างไร อาร์เรย์ parameterOrder
จะระบุลำดับพารามิเตอร์คงที่สำหรับ
การส่งคำขอ อาร์เรย์จะแสดงชื่อของพารามิเตอร์แต่ละรายการตามลำดับความสำคัญ โดยอาจมีพารามิเตอร์เส้นทางหรือพารามิเตอร์การค้นหา แต่ต้องมีพารามิเตอร์ทุกรายการในอาร์เรย์
การอัปโหลดสื่อ
หากเมธอดรองรับการอัปโหลดสื่อ เช่น รูปภาพ เสียง หรือวิดีโอ ระบบจะบันทึกตำแหน่งและ
โปรโตคอลที่รองรับสำหรับการอัปโหลดสื่อนั้นไว้ในส่วนmediaUpload
ส่วนนี้ประกอบด้วยรายละเอียดเกี่ยวกับโปรโตคอลการอัปโหลดที่รองรับ และ
ข้อมูลเกี่ยวกับสื่อประเภทที่อัปโหลดได้
เมธอด enable
ไม่มีส่วน mediaUpload
อย่างไรก็ตาม ส่วนmediaUpload
ทั่วไปอาจมีลักษณะดังนี้
"supportsMediaUpload": true, "mediaUpload": { "accept": [ "image/*" ], "maxSize": "10MB", "protocols": { "simple": { "multipart": true, "path": "/upload/storage/v1beta1/b/{bucket}/o" }, "resumable": { "multipart": true, "path": "/resumable/upload/storage/v1beta1/b/{bucket}/o" } } }
ในตัวอย่างด้านบน พร็อพเพอร์ตี้ supportsMediaUpload
เป็นค่าบูลีนที่
กำหนดว่าเมธอดรองรับการอัปโหลดสื่อหรือไม่ หากค่าเป็นจริง
mediaUpload
ส่วนจะระบุประเภทสื่อที่อัปโหลดได้
พร็อพเพอร์ตี้ accept
คือรายการ media-ranges ที่กำหนดว่าระบบยอมรับ
MIME ประเภทใดในการอัปโหลด ปลายทางที่แสดงในตัวอย่างข้างต้นจะยอมรับรูปแบบรูปภาพทุกรูปแบบ
พร็อพเพอร์ตี้ maxSize
มีขนาดสูงสุดของการอัปโหลด ค่านี้เป็นสตริงในหน่วย MB, GB หรือ TB ในตัวอย่างด้านบน การอัปโหลดจะจำกัดขนาดสูงสุดไว้ที่ 10 MB
โปรดทราบว่าค่านี้ไม่ได้แสดงโควต้าพื้นที่เก็บข้อมูลที่เหลือของผู้ใช้แต่ละรายสำหรับ API นั้น ดังนั้นแม้ว่าการอัปโหลดจะน้อยกว่า maxSize
ไคลเอ็นต์ไลบรารีก็ยังควร
เตรียมพร้อมที่จะจัดการการอัปโหลดที่ล้มเหลวเนื่องจากพื้นที่ไม่เพียงพอ
ส่วน protocols
จะแสดงโปรโตคอลการอัปโหลดที่เมธอดรองรับ โปรโตคอล simple
เป็นเพียงการ POST สื่อไปยังปลายทางที่ระบุในคำขอ HTTP เดียว
โปรโตคอล resumable
หมายความว่าปลายทางที่ระบุใน
path
URI รองรับโปรโตคอลการอัปโหลดต่อ หากพร็อพเพอร์ตี้ multipart
เป็น true
แสดงว่าปลายทาง
ยอมรับการอัปโหลดแบบหลายส่วน ซึ่งหมายความว่าทั้งคำขอ JSON และสื่อสามารถรวมไว้
ในเนื้อหา mutlipart/related และส่ง
พร้อมกันได้ โปรดทราบว่าทั้งโปรโตคอล simple
และ resumable
อาจรองรับ
การอัปโหลดหลายส่วน
พร็อพเพอร์ตี้ path
เป็นเทมเพลต URI และควรขยายเช่นเดียวกับพร็อพเพอร์ตี้
path
สำหรับเมธอด ตามที่ระบุไว้ในส่วนเขียนคำขอ
การดาวน์โหลดสื่อ
หากวิธีการรองรับการดาวน์โหลดสื่อ เช่น รูปภาพ เสียง หรือวิดีโอ ระบบจะระบุโดยใช้พารามิเตอร์ supportsMediaDownload
ดังนี้
"supportsMediaDownload": true,
เมื่อดาวน์โหลดสื่อ คุณต้องตั้งค่าพารามิเตอร์การค้นหา alt
เป็น media
ใน URL ของคำขอ
หากพร็อพเพอร์ตี้ useMediaDownloadService
ของเมธอด API เป็น true
ให้แทรก /download
ก่อน servicePath
เพื่อหลีกเลี่ยงการเปลี่ยนเส้นทาง เช่น เส้นทางการดาวน์โหลดคือ /download/youtube/v3/captions/{id}
หากการต่อกันของ servicePath
และ path
คือ /youtube/v3/captions/{id}
เราขอแนะนำให้สร้าง URL การดาวน์โหลดสื่อด้วย /download
แม้ว่า useMediaDownloadService
จะเป็นเท็จก็ตาม
พารามิเตอร์ทั่วไป
เอกสาร Discovery ระดับบนสุดมีพร็อพเพอร์ตี้ parameters
ส่วนนี้คล้ายกับส่วนพารามิเตอร์สำหรับแต่ละเมธอด แต่พารามิเตอร์เหล่านี้ใช้กับเมธอดใดก็ได้ใน API
เช่น เมธอด get
และ list
ของ Service Usage API สามารถมีพารามิเตอร์ prettyPrint
ในพารามิเตอร์คำขอ ซึ่งจะจัดรูปแบบการตอบกลับสำหรับเมธอดทั้งหมดเหล่านั้นในรูปแบบที่มนุษย์อ่านได้ ต่อไปนี้คือรายการพารามิเตอร์ที่ใช้กันโดยทั่วไป
พารามิเตอร์ | ความหมาย | หมายเหตุ | ประโยชน์ต่อการให้บริการ |
---|---|---|---|
access_token |
โทเค็น OAuth 2.0 สำหรับผู้ใช้ปัจจุบัน |
|
|
alt |
รูปแบบข้อมูลสำหรับการตอบกลับ |
|
|
callback |
ฟังก์ชัน Callback |
|
|
fields |
ตัวเลือกที่ระบุชุดย่อยของช่องที่จะรวมไว้ในการตอบกลับ |
|
|
key |
คีย์ API (ต้องระบุ) |
|
|
prettyPrint |
แสดงผลการตอบกลับพร้อมการเยื้องและขึ้นบรรทัดใหม่ |
|
|
quotaUser |
ทางเลือกแทน userIp |
|
|
userIp |
ที่อยู่ IP ของผู้ใช้ปลายทางที่กำลังทำการเรียก API |
|
เอกสารประกอบในโค้ด
เอกสาร Discovery แต่ละรายการจะมีการอธิบายประกอบด้วยdescription
ฟิลด์จำนวนหนึ่งที่
จัดทำเอกสารประกอบแบบอินไลน์สำหรับ API ฟิลด์ description
จะอยู่ในองค์ประกอบ API ต่อไปนี้
- API เอง
- ขอบเขต OAuth
- สคีมาทรัพยากร
- เมธอดของ API
- พารามิเตอร์ของเมธอด
- ค่าที่ยอมรับได้สำหรับพารามิเตอร์บางรายการ
ฟิลด์เหล่านี้มีประโยชน์อย่างยิ่งหากคุณต้องการใช้บริการการค้นพบ Google APIs เพื่อสร้างเอกสารประกอบที่มนุษย์อ่านได้สำหรับไลบรารีของไคลเอ็นต์ เช่น JavaDoc