ปรับปรุงประสิทธิภาพ

เอกสารนี้ครอบคลุมเทคนิคบางอย่างที่คุณสามารถใช้เพื่อปรับปรุงประสิทธิภาพของแอปพลิเคชัน ในบางกรณี เราจะใช้ตัวอย่างจาก 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)
  • Patch: คำขออัปเดตที่คุณส่งเฉพาะฟิลด์ที่ต้องการเปลี่ยนแปลง (ใช้กริยา HTTP PATCH)

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการส่งคำขอแบบบางส่วนได้ในส่วนต่อไปนี้

การตอบกลับบางส่วน

โดยค่าเริ่มต้น เซิร์ฟเวอร์จะส่งการแสดงทรัพยากรแบบเต็มกลับมาหลังจากประมวลผลคำขอ เพื่อประสิทธิภาพที่ดีขึ้น คุณสามารถขอให้เซิร์ฟเวอร์ส่งเฉพาะฟิลด์ที่คุณต้องการจริงๆ และรับการตอบกลับบางส่วนแทนได้

หากต้องการขอการตอบกลับบางส่วน ให้ใช้พารามิเตอร์คำขอ fields เพื่อระบุช่องที่คุณต้องการให้แสดงผล คุณใช้พารามิเตอร์นี้กับคำขอใดก็ได้ที่แสดงข้อมูลการตอบกลับ

โปรดทราบว่าพารามิเตอร์ fields จะมีผลต่อข้อมูลการตอบกลับเท่านั้น โดยจะไม่มีผลต่อข้อมูลที่คุณต้องส่ง (หากมี) หากต้องการลดปริมาณข้อมูลที่ส่งเมื่อแก้ไขทรัพยากร ให้ใช้คำขอ patch

ตัวอย่าง

Patch (การอัปเดตบางส่วน)

นอกจากนี้ คุณยังหลีกเลี่ยงการส่งข้อมูลที่ไม่จำเป็นเมื่อแก้ไขทรัพยากรได้ด้วย หากต้องการส่งข้อมูลที่อัปเดตเฉพาะช่องที่เฉพาะเจาะจงซึ่งคุณกำลังเปลี่ยนแปลง ให้ใช้คำกริยา HTTP PATCH ความหมายของแพตช์ที่อธิบายไว้ในเอกสารนี้แตกต่าง (และง่ายกว่า) ความหมายของแพตช์สำหรับการติดตั้งใช้งาน GData แบบเก่าของการอัปเดตบางส่วน

ตัวอย่างสั้นๆ ด้านล่างแสดงให้เห็นว่าการใช้แพตช์ช่วยลดข้อมูลที่คุณต้องส่งเพื่อทำการอัปเดตเล็กๆ น้อยๆ ได้อย่างไร

ตัวอย่าง

การจัดการการตอบกลับแพตช์

หลังจากประมวลผลคำขอ PATCH ที่ถูกต้องแล้ว API จะแสดงรหัสการตอบกลับ HTTP 200 OK พร้อมกับการแสดงทรัพยากรที่แก้ไขแล้วทั้งหมด หาก API ใช้ ETag เซิร์ฟเวอร์จะอัปเดตค่า ETag เมื่อประมวลผลคำขอ PATCH สำเร็จ เช่นเดียวกับที่ทำกับ PUT

คำขอ PATCH จะแสดงการแสดงทรัพยากรทั้งหมด เว้นแต่คุณจะใช้พารามิเตอร์ fields เพื่อลดจำนวนข้อมูลที่แสดงผล

หากคำขอ PATCH ทำให้เกิดสถานะทรัพยากรใหม่ที่ไม่ถูกต้องตามไวยากรณ์หรือความหมาย เซิร์ฟเวอร์จะแสดงรหัสสถานะ 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 ครั้งในคำขอแบบกลุ่มเดียว หากจำเป็นต้องโทรมากกว่านั้น ให้ใช้คำขอแบบกลุ่มหลายรายการ

หมายเหตุ: ระบบการประมวลผลแบบกลุ่มสำหรับ Google Drive API ใช้ไวยากรณ์เดียวกับระบบการประมวลผลแบบกลุ่ม OData แต่ความหมายจะแตกต่างกัน

ข้อจำกัดเพิ่มเติมมีดังนี้

  • คำขอแบบกลุ่มที่มีการเรียกใช้มากกว่า 100 ครั้งอาจทำให้เกิดข้อผิดพลาด
  • ความยาวของ URL สำหรับคำขอภายในแต่ละรายการจำกัดไว้ที่ 8,000 อักขระ
  • Google ไดรฟ์ไม่รองรับการดำเนินการเป็นชุดสำหรับสื่อ ไม่ว่าจะเป็นการอัปโหลดหรือดาวน์โหลด หรือการส่งออกไฟล์

รายละเอียดแบทช์

คำขอแบบกลุ่มประกอบด้วยการเรียก API หลายรายการที่รวมกันเป็นคำขอ HTTP เดียว ซึ่งสามารถส่งไปยัง batchPath ที่ระบุไว้ในเอกสารการค้นพบ API เส้นทางเริ่มต้นคือ /batch/api_name/api_version ส่วนนี้จะอธิบายไวยากรณ์ของชุดคำสั่งโดยละเอียด และมีตัวอย่างในภายหลัง

หมายเหตุ: ชุดคำขอ n ที่จัดกลุ่มไว้ด้วยกันจะนับรวมในโควต้าการใช้งานเป็นคำขอ n ไม่ใช่คำขอเดียว ระบบจะแยกคำขอแบบกลุ่มออกเป็นชุดคำขอก่อนประมวลผล

รูปแบบของคำขอแบบกลุ่ม

คำขอแบบกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก Google ไดรฟ์ API หลายรายการ โดยใช้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 รายการในคำขอเดียวไม่ได้ แต่ให้ส่งการเรียกใช้รายการแรกแยกต่างหาก จากนั้นรอการตอบกลับการเรียกใช้รายการแรกก่อนที่จะส่งการเรียกใช้รายการที่ 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--

แสดงผลฟิลด์ที่เฉพาะเจาะจงจากคำขอ

หากไม่ได้ระบุพารามิเตอร์ fields เซิร์ฟเวอร์จะแสดงชุดฟิลด์เริ่มต้น ที่เฉพาะเจาะจงสำหรับเมธอด เช่น เมธอด files.list จะแสดงผลเฉพาะช่อง kind, id, name และ mimeType

ช่องเริ่มต้นที่แสดงผลอาจไม่ใช่สิ่งที่คุณต้องการ หากต้องการระบุ ช่องที่จะแสดงผลในการตอบกลับ ให้ใช้fields พารามิเตอร์ ของระบบ ดูข้อมูลเพิ่มเติมได้ที่แสดงฟิลด์ที่เฉพาะเจาะจง

สำหรับเมธอดทั้งหมดของทรัพยากร about, comments (ยกเว้น delete) และ replies (ยกเว้น delete) คุณต้องตั้งค่า fields พารามิเตอร์ วิธีการเหล่านี้จะไม่แสดงชุดฟิลด์เริ่มต้น