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

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

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

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

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

  เช่น fields=items/pagemap/* เลือกออบเจ็กต์ทั้งหมดในแผนที่หน้าเว็บ

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

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

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

ระบุช่องที่คุณต้องการให้แสดงผล หรือเลือกช่อง

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

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

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