เคล็ดลับเพื่อเพิ่มประสิทธิภาพ

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

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงการใช้พารามิเตอร์ 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 ที่ใช้ Wrapper "data" ซึ่งการตอบกลับจะซ้อนอยู่ภายในออบเจ็กต์ data ที่มีลักษณะคล้าย data: { ... } อย่ารวม "data" ไว้ในข้อกำหนด fields การรวมออบเจ็กต์ข้อมูลที่มีข้อกำหนดฟิลด์ เช่น data/a/b จะทำให้เกิดข้อผิดพลาด แต่ให้ใช้ข้อกำหนด fields เช่น a/b แทน

• ใช้ตัวเลือกย่อยเพื่อขอชุดฟิลด์ย่อยที่เฉพาะเจาะจงของอาร์เรย์หรือออบเจ็กต์โดยวางนิพจน์ไว้ในวงเล็บ "( )"

  เช่น fields=items(id,author/email) จะแสดงเฉพาะรหัสสินค้าและอีเมลของผู้เขียนสำหรับแต่ละองค์ประกอบในอาร์เรย์สินค้า คุณยังระบุฟิลด์ย่อยเดียวได้ด้วย โดยที่ fields=items(id) จะเทียบเท่ากับ fields=items/id

• ใช้ไวลด์การ์ดในการเลือกช่อง หากจำเป็น

  เช่น fields=items/pagemap/* จะเลือกออบเจ็กต์ทั้งหมดใน Pagemap

ตัวอย่างเพิ่มเติมของการใช้พารามิเตอร์ฟิลด์

ตัวอย่างด้านล่างมีคำอธิบายว่าค่าพารามิเตอร์ fields ส่งผลต่อการตอบกลับอย่างไร

หมายเหตุ: ค่าพารามิเตอร์ fields ต้องเข้ารหัส URL เช่นเดียวกับค่าพารามิเตอร์การค้นหาทั้งหมด ตัวอย่างในเอกสารนี้จะไม่มีการเข้ารหัสเพื่อให้ง่ายต่อการอ่าน

ระบุฟิลด์ที่ต้องการให้แสดง หรือเลือกฟิลด์

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

ตัวอย่างระดับคอลเล็กชันมีดังนี้

ตัวอย่าง	เอฟเฟ็กต์
items	แสดงผลองค์ประกอบทั้งหมดในอาร์เรย์รายการ รวมถึงฟิลด์ทั้งหมดในแต่ละองค์ประกอบ แต่จะไม่แสดงฟิลด์อื่นๆ
etag,items	แสดงทั้งฟิลด์ etag และองค์ประกอบทั้งหมดในอาร์เรย์สินค้า
items/title	แสดงเฉพาะฟิลด์ title สำหรับองค์ประกอบทั้งหมดในอาร์เรย์รายการ เมื่อใดก็ตามที่มีการแสดงผลฟิลด์ที่ซ้อนกัน การตอบกลับจะรวมออบเจ็กต์หลักที่ครอบคลุม ฟิลด์ระดับบนจะไม่รวมฟิลด์ระดับล่างอื่นๆ เว้นแต่จะมีการเลือกอย่างชัดเจนด้วย
context/facets/label	แสดงเฉพาะฟิลด์ label สำหรับสมาชิกทั้งหมดของอาร์เรย์ facets ซึ่งซ้อนอยู่ภายใต้ออบเจ็กต์ context
items/pagemap/*/title	สำหรับแต่ละองค์ประกอบในอาร์เรย์รายการ จะแสดงเฉพาะฟิลด์ title (หากมี) ของออบเจ็กต์ทั้งหมดที่เป็นออบเจ็กต์ย่อยของ pagemap

ตัวอย่างระดับทรัพยากรมีดังนี้

ตัวอย่าง	เอฟเฟ็กต์
title	แสดงผลฟิลด์ title ของทรัพยากรที่ขอ
author/uri	แสดงผลuriฟิลด์ย่อยของออบเจ็กต์ author ในทรัพยากรที่ขอ
links/*/href	แสดงผลฟิลด์ href ของออบเจ็กต์ทั้งหมดที่เป็นรายการย่อยของ links

ขอเฉพาะบางส่วนของฟิลด์ที่เฉพาะเจาะจงโดยใช้การเลือกย่อย

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

ตัวอย่าง	เอฟเฟ็กต์
items(title,author/uri)	แสดงผลเฉพาะค่าของ title และ uri ของผู้เขียนสำหรับแต่ละองค์ประกอบในอาร์เรย์รายการ

การจัดการคำตอบบางส่วน

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

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

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

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

ตัวอย่าง

ตัวอย่างนี้แสดงคำขอ PATCH อย่างง่ายเพื่ออัปเดตเฉพาะชื่อของทรัพยากร 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 ร่วมกับ Patch คุณจะเพิ่มประสิทธิภาพของคำขออัปเดตได้มากยิ่งขึ้น คำขอแก้ไขจะลดขนาดของคำขอเท่านั้น คำตอบบางส่วนจะช่วยลดขนาดของคำตอบ ดังนั้นหากต้องการลดปริมาณข้อมูลที่ส่งทั้ง 2 ทาง ให้ใช้คำขอ PATCH ที่มีพารามิเตอร์ fields

ความหมายของคำขอแพตช์

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

• เพิ่ม: หากต้องการเพิ่มฟิลด์ที่ยังไม่มี ให้ระบุฟิลด์ใหม่และค่าของฟิลด์
• แก้ไข: หากต้องการเปลี่ยนค่าของช่องที่มีอยู่ ให้ระบุช่องและตั้งค่าเป็นค่าใหม่
  
• ลบ: หากต้องการลบช่อง ให้ระบุช่องและตั้งค่าเป็น null เช่น "comment": null นอกจากนี้ คุณยังลบออบเจ็กต์ทั้งหมด (หากแก้ไขได้) ได้โดยตั้งค่าเป็น null หากใช้ไลบรารีของไคลเอ็นต์ Java API ให้ใช้ Data.NULL_STRING แทน ดูรายละเอียดได้ที่ค่า Null ของ JSON

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

การใช้แพตช์ในวงจรการอ่าน-แก้ไข-เขียน

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

สร้างคำขอแก้ไขโดยตรง

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

หมายเหตุ: คุณสามารถใช้"If-Match: *"ส่วนหัว HTTP เพื่อบังคับให้แพตช์ผ่านได้เมื่อมีการใช้ ETag  หากทำเช่นนี้ คุณก็ไม่จำเป็นต้องอ่านก่อนเขียน

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

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
  }
}

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

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

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

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