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

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

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