เอกสารนี้ครอบคลุมเทคนิคบางประการที่คุณสามารถใช้เพื่อปรับปรุงประสิทธิภาพของแอปพลิเคชันของคุณ ในบางกรณี ตัวอย่างจาก 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
ร่วมกับโปรแกรมปรับปรุง คุณสามารถเพิ่มประสิทธิภาพของคำขออัปเดตได้มากยิ่งขึ้น คำขอแพตช์จะลดขนาดคำขอเท่านั้น การตอบกลับบางส่วนจะลดขนาดการตอบกลับ ดังนั้นหากต้องการลดปริมาณข้อมูลที่ส่งไปทั้งสองทิศทาง ให้ใช้คำขอแพตช์ที่มีพารามิเตอร์ 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 จะส่งโค้ดตอบกลับ HTTP 200 OK
กลับมาพร้อมการนําเสนอทรัพยากรที่แก้ไขแล้วอย่างสมบูรณ์ หาก 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 สายต่อคำขอเป็นกลุ่ม หากต้องการให้มีการเรียกมากกว่านั้น ให้ใช้คำขอแบบกลุ่มหลายรายการ
หมายเหตุ: ระบบแบบกลุ่มสำหรับ API ของ Google ไดรฟ์จะใช้ไวยากรณ์เดียวกันกับระบบการประมวลผลแบบกลุ่มของข้อมูล OData แต่อรรถศาสตร์แตกต่างกัน
หมายเหตุ: คำขอแบบกลุ่มที่มีการเรียกใช้มากกว่า 100 ครั้งอาจทำให้เกิดข้อผิดพลาด
หมายเหตุ: มีการจำกัดความยาวของ URL สำหรับแต่ละคำขอภายใน 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
เท่านั้น ช่องเหล่านี้อาจไม่ใช่ช่องที่คุณต้องการ หากต้องการแสดงผลช่องอื่นๆ โปรดดูส่งคืนช่องข้อมูลที่เจาะจงสำหรับไฟล์