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

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

หมายเหตุเกี่ยวกับอาร์เรย์: คำขอการแก้ไขที่มีอาร์เรย์จะแทนที่อาร์เรย์ที่มีอยู่ด้วยอาร์เรย์ที่คุณระบุ คุณไม่สามารถแก้ไข เพิ่ม หรือลบรายการในอาร์เรย์ทีละรายการ

การใช้แพตช์ในวงจร read-modify-write

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

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

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

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

รายละเอียดการประมวลผลเป็นกลุ่ม

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

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

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

คำขอกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียกใช้ Google Drive API หลายรายการโดยใช้ประเภทเนื้อหา multipart/mixed ภายในคําขอ HTTP หลักนั้น แต่ละส่วนจะมีคําขอ HTTP ที่ฝังอยู่

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