บทนำ
เอกสารนี้มีไว้สําหรับนักพัฒนาซอฟต์แวร์ที่ต้องการเขียนไลบรารีของไคลเอ็นต์ ปลั๊กอิน IDE และเครื่องมืออื่นๆ สําหรับการโต้ตอบกับ Google API บริการ Discovery ของ Google APIs ช่วยให้คุณดําเนินการทั้งหมดข้างต้นได้ โดยแสดงข้อมูลเมตาที่เครื่องอ่านได้เกี่ยวกับ Google API อื่นๆ ผ่าน API แบบง่าย คู่มือนี้จะอธิบายภาพรวมของแต่ละส่วนของเอกสาร Discovery รวมถึงเคล็ดลับที่เป็นประโยชน์เกี่ยวกับวิธีใช้เอกสาร
การเรียก API ทั้งหมดเป็นคําขอที่ไม่ได้ตรวจสอบสิทธิ์, รูปแบบ JSON และ REST ที่ใช้ SSL กล่าวคือ URL จะเริ่มต้นด้วย https
หากคุณไม่คุ้นเคยกับแนวคิดบริการ Discovery ของ Google APIs คุณควรอ่านการเริ่มต้นใช้งานก่อนเริ่มต้นโค้ด
รูปแบบเอกสารการค้นพบ
ส่วนนี้จะแสดงภาพรวมของเอกสาร Discovery
ตัวอย่างทั้งหมดด้านล่างใช้เอกสาร Discovery จาก Google Cloud Service Management API คุณสามารถโหลดเอกสารการค้นพบสําหรับ Google Cloud Service Management API โดยดําเนินการตามคําขอ GET นี้
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1รูปแบบของเอกสารการค้นพบมีข้อมูลที่จัดอยู่ใน 6 หมวดหมู่หลัก ได้แก่
- คําอธิบายพื้นฐานของ API
- ข้อมูลการตรวจสอบสิทธิ์สําหรับ API
- รายละเอียดทรัพยากรและสคีมาที่อธิบายข้อมูลของ API'
- รายละเอียดเกี่ยวกับเมธอด API'
- ข้อมูลเกี่ยวกับฟีเจอร์ที่กําหนดเองซึ่ง API รองรับ
- เอกสารประกอบในบรรทัดที่อธิบายองค์ประกอบหลักของ API
เนื้อหาในเอกสารการค้นพบแต่ละส่วนจะอธิบายไว้ด้านล่าง ดูรายละเอียดเพิ่มเติมเกี่ยวกับพร็อพเพอร์ตี้แต่ละรายการได้ในเอกสารอ้างอิง
คําอธิบาย API พื้นฐาน
เอกสารการค้นพบมีชุดพร็อพเพอร์ตี้เฉพาะสําหรับ API ดังนี้
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
พร็อพเพอร์ตี้ระดับ API เหล่านี้ประกอบด้วยรายละเอียดเกี่ยวกับ API เวอร์ชันหนึ่งๆ เช่น name, version, title และ description protocol จะมีค่าคงที่ rest เสมอ เนื่องจากบริการ Discovery API รองรับเมธอด RESTful ในการเข้าถึง API เท่านั้น
ช่อง servicePath ระบุคํานําหน้าเส้นทางสําหรับ API เวอร์ชันนี้
การตรวจสอบสิทธิ์
ส่วน auth จะมีรายละเอียดเกี่ยวกับขอบเขตการตรวจสอบสิทธิ์ OAuth 2.0 สําหรับ API หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้ขอบเขตกับ OAuth 2.0 โปรดไปที่การใช้ OAuth 2.0 เพื่อเข้าถึง Google API
ส่วน auth มีส่วน oauth2 และ scopes ที่ฝังไว้ ส่วน scopes คือการแมปคีย์/ค่าจากค่าขอบเขตเพื่อดูรายละเอียดเพิ่มเติมเกี่ยวกับขอบเขต
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/cloud-platform.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management": {
"description": "Manage your Google API service configuration"
}
}
}
}
ส่วน auth จะกําหนดขอบเขตของ API หนึ่งๆ เท่านั้น หากต้องการดูว่าขอบเขตเหล่านี้เชื่อมโยงกับเมธอด API อย่างไร ให้ดูส่วนเมธอดด้านล่าง
ทรัพยากรและสคีมา
การดําเนินการของ API' ดําเนินการกับออบเจ็กต์ข้อมูลที่เรียกว่า resources เอกสาร Discovery สร้างขึ้นจากแนวคิดของทรัพยากร เอกสารการค้นพบแต่ละรายการจะมีส่วนระดับบนสุด resources ที่จัดกลุ่มทรัพยากรทั้งหมดที่เชื่อมโยงกับ API ตัวอย่างเช่น Google Cloud Service Management API มีทรัพยากร services และมีทรัพยากร operations ภายใต้โดเมนระดับบนสุด resources, ทรัพยากร services มีทรัพยากรย่อย 3 รายการ ได้แก่ configs, rollouts และ consumers
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
ภายในทรัพยากรแต่ละรายการจะมีเมธอดที่เชื่อมโยงกับทรัพยากรนั้นๆ เช่น Google Cloud Service Management API มี 3 วิธีที่เชื่อมโยงกับทรัพยากร services.rollouts ได้แก่ get, list และ create
สคีมาจะบอกคุณว่าทรัพยากรใน API มีลักษณะอย่างไร เอกสารการค้นพบแต่ละรายการจะมีส่วน schemas ระดับบนสุด ซึ่งมีคู่ของชื่อ/ค่าของรหัสสคีมากับออบเจ็กต์ รหัสสคีมาจะไม่ซ้ํากันต่อ API และจะใช้เพื่อระบุสคีมาในส่วน methods ของเอกสาร Discovery อย่างไม่ซ้ํากัน
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
บริการ Discovery API ใช้ ฉบับร่างของสคีมา JSON-03 สําหรับการนําเสนอสคีมา ตัวอย่างข้อมูลของสคีมา JSON สําหรับทรัพยากร URL รวมถึงทรัพยากรการตอบกลับจริงมีดังนี้
| สคีมา JSON ของทรัพยากรการเปิดตัว: | การตอบสนองจริงของการเปิดตัวทรัพยากร: |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
}
|
{
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
}
|
ช่องที่เป็นตัวหนาจะแสดงการจับคู่ระหว่างสคีมา JSON และการตอบกลับจริง
สคีมาอาจมีการอ้างอิงไปยังสคีมาอื่นๆ ด้วย หากคุณกําลังสร้างไลบรารีของไคลเอ็นต์ ซึ่งจะช่วยให้คุณจําลองออบเจ็กต์ของ API อย่างมีประสิทธิภาพในชั้นเรียนโมเดลข้อมูล ในตัวอย่าง Rollout ด้านบน อันที่จริง trafficPercentStrategy เป็นการอ้างอิงถึงสคีมาที่มีรหัส TrafficPercentStrategy หากดูที่ส่วน schemas คุณจะเห็นสคีมา TrafficPercentStrategy สามารถใช้สคีมานี้แทนพร็อพเพอร์ตี้ trafficPercentStrategy ในทรัพยากร Rollout ได้ (โปรดทราบว่าไวยากรณ์ $ref มาจากข้อกําหนดของสคีมา JSON)
นอกจากนี้ เมธอดอาจอ้างอิงสคีมาเมื่อระบุเนื้อหาของคําขอและการตอบสนอง ดูรายละเอียดเพิ่มเติมได้ที่ส่วนเมธอด
เมธอด
หัวใจหลักของเอกสารการค้นพบนั้นสร้างขึ้นจากวิธีการต่างๆ เมธอดคือการดําเนินการที่ดําเนินการกับ 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 แต่ละรายการเป็นการแมปคีย์/ค่าจากชื่อเมธอดไปยังรายละเอียดอื่นๆ เกี่ยวกับเมธอด ตัวอย่างด้านล่างแสดงเอกสาร 3 วิธี ได้แก่ get, list และ create
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
สุดท้าย แต่ละส่วนของเมธอดจะแสดงรายละเอียดพร็อพเพอร์ตี้ต่างๆ เกี่ยวกับวิธีการดังกล่าว ตัวอย่างของเมธอด get มีดังนี้
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
ส่วนนี้มีรายละเอียดวิธีการทั่วไป เช่น ID ที่ไม่ซ้ํากันสําหรับระบุเมธอด httpMethod ที่จะใช้ และ path ของเมธอด (สําหรับรายละเอียดเกี่ยวกับวิธีใช้พร็อพเพอร์ตี้ path เพื่อคํานวณ URL เมธอดแบบเต็ม โปรดดูส่วนเขียนคําขอ) นอกเหนือจากพร็อพเพอร์ตี้วิธีการทั่วไปเหล่านี้แล้ว ยังมีพร็อพเพอร์ตี้บางรายการที่เชื่อมต่อกับเมธอดดังกล่าวกับส่วนอื่นๆ ในเอกสาร Discovery
กล้องติดปืน
ส่วน auth ที่กําหนดไว้ก่อนหน้านี้ในเอกสารประกอบนี้มีข้อมูลเกี่ยวกับขอบเขตทั้งหมดที่ API หนึ่งๆ รองรับ หากเมธอดรองรับหนึ่งในขอบเขตเหล่านี้ ก็จะมีอาร์เรย์ขอบเขต มีรายการนี้ในอาร์เรย์นี้สําหรับขอบเขตแต่ละรายการที่เมธอดรองรับ เช่น ส่วน scopes ของเมธอด Google Cloud Service Management API get มีลักษณะดังนี้
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
โปรดทราบว่าการเลือกขอบเขตการตรวจสอบสิทธิ์ที่จะใช้ในแอปพลิเคชันขึ้นอยู่กับหลายปัจจัย เช่น เมธอดที่เรียกใช้และพารามิเตอร์ที่ส่งไปพร้อมกับเมธอด ดังนั้น นักพัฒนาซอฟต์แวร์จึงตัดสินใจว่าจะกําหนดขอบเขตใดในขอบเขตนี้ Discovery จะเก็บเฉพาะเอกสารที่มีขอบเขตที่ใช้ได้กับเมธอด
คําขอและการตอบกลับ
หากเมธอดมีเนื้อหาของคําขอหรือการตอบกลับ เอกสารเหล่านี้จะระบุไว้ในส่วน request หรือ response ตามลําดับ ในตัวอย่าง get ข้างต้น เมธอดจะมีเนื้อหาของ response:
"response": {
"$ref": "Rollout"
}
ไวยากรณ์ด้านบนแสดงให้เห็นว่าเนื้อหาการตอบกลับกําหนดโดยสคีมา JSON ที่มีรหัส Rollout โดยสคีมานี้จะปรากฏในส่วนสคีมาระดับบนสุด ทั้งเนื้อหาคําขอและเนื้อหาการตอบกลับจะใช้ไวยากรณ์ $ref เพื่ออ้างอิงสคีมา
พารามิเตอร์
หากวิธีการมีพารามิเตอร์ที่ผู้ใช้ควรระบุไว้ พารามิเตอร์เหล่านี้จะระบุไว้ในส่วน parameters ระดับเมธอด ส่วนนี้ประกอบด้วยการจับคู่คีย์/ค่าของชื่อพารามิเตอร์เพื่อดูรายละเอียดเพิ่มเติมเกี่ยวกับพารามิเตอร์นั้น:
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
ในตัวอย่างข้างต้น มี 2 พารามิเตอร์สําหรับเมธอด get ได้แก่ serviceName และ rolloutId พารามิเตอร์อาจอยู่ใน path หรือ URL query โดยพร็อพเพอร์ตี้ location จะระบุตําแหน่งที่ไลบรารีของไคลเอ็นต์ควรวางพารามิเตอร์
มีพร็อพเพอร์ตี้อื่นๆ มากมายที่อธิบายถึงพารามิเตอร์ รวมถึงข้อมูลพารามิเตอร์ type (มีประโยชน์สําหรับภาษาที่พิมพ์อย่างยิ่ง) ระบุว่าพารามิเตอร์คือ required หรือไม่ และพารามิเตอร์เป็น enum หรือไม่ ดูคู่มืออ้างอิงสําหรับรายละเอียดเพิ่มเติมเกี่ยวกับพร็อพเพอร์ตี้
ลําดับพารามิเตอร์
ไลบรารีของไคลเอ็นต์จะจัดโครงสร้างอินเทอร์เฟซของตัวเองได้หลายวิธี วิธีหนึ่งคือการใช้เมธอดกับพารามิเตอร์ API แต่ละรายการในลายเซ็นของเมธอด อย่างไรก็ตาม เนื่องจาก JSON เป็นรูปแบบที่ไม่ได้เรียงลําดับ การเรียงลําดับพารามิเตอร์ในลายเซ็นของเมธอดจึงเป็นเรื่องยาก อาร์เรย์ parameterOrder มีพารามิเตอร์คงที่สําหรับลําดับการส่งคําขอ อาร์เรย์จะแสดงชื่อของพารามิเตอร์แต่ละรายการตามความสําคัญ โดยอาจมีได้ทั้งเส้นทางหรือพารามิเตอร์การค้นหา แต่พารามิเตอร์ทุกตัวในอาร์เรย์จะต้องระบุ ในตัวอย่างข้างต้น ลายเซ็นของเมธอด Java อาจมีลักษณะเช่นนี้
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);ค่าแรกในอาร์เรย์ parameterOrder serviceName เป็นองค์ประกอบแรกในลายเซ็นของเมธอดด้วย หากมีพารามิเตอร์อื่นๆ ในอาร์เรย์ parameterOrder พารามิเตอร์เหล่านั้นจะอยู่หลังพารามิเตอร์ serviceName เนื่องจากอาร์เรย์ parameterOrder มีเฉพาะพารามิเตอร์ที่จําเป็นเท่านั้น แนวทางปฏิบัติที่ดีจึงเป็นการรวมวิธีระบุพารามิเตอร์ที่ไม่บังคับให้กับผู้ใช้ด้วย ตัวอย่างข้างต้นทํากับแผนที่ optionalParameters
อัปโหลดสื่อ
หากวิธีการรองรับการอัปโหลดสื่อ เช่น รูปภาพ เสียง หรือวิดีโอ ระบบจะบันทึกตําแหน่งและโปรโตคอลที่รองรับการอัปโหลดสื่อนั้นในส่วน 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 คือรายการช่วงสื่อที่กําหนดประเภท MIME ที่สามารถอัปโหลดได้ ปลายทางที่แสดงในตัวอย่างข้างต้นจะยอมรับรูปภาพทุกรูปแบบ
พร็อพเพอร์ตี้ maxSize มีขนาดสูงสุดของการอัปโหลด ค่าเป็นสตริงในหน่วย MB, GB หรือ TB ในตัวอย่างข้างต้น การอัปโหลดต้องมีขนาดไม่เกิน 10 MB โปรดทราบว่าค่านี้ไม่ใช่โควต้าพื้นที่เก็บข้อมูลของผู้ใช้แต่ละคนสําหรับ API นั้น ดังนั้นแม้ว่าการอัปโหลดจะมีค่าน้อยกว่า maxSize แต่ไลบรารีของไคลเอ็นต์ก็ควรมีความพร้อมในการจัดการการอัปโหลดที่ไม่สําเร็จเนื่องจากพื้นที่ไม่เพียงพอ
ส่วน protocols จะแสดงโปรโตคอลการอัปโหลดที่เมธอดรองรับ โปรโตคอล simple แค่โพสต์สื่อไปยังปลายทางหนึ่งๆ ในคําขอ HTTP รายการเดียว โปรโตคอล resumable หมายความว่าปลายทางที่ระบุไว้ใน URI ของ path รองรับโปรโตคอลการอัปโหลดที่ดําเนินการต่อได้ หากพร็อพเพอร์ตี้ 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 จะเป็นเท็จ
พารามิเตอร์ทั่วไป
เอกสารการค้นพบระดับบนสุดมีพร็อพเพอร์ตี้ parameters ส่วนนี้จะคล้ายกับส่วนพารามิเตอร์ของเมธอดแต่ละวิธี แต่พารามิเตอร์เหล่านี้จะมีผลกับเมธอดใดก็ได้ใน API
ตัวอย่างเช่น เมธอด get, insert หรือ แสดงรายการของ Google Cloud Service Management API จะมีพารามิเตอร์ prettyPrint ในพารามิเตอร์คําขอ เพื่อจัดรูปแบบการตอบกลับสําหรับเมธอดเหล่านั้นทั้งหมดในรูปแบบที่มนุษย์อ่านได้ รายการพารามิเตอร์ทั่วไปมีดังนี้
| พารามิเตอร์ | ความหมาย | หมายเหตุ | ประโยชน์ต่อการให้บริการ |
|---|---|---|---|
access_token |
โทเค็น OAuth 2.0 สําหรับผู้ใช้ปัจจุบัน |
|
|
alt |
รูปแบบข้อมูลสําหรับคําตอบ |
|
|
callback |
ฟังก์ชันเรียกกลับ |
| |
fields |
ตัวเลือกที่ระบุชุดย่อยของช่องที่จะรวมไว้ในคําตอบ |
|
|
key |
คีย์ API (ต้องระบุ*) |
|
|
prettyPrint |
แสดงผลการตอบสนองที่ระบุข้อมูลประจําตัวและการขึ้นบรรทัดใหม่ |
|
|
quotaUser |
ตัวเลือกอื่นๆ สําหรับ userIp |
|
|
userIp |
ที่อยู่ IP ของผู้ใช้ปลายทางที่มีการเรียก API |
|
ฟีเจอร์
ในบางกรณี API จะรองรับฟีเจอร์ที่กําหนดเองที่อยู่นอกเหนือขอบเขตอื่นๆ ของเอกสาร Discovery ซึ่งรวบรวมในอาร์เรย์ features อาร์เรย์ฟีเจอร์มีป้ายกํากับสตริงสําหรับฟีเจอร์พิเศษแต่ละรายการที่ API รองรับ ปัจจุบัน dataWrapper เป็นฟีเจอร์เดียวที่รองรับ แต่เราอาจรองรับฟีเจอร์อื่นๆ ในอนาคต
"features": dataWrapper
ฟีเจอร์ dataWrapper ระบุว่าคําขอและการตอบกลับทั้งหมดจาก API รวมอยู่ในออบเจ็กต์ JSON ของ data ฟีเจอร์นี้เป็น API เก่าของ Google แต่เลิกใช้งานไปแล้ว API ต่อไปนี้รองรับฟีเจอร์ dataWrapper: โมเดอเรเตอร์ v1 และ แปลภาษา v2
ในฐานะนักพัฒนาไลบรารีของไคลเอ็นต์ หาก API รองรับฟีเจอร์ "dataWrapper" คุณควรทําดังนี้
- ในคําขอ: รวมทรัพยากรคําขอในออบเจ็กต์ JSON
data - ในการตอบกลับ: ค้นหาทรัพยากรภายในออบเจ็กต์ JSON
data
สคีมาในเอกสาร Discovery ไม่มี Wrapper ข้อมูล คุณจึงต้องเพิ่มและนําสคีมาออกอย่างชัดเจน ตัวอย่างเช่น สมมติว่ามี API ที่มีทรัพยากรชื่อ "Foo" ซึ่งมีลักษณะดังนี้
{
"id": 1,
"foo": "bar"
}
ก่อนที่จะแทรกทรัพยากรนี้โดยใช้ API คุณจะต้องรวมแหล่งข้อมูลนี้ในองค์ประกอบข้อมูล
{
"data": {
"id": 1,
"foo": "bar"
}
}
ในทางกลับกัน เมื่อคุณได้รับการตอบกลับจาก API ก็จะมี Wrapper ข้อมูลดังนี้
{
"data": {
"id": 1,
"foo": "bar"
}
}
หากต้องการให้ทรัพยากรกําหนดโดยสคีมา คุณต้องนํา Wrapper ข้อมูลออกโดยทําดังนี้
{
"id": 1,
"foo": "bar"
}
เอกสารในบรรทัด
เอกสารการค้นพบแต่ละรายการจะมีคําอธิบายประกอบด้วยช่อง description จํานวนช่องที่ระบุเอกสารแทรกในบรรทัดสําหรับ API ช่อง description มีไว้สําหรับองค์ประกอบ API ต่อไปนี้
- API เอง
- ขอบเขต OAuth
- สคีมาของทรัพยากร
- เมธอดของ API
- พารามิเตอร์เมธอด
- ค่าที่ยอมรับสําหรับพารามิเตอร์บางรายการ
ช่องเหล่านี้มีประโยชน์อย่างยิ่งในกรณีที่คุณต้องการใช้บริการการค้นพบของ Google API เพื่อสร้างเอกสารประกอบที่มนุษย์อ่านได้ในไลบรารีของไคลเอ็นต์ เช่น JavaDoc