เอกสารนี้ครอบคลุมเทคนิคบางอย่างที่คุณสามารถใช้เพื่อปรับปรุงประสิทธิภาพของแอปพลิเคชันของคุณ ในบางกรณี อาจมีการใช้ตัวอย่างจาก API อื่นๆ หรือ API ทั่วไปเพื่อแสดงให้เห็นแนวคิดที่นำเสนอ แต่ Google Drive API ก็มีแนวคิดเดียวกันนี้ด้วย
การบีบอัดโดยใช้ gzip
วิธีที่ง่ายและสะดวกในการลดแบนด์วิดท์ที่ต้องใช้สำหรับแต่ละคำขอคือการเปิดใช้การบีบอัด gzip แม้ว่าวิธีนี้ต้องใช้เวลา CPU เพิ่มเติมเพื่อยกเลิกการบีบอัดผลลัพธ์ แต่การแลกกับค่าใช้จ่ายเครือข่ายมักจะคุ้มค่ามาก
หากต้องการรับการตอบกลับที่เข้ารหัส gzip คุณต้องดำเนินการ 2 อย่าง ได้แก่ ตั้งค่าส่วนหัว Accept-Encoding
และแก้ไข User Agent ให้มีสตริง gzip
ตัวอย่างส่วนหัว HTTP ที่มีรูปแบบถูกต้องสำหรับเปิดใช้การบีบอัด gzip มีดังนี้
Accept-Encoding: gzip User-Agent: my program (gzip)
การทำงานกับทรัพยากรบางส่วน
อีกวิธีหนึ่งในการปรับปรุงประสิทธิภาพการเรียก API คือการส่งและรับเฉพาะข้อมูลที่คุณสนใจเท่านั้น ซึ่งช่วยให้แอปพลิเคชันหลีกเลี่ยงการโอน แยกวิเคราะห์ และจัดเก็บช่องที่ไม่จำเป็นได้ เพื่อให้ใช้ทรัพยากรต่างๆ รวมถึงเครือข่าย, CPU และหน่วยความจำได้อย่างมีประสิทธิภาพมากขึ้น
คำขอบางส่วนมี 2 ประเภท ได้แก่
- การตอบกลับบางส่วน: คำขอที่คุณระบุช่องที่จะรวมไว้ในการตอบกลับ (ใช้พารามิเตอร์คำขอ
fields
) - แพตช์: คำขออัปเดตที่คุณส่งเฉพาะช่องที่ต้องการเปลี่ยน (ใช้คำกริยา HTTP ของ
PATCH
)
รายละเอียดเพิ่มเติมเกี่ยวกับการส่งคำขอบางส่วนจะแสดงในส่วนต่อไปนี้
คำตอบเพียงบางส่วน
โดยค่าเริ่มต้น เซิร์ฟเวอร์จะส่งการแสดงผลแบบเต็มของทรัพยากรกลับมาหลังจากประมวลผลคำขอ เพื่อประสิทธิภาพที่ดีขึ้น คุณสามารถขอให้เซิร์ฟเวอร์ส่งเฉพาะช่องที่คุณต้องการจริงๆ แล้วรับการตอบกลับบางส่วนแทน
หากต้องการขอการตอบกลับบางส่วน ให้ใช้พารามิเตอร์คำขอ fields
เพื่อระบุช่องที่คุณต้องการให้แสดงผล คุณใช้พารามิเตอร์นี้กับคำขอใดก็ได้ที่แสดงข้อมูลการตอบกลับ
โปรดทราบว่าพารามิเตอร์ fields
จะส่งผลต่อข้อมูลการตอบกลับเท่านั้น จะไม่ส่งผลต่อข้อมูลที่คุณต้องส่ง (หากมี) หากต้องการลดปริมาณข้อมูลที่คุณส่งเมื่อแก้ไขทรัพยากร ให้ใช้คำขอแพตช์
ตัวอย่าง
ตัวอย่างต่อไปนี้แสดงการใช้พารามิเตอร์ fields
กับ "การสาธิต" ทั่วไป (สมมติ) API
คำขอแบบง่าย: คำขอ HTTP GET
นี้ละเว้นพารามิเตอร์ fields
และแสดงผลทรัพยากรทั้งหมด
https://www.googleapis.com/demo/v1
การตอบกลับแบบเต็มของทรัพยากร: ข้อมูลทรัพยากรแบบเต็มจะมีช่องต่อไปนี้ พร้อมกับช่องอื่นๆ อีกหลายช่องที่มีการละไว้เพื่อความกระชับ
{ "kind": "demo", ... "items": [ { "title": "First title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }, { "title": "Second title", "comment": "Second comment.", "characteristics": { "length": "long", "accuracy": "medium" "followers": [ ], }, "status": "pending", ... }, ... ] }
คำขอการตอบกลับบางส่วน: คำขอต่อไปนี้สำหรับทรัพยากรเดียวกันนี้ใช้พารามิเตอร์ fields
เพื่อลดจำนวนข้อมูลที่ส่งคืนลงอย่างมาก
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
การตอบกลับบางส่วน: เพื่อตอบสนองคำขอข้างต้น เซิร์ฟเวอร์จะส่งการตอบกลับที่มีเฉพาะข้อมูลชนิด พร้อมด้วยอาร์เรย์รายการที่แยกวิเคราะห์ซึ่งมีเฉพาะชื่อ HTML และข้อมูลลักษณะความยาวในแต่ละรายการ
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
โปรดทราบว่าการตอบกลับจะเป็นออบเจ็กต์ JSON ที่มีเฉพาะช่องที่เลือกและออบเจ็กต์หลักที่ล้อมรอบอยู่
ต่อไปเราจะกล่าวถึงรายละเอียดวิธีจัดรูปแบบพารามิเตอร์ fields
ตามด้วยรายละเอียดเพิ่มเติมเกี่ยวกับผลลัพธ์ที่จะแสดงในคำตอบ
สรุปไวยากรณ์พารามิเตอร์ของช่อง
รูปแบบของค่าพารามิเตอร์คำขอ fields
จะอิงตามไวยากรณ์ XPath แบบคร่าวๆ ดูสรุปไวยากรณ์ที่สนับสนุนได้ที่ด้านล่าง และแสดงตัวอย่างเพิ่มเติมในส่วนต่อไปนี้
- ใช้รายการที่คั่นด้วยเครื่องหมายจุลภาคเพื่อเลือกหลายช่อง
- ใช้
a/b
เพื่อเลือกช่องb
ที่ซ้อนอยู่ภายในช่องa
ใช้a/b/c
เพื่อเลือกช่องc
ที่ฝังอยู่ในb
ข้อยกเว้น: สำหรับการตอบกลับจาก API ที่ใช้ "ข้อมูล" Wrapper ที่การตอบสนองฝังอยู่ในออบเจ็กต์
data
ที่มีลักษณะคล้ายกับdata: { ... }
ไม่ต้องรวม "data
" ในข้อกำหนดจำเพาะfields
การรวมออบเจ็กต์ข้อมูลตามข้อกำหนดของช่อง เช่นdata/a/b
จะทำให้เกิดข้อผิดพลาด แต่ให้ใช้ข้อกำหนดของfields
เช่นa/b
แทน - ใช้ตัวเลือกย่อยเพื่อขอชุดฟิลด์ย่อยของอาร์เรย์หรือวัตถุที่ระบุ โดยวางนิพจน์ในวงเล็บ "
( )
"เช่น
fields=items(id,author/email)
จะแสดงเฉพาะรหัสสินค้าและอีเมลของผู้เขียนสำหรับองค์ประกอบแต่ละรายการในอาร์เรย์ items คุณยังระบุช่องย่อยช่องเดียวได้ด้วย โดยfields=items(id)
มีค่าเท่ากับfields=items/id
- ใช้ไวลด์การ์ดในการเลือกช่อง หากจำเป็น
เช่น
fields=items/pagemap/*
เลือกออบเจ็กต์ทั้งหมดในแผนที่หน้าเว็บ
ตัวอย่างเพิ่มเติมของการใช้พารามิเตอร์ "ฟิลด์"
ตัวอย่างด้านล่างจะมีคำอธิบายว่าค่าพารามิเตอร์ fields
ส่งผลต่อการตอบกลับอย่างไร
หมายเหตุ: เช่นเดียวกับค่าพารามิเตอร์การค้นหาทั้งหมด ค่าพารามิเตอร์ fields
ต้องเป็น URL ที่เข้ารหัส ตัวอย่างในเอกสารนี้ละเว้นการเข้ารหัสเพื่อให้อ่านง่ายขึ้น
- ระบุช่องที่คุณต้องการให้แสดงผล หรือทำเลือกช่อง
- ค่าพารามิเตอร์คำขอ
fields
คือรายการช่องที่คั่นด้วยคอมมา และมีการระบุแต่ละช่องซึ่งสัมพันธ์กับรูทของการตอบกลับ ดังนั้นถ้าคุณดำเนินการ list การตอบกลับจะเป็นคอลเล็กชัน และโดยทั่วไปจะประกอบด้วยอาร์เรย์ของทรัพยากร หากคุณกำลังดำเนินการที่ส่งคืนทรัพยากรเดียว จะมีการระบุช่องซึ่งสัมพันธ์กับทรัพยากรนั้น ถ้าช่องที่คุณเลือกเป็น (หรือเป็นส่วนหนึ่งของ) อาร์เรย์ เซิร์ฟเวอร์จะส่งคืนส่วนที่เลือกขององค์ประกอบทั้งหมดในอาร์เรย์
ตัวอย่างระดับคอลเล็กชันบางส่วนมีดังนี้
ตัวอย่าง ผลกระทบ items
แสดงผลองค์ประกอบทั้งหมดในอาร์เรย์ items โดยรวมช่องทั้งหมดในแต่ละองค์ประกอบ แต่ไม่แสดงช่องอื่นๆ etag,items
แสดงผลทั้งฟิลด์ etag
และองค์ประกอบทั้งหมดในอาร์เรย์ itemsitems/title
แสดงผลเฉพาะช่อง title
สำหรับองค์ประกอบทั้งหมดในอาร์เรย์ items
เมื่อใดก็ตามที่มีการส่งคืนช่องที่ซ้อนกัน การตอบสนองจะรวมออบเจ็กต์หลักที่ล้อมรอบอยู่ ช่องหลักไม่มีช่องย่อยอื่นๆ เว้นแต่จะเลือกไว้อย่างชัดเจนcontext/facets/label
แสดงผลเฉพาะช่อง label
สำหรับสมาชิกทั้งหมดของอาร์เรย์facets
ซึ่งฝังอยู่ใต้ออบเจ็กต์context
items/pagemap/*/title
สำหรับองค์ประกอบแต่ละรายการในอาร์เรย์ items จะแสดงเฉพาะช่อง title
(หากมี) ของออบเจ็กต์ทั้งหมดที่เป็นระดับย่อยของpagemap
ตัวอย่างระดับแหล่งข้อมูลบางส่วนมีดังนี้
ตัวอย่าง ผลกระทบ title
แสดงผลฟิลด์ title
ของทรัพยากรที่ขอauthor/uri
แสดงผลฟิลด์ย่อย uri
ของออบเจ็กต์author
ในทรัพยากรที่ขอlinks/*/href
แสดงผลฟิลด์ href
ของออบเจ็กต์ทั้งหมดที่เป็นรายการย่อยของlinks
- ขอเฉพาะบางช่องโดยใช้การเลือกย่อย
- โดยค่าเริ่มต้น หากคำขอของคุณระบุช่องเฉพาะ เซิร์ฟเวอร์จะส่งกลับออบเจ็กต์หรือองค์ประกอบอาร์เรย์ทั้งหมด คุณระบุการตอบกลับที่มีเฉพาะช่องย่อยบางช่องได้ คุณดำเนินการนี้โดยใช้ "
( )
" ไวยากรณ์การเลือกย่อย ดังที่แสดงในตัวอย่างด้านล่างตัวอย่าง ผลกระทบ items(title,author/uri)
แสดงผลเฉพาะค่าของ title
และuri
ของผู้เขียนสำหรับแต่ละองค์ประกอบในอาร์เรย์ items
การจัดการคำตอบบางส่วน
หลังจากที่เซิร์ฟเวอร์ประมวลผลคำขอที่ถูกต้องซึ่งมีพารามิเตอร์การค้นหา fields
แล้ว เซิร์ฟเวอร์จะส่งรหัสสถานะ HTTP 200 OK
กลับมา พร้อมกับข้อมูลที่ขอ หากพารามิเตอร์การค้นหาของ fields
มีข้อผิดพลาดหรือไม่ถูกต้อง เซิร์ฟเวอร์จะส่งกลับรหัสสถานะ HTTP 400 Bad Request
พร้อมกับข้อความแสดงข้อผิดพลาดที่แจ้งให้ผู้ใช้ทราบความผิดพลาดในการเลือกช่อง (เช่น "Invalid field selection a/b"
)
ต่อไปนี้คือตัวอย่างคำตอบบางส่วนที่แสดงในส่วนแนะนำด้านบน คำขอใช้พารามิเตอร์ fields
เพื่อระบุช่องที่จะแสดง
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
การตอบกลับบางส่วนจะมีลักษณะดังนี้
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
หมายเหตุ: สำหรับ API ที่รองรับพารามิเตอร์การค้นหาสำหรับการแบ่งหน้าข้อมูล (เช่น maxResults
และ nextPageToken
) ให้ใช้พารามิเตอร์เหล่านั้นเพื่อลดผลลัพธ์ของการค้นหาแต่ละรายการให้เป็นขนาดที่จัดการได้ มิฉะนั้น ประสิทธิภาพจะเพิ่มขึ้นเมื่อมีการตอบสนองบางส่วน
แพตช์ (อัปเดตบางส่วน)
นอกจากนี้ คุณยังหลีกเลี่ยงการส่งข้อมูลที่ไม่จำเป็นเมื่อแก้ไขทรัพยากรได้ด้วย หากต้องการส่งข้อมูลที่อัปเดตแล้วเฉพาะสำหรับช่องที่คุณกำลังเปลี่ยนแปลงเท่านั้น ให้ใช้คำกริยา HTTP PATCH
ความหมายของแพตช์ที่อธิบายไว้ในเอกสารนี้จะแตกต่าง (และง่ายกว่า) สำหรับการติดตั้งใช้งาน GData เก่าของการอัปเดตบางส่วน
ตัวอย่างสั้นๆ ด้านล่างแสดงวิธีการใช้แพตช์ลดข้อมูลที่คุณต้องส่งเพื่อทำการอัปเดตขนาดเล็ก
ตัวอย่าง
ตัวอย่างนี้แสดงคำขอแพตช์ง่ายๆ เพื่ออัปเดตเฉพาะชื่อของ "การสาธิต" ทั่วไป (สมมติ) ทรัพยากร API ทรัพยากรยังมีความคิดเห็น ชุดของลักษณะ สถานะ และช่องอื่นๆ อีกมากมาย แต่คำขอนี้จะส่งเฉพาะช่อง title
เนื่องจากเป็นช่องเดียวที่ได้รับการแก้ไข
PATCH https://www.googleapis.com/demo/v1/324 Authorization: Bearer your_auth_token Content-Type: application/json { "title": "New title" }
คำตอบ:
200 OK
{ "title": "New title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }
เซิร์ฟเวอร์จะส่งคืนรหัสสถานะ 200 OK
พร้อมกับการแสดงทรัพยากรที่อัปเดตแล้วอย่างสมบูรณ์ เนื่องจากมีเพียงช่อง title
ที่รวมอยู่ในคำขอแพตช์ ค่านี้จึงแตกต่างจากก่อนหน้านี้
หมายเหตุ: หากใช้พารามิเตอร์ fields
การตอบสนองบางส่วน ร่วมกับแพตช์ คุณจะเพิ่มประสิทธิภาพของคำขออัปเดตได้มากขึ้นไปอีก คำขอแพตช์จะลดขนาดคำขอเท่านั้น คำตอบบางส่วนจะลดขนาดคำตอบลง ดังนั้นหากต้องการลดปริมาณข้อมูลที่ส่งในทั้ง 2 ทิศทาง ให้ใช้คำขอแพตช์ที่มีพารามิเตอร์ fields
ความหมายของคำขอแพตช์
เนื้อหาของคำขอแพตช์จะมีเฉพาะช่องทรัพยากรที่คุณต้องการแก้ไข เมื่อระบุช่อง คุณต้องรวมออบเจ็กต์หลักที่ล้อมรอบด้วยจะต้องแสดงผลออบเจ็กต์หลักที่ล้อมรอบด้วยคำตอบบางส่วน ข้อมูลที่แก้ไขแล้วที่คุณส่งจะผสานเป็นข้อมูลสำหรับออบเจ็กต์หลัก หากมี
- เพิ่ม: หากต้องการเพิ่มช่องที่ยังไม่มีในระบบ ให้ระบุช่องใหม่และค่าในช่อง
- แก้ไข: หากต้องการเปลี่ยนค่าของช่องที่มีอยู่ ให้ระบุช่องดังกล่าวและตั้งเป็นค่าใหม่
- ลบ: หากต้องการลบช่อง ให้ระบุช่องนั้นแล้วตั้งค่าเป็น
null
เช่น"comment": null
นอกจากนี้ คุณยังลบออบเจ็กต์ทั้งหมด (หากเปลี่ยนแปลงไม่ได้) โดยการตั้งค่าเป็นnull
ได้ด้วย หากคุณกำลังใช้ ไลบรารีของไคลเอ็นต์ Java API ให้ใช้Data.NULL_STRING
แทน สำหรับ โปรดดูรายละเอียดที่หัวข้อ JSON null
หมายเหตุเกี่ยวกับอาร์เรย์: คำขอแพตช์ที่มีอาร์เรย์จะแทนที่อาร์เรย์ที่มีอยู่ด้วยอาร์เรย์ที่คุณระบุ คุณไม่สามารถแก้ไข เพิ่ม หรือลบรายการในอาร์เรย์แบบเป็นส่วนๆ ได้
การใช้แพตช์ในรอบการอ่าน-แก้ไข-เขียน
วิธีนี้อาจเป็นประโยชน์หากคุณเริ่มต้นโดยการดึงข้อมูลคำตอบบางส่วนพร้อมข้อมูลที่ต้องการแก้ไข ข้อมูลนี้สำคัญอย่างยิ่งสำหรับทรัพยากรที่ใช้ ETag เนื่องจากคุณต้องระบุค่า ETag ปัจจุบันในส่วนหัว HTTP If-Match
เพื่ออัปเดตทรัพยากรให้สำเร็จ หลังจากที่ได้รับข้อมูลแล้ว คุณจะแก้ไขค่าที่ต้องการเปลี่ยนแปลงและส่งการแสดงส่วนที่แก้ไขบางส่วนกลับมาพร้อมคำขอแพตช์ได้ ตัวอย่างสมมติให้ทรัพยากรเดโมใช้ ETag
GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token
นี่คือการตอบกลับบางส่วน:
200 OK
{ "etag": "ETagString" "title": "New title" "comment": "First comment.", "characteristics": { "length": "short", "level": "5", "followers": ["Jo", "Will"], } }
คำขอแพตช์ต่อไปนี้อิงตามการตอบกลับดังกล่าว และตามที่แสดงด้านล่าง ยังใช้พารามิเตอร์ fields
เพื่อจำกัดข้อมูลที่แสดงผลในการตอบกลับแพตช์ด้วย
PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json If-Match: "ETagString"
{ "etag": "ETagString" "title": "", /* Clear the value of the title by setting it to the empty string. */ "comment": null, /* Delete the comment by replacing its value with null. */ "characteristics": { "length": "short", "level": "10", /* Modify the level value. */ "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */ "accuracy": "high" /* Add a new characteristic. */ }, }
เซิร์ฟเวอร์จะตอบสนองด้วยรหัสสถานะ HTTP 200 OK และแสดงทรัพยากรที่อัปเดตแล้วบางส่วน ดังนี้
200 OK
{ "etag": "newETagString" "title": "", /* Title is cleared; deleted comment field is missing. */ "characteristics": { "length": "short", "level": "10", /* Value is updated.*/ "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */ "accuracy": "high" /* New characteristic is present. */ } }
การสร้างคำขอแพตช์โดยตรง
สำหรับคำขอแพตช์บางรายการ คุณต้องอิงตามข้อมูลที่ดึงมาก่อนหน้านี้ เช่น หากต้องการเพิ่มรายการลงในอาร์เรย์และไม่ต้องการให้องค์ประกอบในอาร์เรย์ที่มีอยู่สูญหายไป คุณต้องรับข้อมูลที่มีอยู่ก่อน ในทํานองเดียวกัน หาก API ใช้ ETag คุณต้องส่งค่า ETag ก่อนหน้าไปกับคําขอเพื่อให้อัปเดตทรัพยากรได้สําเร็จ
หมายเหตุ: คุณใช้ส่วนหัว HTTP ของ "If-Match: *"
เพื่อบังคับให้แพตช์ผ่านได้เมื่อใช้งาน ETag หากคุณทำเช่นนี้ ก็ไม่จำเป็นต้องอ่านก่อนเขียน
อย่างไรก็ตาม สำหรับสถานการณ์อื่นๆ คุณสามารถสร้างคำขอแพตช์ได้โดยตรงโดยไม่ต้องเรียกข้อมูลที่มีอยู่ก่อน ตัวอย่างเช่น คุณสามารถสร้างคำขอแพตช์ที่อัปเดตช่องเป็นค่าใหม่หรือเพิ่มช่องใหม่ มีตัวอย่างดังต่อไปนี้
PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json { "comment": "A new comment", "characteristics": { "volume": "loud", "accuracy": null } }
เมื่อมีคำขอนี้ หากช่องความคิดเห็นมีค่าอยู่ ค่าใหม่จะเขียนทับค่าดังกล่าว ไม่เช่นนั้น จะตั้งเป็นค่าใหม่ ในทำนองเดียวกัน หากมีลักษณะด้านปริมาณ จะมีการเขียนทับค่า หากไม่มี ก็สร้างขึ้น ฟิลด์ความแม่นยำ (หากตั้งค่าไว้) จะถูกลบออก
การจัดการการตอบสนองต่อแพตช์
หลังจากประมวลผลคำขอแพตช์ที่ถูกต้องแล้ว API จะส่งคืนรหัสการตอบกลับ 200 OK
HTTP พร้อมกับการแสดงทรัพยากรที่แก้ไขอย่างสมบูรณ์ หาก API ใช้ ETag เซิร์ฟเวอร์จะอัปเดตค่า ETag เมื่อประมวลผลคำขอแพตช์เรียบร้อยแล้ว เช่นเดียวกับที่ทำกับ PUT
คำขอแพตช์จะแสดงผลการแสดงทรัพยากรทั้งหมด เว้นแต่ว่าคุณจะใช้พารามิเตอร์ fields
เพื่อลดปริมาณข้อมูลที่แสดงผล
หากคำขอแพตช์ส่งผลให้มีสถานะทรัพยากรใหม่ที่ไม่ถูกต้องตามไวยากรณ์หรือความหมาย เซิร์ฟเวอร์จะแสดงรหัสสถานะ HTTP 400 Bad Request
หรือ 422 Unprocessable Entity
และสถานะทรัพยากรจะไม่มีการเปลี่ยนแปลง เช่น หากคุณพยายามลบค่าในช่องที่ต้องกรอก เซิร์ฟเวอร์จะแสดงข้อผิดพลาด
รูปแบบสำรองเมื่อไม่รองรับคำกริยา HTTP ของ Patch
หากไฟร์วอลล์ของคุณไม่อนุญาตคำขอ HTTP PATCH
ให้ส่งคำขอ HTTP POST
และตั้งค่าส่วนหัวการลบล้างเป็น PATCH
ตามที่แสดงด้านล่าง
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
ความแตกต่างระหว่างแพตช์และการอัปเดต
ในทางปฏิบัติ เมื่อคุณส่งข้อมูลสำหรับคำขออัปเดตที่ใช้คำกริยา HTTP PUT
คุณต้องส่งเฉพาะฟิลด์ที่จำเป็นหรือไม่บังคับ หากคุณส่งค่าสำหรับช่องที่เซิร์ฟเวอร์ตั้งค่าไว้ ระบบจะไม่สนใจค่าดังกล่าว แม้ว่านี่อาจดูเป็นอีกวิธีในการอัปเดตบางส่วน แต่วิธีนี้ก็มีข้อจำกัดบางประการ การอัปเดตที่ใช้คำกริยา HTTP PUT
จะทำให้คำขอล้มเหลวหากคุณไม่ใส่พารามิเตอร์ที่จำเป็น และจะล้างข้อมูลที่ตั้งค่าไว้ก่อนหน้านี้หากไม่ได้ระบุพารามิเตอร์ที่ไม่บังคับ
การใช้แพตช์จึงปลอดภัยกว่ามาก คุณให้ข้อมูลสำหรับช่องที่ต้องการเปลี่ยนแปลงเท่านั้น ระบบจะไม่ล้างช่องที่คุณยกเว้น ข้อยกเว้นเพียงอย่างเดียวของกฎนี้จะเกิดขึ้นกับองค์ประกอบหรืออาร์เรย์ที่ซ้ำกัน: ถ้าคุณข้ามทั้งหมด องค์ประกอบหรืออาร์เรย์ทั้งหมดจะยังเหมือนเดิม หากมีผลิตภัณฑ์ใดๆ ก็ตาม ทั้งชุดจะแทนที่ด้วยชุดที่คุณให้ไว้
คำขอแบบกลุ่ม
เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API ไว้ด้วยกันเพื่อลดจำนวนการเชื่อมต่อ HTTP ให้ลูกค้ามีส่วนร่วม
เอกสารนี้เกี่ยวข้องกับการส่งคำขอแบบกลุ่มโดยส่ง คำขอ HTTP แต่หากคุณกำลังใช้ไลบรารีไคลเอ็นต์ของ Google เพื่อส่งคำขอแบบกลุ่ม โปรดดูเอกสารประกอบของไลบรารีไคลเอ็นต์
ภาพรวม
การเชื่อมต่อ HTTP แต่ละครั้งที่ไคลเอ็นต์สร้างค่าใช้จ่ายในการดำเนินการตามจำนวนที่กำหนด Google Drive API รองรับการทำงานแบบกลุ่ม เพื่อให้ไคลเอ็นต์ของคุณใส่การเรียก API หลายรายการลงในคำขอ HTTP รายการเดียวได้
ตัวอย่างสถานการณ์ที่คุณอาจต้องใช้การรวมกลุ่มมีดังนี้
- กำลังเรียกข้อมูลเมตาสำหรับไฟล์จำนวนมาก
- อัปเดตข้อมูลเมตาหรือพร็อพเพอร์ตี้หลายรายการพร้อมกัน
- การเปลี่ยนแปลงสิทธิ์สำหรับไฟล์จำนวนมาก เช่น เพิ่มผู้ใช้หรือกลุ่มใหม่
- การซิงค์ข้อมูลไคลเอ็นต์ในเครื่องเป็นครั้งแรกหรือหลังจากออฟไลน์เป็นเวลานาน
ในแต่ละกรณี คุณสามารถจัดกลุ่มการเรียกรวมกันเป็นคำขอ HTTP รายการเดียว แทนการส่งแต่ละการเรียกแยกกัน คำขอภายในทั้งหมดจะต้องไปยัง Google API เดียวกัน
ระบบจำกัดให้คุณโทรได้สูงสุด 100 ครั้งต่อคำขอแบบกลุ่ม 1 รายการ หากคุณต้องทำการเรียกมากกว่าจำนวนนั้น ให้ใช้คำขอแบบกลุ่มหลายรายการ
หมายเหตุ: ระบบแบบกลุ่มสำหรับ Google Drive API ใช้ไวยากรณ์เดียวกันกับระบบการประมวลผลแบบกลุ่ม OData แต่ความหมายแตกต่างกัน
ข้อจำกัดเพิ่มเติมมีดังนี้
- คำขอแบบกลุ่มที่มีการเรียกใช้มากกว่า 100 ครั้งอาจทำให้เกิดข้อผิดพลาดได้
- ความยาวของ URL สำหรับคำขอภายในแต่ละรายการจะมีจำนวนอักขระสูงสุด 8,000 ตัว
- Google ไดรฟ์ไม่รองรับการดำเนินการแบบกลุ่มสำหรับสื่อ ไม่ว่าจะเป็นการอัปโหลดหรือดาวน์โหลด หรือการส่งออกไฟล์
รายละเอียดกลุ่ม
คำขอแบบกลุ่มประกอบด้วยการเรียก API หลายรายการรวมกันเป็นคำขอ HTTP รายการเดียว ซึ่งจะส่งไปยัง batchPath
ที่ระบุไว้ในเอกสารการค้นพบ API ได้ เส้นทางเริ่มต้นคือ /batch/api_name/api_version
ส่วนนี้จะอธิบายไวยากรณ์แบบกลุ่มโดยละเอียด จะมีตัวอย่างในภายหลัง
หมายเหตุ: ชุดคำขอ n ที่จัดกลุ่มไว้ด้วยกันจะนับรวมในขีดจำกัดการใช้งานเป็นคำขอ n ไม่ใช่คำขอเดียว ระบบจะแยกคำขอเป็นกลุ่มออกเป็นชุดคำขอก่อนประมวลผล
รูปแบบของคำขอแบบกลุ่ม
คำขอแบบกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก API ของ Google ไดรฟ์หลายรายการ โดยใช้ประเภทเนื้อหา multipart/mixed
ภายในคำขอ HTTP หลักนั้น แต่ละส่วนจะมีคำขอ HTTP ที่ซ้อนกัน
แต่ละส่วนจะขึ้นต้นด้วยส่วนหัว HTTP Content-Type: application/http
ของตนเอง หรือใส่ส่วนหัว Content-ID
หรือไม่ก็ได้ แต่ส่วนหัวของชิ้นส่วนไว้เพื่อทำเครื่องหมายจุดเริ่มต้นของส่วนดังกล่าว คำขอเหล่านี้จะแยกจากคำขอแบบซ้อน หลังจากที่เซิร์ฟเวอร์แยกคำขอกลุ่มออกเป็นคำขอที่แยกจากกันแล้ว ระบบจะไม่สนใจส่วนหัวของส่วน
ส่วนเนื้อหาของแต่ละส่วนเป็นคำขอ HTTP ที่สมบูรณ์ โดยมีกริยา, URL, ส่วนหัว และเนื้อหาของตัวเอง คำขอ HTTP ต้องมีเฉพาะส่วนเส้นทางของ URL ไม่อนุญาตให้ใช้ URL แบบเต็มในคำขอแบบกลุ่ม
ส่วนหัว HTTP สำหรับคำขอกลุ่มภายนอก ยกเว้นส่วนหัว Content-
เช่น Content-Type
จะมีผลกับคำขอทุกรายการในกลุ่ม หากคุณระบุส่วนหัว HTTP ที่ให้ไว้ทั้งในคำขอภายนอกและการเรียกแต่ละรายการ ค่าของส่วนหัวการโทรแต่ละรายการจะลบล้างค่าของส่วนหัวของคำขอแบบกลุ่มภายนอก ส่วนหัวสำหรับการโทรแต่ละครั้งจะมีผลกับการโทรนั้นเท่านั้น
ตัวอย่างเช่น ถ้าคุณระบุส่วนหัวการให้สิทธิ์สำหรับการโทรที่ระบุ ส่วนหัวนั้นจะมีผลกับการโทรนั้นเท่านั้น ถ้าคุณระบุส่วนหัวการให้สิทธิ์สำหรับคำขอภายนอก ส่วนหัวนั้นจะใช้กับการเรียกแต่ละรายการทั้งหมด ยกเว้นในกรณีที่ลบล้างด้วยส่วนหัวการให้สิทธิ์ของตนเอง
เมื่อเซิร์ฟเวอร์ได้รับคำขอแบบกลุ่ม เซิร์ฟเวอร์จะนำพารามิเตอร์การค้นหาและส่วนหัวภายนอกของคำขอ (ตามความเหมาะสม) ไปใช้กับแต่ละส่วน จากนั้นจึงปฏิบัติต่อแต่ละส่วนเหมือนกับเป็นคำขอ HTTP ที่แยกกัน
การตอบกลับคำขอแบบกลุ่ม
การตอบกลับของเซิร์ฟเวอร์เป็นการตอบกลับ HTTP มาตรฐานรายการเดียวที่มีประเภทเนื้อหา multipart/mixed
แต่ละส่วนคือการตอบกลับหนึ่งในคำขอในคำขอแบบกลุ่ม ในลำดับเดียวกับคำขอ
การตอบสนองแต่ละส่วนมีการตอบสนอง HTTP ที่สมบูรณ์รวมถึงรหัสสถานะ ส่วนหัว และเนื้อหา เช่นเดียวกับส่วนต่างๆ ในคำขอ ส่วนการตอบสนองแต่ละส่วนจะมีส่วนหัว Content-Type
ซึ่งทำเครื่องหมายจุดเริ่มต้นของส่วนดังกล่าวอยู่เช่นเดียวกับส่วนต่างๆ ในคำขอ
หากส่วนที่กำหนดของคำขอมีส่วนหัว Content-ID
ส่วนที่เกี่ยวข้องของการตอบกลับจะมีส่วนหัว Content-ID
ที่ตรงกัน โดยมีค่าเดิมนำหน้าด้วยสตริง response-
ดังที่แสดงในตัวอย่างต่อไปนี้
หมายเหตุ: เซิร์ฟเวอร์อาจดำเนินการเรียกคุณโดยไม่เรียงตามลำดับ อย่าคาดหวังว่าจะมีการดำเนินการตามลำดับที่คุณกำหนด หากต้องการแน่ใจว่ามีการเรียก 2 ครั้งตามลำดับที่ระบุ คุณไม่สามารถส่งคำขอเดียวได้ ให้ส่งข้อความแรกไปด้วยตัวเอง แล้วรอให้ลูกค้าตอบกลับถึงข้อความแรกก่อนที่จะส่งจดหมายฉบับที่ 2
ตัวอย่าง
ตัวอย่างต่อไปนี้แสดงการใช้งานการจัดกลุ่มกับ Google Drive API
ตัวอย่างคำขอแบบกลุ่ม
POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8
{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8
{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--
ตัวอย่างการตอบกลับเป็นกลุ่ม
นี่คือการตอบกลับคำขอตัวอย่างในส่วนก่อนหน้า
HTTP/1.1 200 OK Alt-Svc: quic=":443"; p="1"; ma=604800 Server: GSE Alternate-Protocol: 443:quic,p=1 X-Frame-Options: SAMEORIGIN Content-Encoding: gzip X-XSS-Protection: 1; mode=block Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk Transfer-Encoding: chunked X-Content-Type-Options: nosniff Date: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Vary: X-Origin Vary: Origin Expires: Fri, 13 Nov 2015 19:28:59 GMT--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "12218244892818058021i" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "04109509152946699072k" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk--
แสดงข้อมูลบางช่องจากคำขอ
โดยค่าเริ่มต้น เซิร์ฟเวอร์จะส่งคืนชุดฟิลด์ทรัพยากรเริ่มต้นซึ่งใช้เฉพาะสำหรับ
ที่ใช้ได้อีกด้วย ตัวอย่างเช่น พารามิเตอร์
เมธอด files.list
อาจแสดงผลเฉพาะ
id
, name
และ mimeType
ช่องเหล่านี้อาจไม่ใช่ช่องที่คุณ
ความต้องการ หากต้องการแสดงผลช่องอื่นๆ โปรดดูที่
ส่งคืนช่องเฉพาะสำหรับไฟล์