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

เอกสารนี้ครอบคลุมเทคนิคบางอย่างที่คุณสามารถใช้เพื่อปรับปรุงประสิทธิภาพของแอปพลิเคชันของคุณ ในบางกรณี ตัวอย่างจาก 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 "Demo" ทั่วไป (สมมติ)

คำขอแบบง่าย: คำขอ 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 ที่ใช้ตัวห่อ "data" ซึ่งการตอบกลับนั้นฝังอยู่ภายในออบเจ็กต์ 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 คือรายการช่องที่คั่นด้วยคอมมา และมีการระบุแต่ละช่องซึ่งสัมพันธ์กับรูทของการตอบกลับ ดังนั้น หากคุณดําเนินการรายการ คำตอบจะเป็นคอลเล็กชัน และโดยทั่วไปจะมีอาร์เรย์ของทรัพยากร หากคุณกำลังดำเนินการที่ส่งคืนทรัพยากรเดียว จะมีการระบุช่องซึ่งสัมพันธ์กับทรัพยากรนั้น หากช่องที่คุณเลือกเป็น (หรือเป็นส่วนหนึ่งของ) อาร์เรย์ เซิร์ฟเวอร์จะแสดงผลองค์ประกอบทั้งหมดในอาร์เรย์ซึ่งคุณเลือกไว้

ตัวอย่างระดับคอลเล็กชันมีดังนี้
ตัวอย่าง ผลกระทบ
items แสดงผลองค์ประกอบทั้งหมดในอาร์เรย์ items ซึ่งรวมถึงช่องทั้งหมดในแต่ละองค์ประกอบ แต่ไม่มีช่องอื่นๆ
etag,items แสดงผลทั้งช่อง etag และองค์ประกอบทั้งหมดในอาร์เรย์ items
items/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 "Demo" ทั่วไป (สมมติ) ทรัพยากรยังมีความคิดเห็น ชุดของลักษณะ สถานะ และช่องอื่นๆ อีกมากมาย แต่คำขอนี้จะส่งเฉพาะช่อง 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 เพื่อให้อัปเดตทรัพยากรได้สําเร็จ หลังจากได้รับข้อมูลแล้ว คุณสามารถแก้ไขค่าที่ต้องการเปลี่ยนแปลงและส่งการนําเสนอบางส่วนที่แก้ไขแล้วกลับมาพร้อมกับคําขอการแก้ไข ต่อไปนี้คือตัวอย่างที่สมมติว่าทรัพยากร Demo ใช้ 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
...

ความแตกต่างระหว่างแพตช์กับการอัปเดต

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

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

คำขอแบบเป็นกลุ่ม

เอกสารนี้แสดงวิธีเรียก 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 รายการ ไม่ใช่ 1 รายการตามขีดจํากัดการใช้งาน ระบบจะแยกคำขอเป็นชุดคำขอก่อนดำเนินการ

รูปแบบคำขอแบบเป็นกลุ่ม

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