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

การบีบอัดโดยใช้ gzip

วิธีที่ง่ายและสะดวกในการลดแบนด์วิดท์ที่จำเป็นสำหรับแต่ละคำขอคือการเปิดใช้การบีบอัด Gzip แม้ว่าการดำเนินการนี้จะต้องใช้เวลา CPU เพิ่มเติมเพื่อคลายการบีบอัดผลลัพธ์ แต่การแลกเปลี่ยนกับค่าใช้จ่ายของเครือข่ายมักจะทำให้คุ้มค่ามาก

หากต้องการรับการตอบกลับที่เข้ารหัส gzip คุณต้องทำ 2 อย่าง ได้แก่ ตั้งค่าส่วนหัว Accept-Encoding และแก้ไข User-Agent ให้มีสตริง gzip ตัวอย่างส่วนหัว HTTP ที่จัดรูปแบบอย่างถูกต้องสำหรับการเปิดใช้การบีบอัด gzip มีดังนี้

Accept-Encoding: gzip
User-Agent: my program (gzip)

การทำงานกับทรัพยากรบางส่วน

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

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

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

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