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

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

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

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

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

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

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

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

คําตอบบางส่วน

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

หากต้องการตอบกลับบางส่วน ให้ใช้พารามิเตอร์คําขอ fields เพื่อระบุช่องที่ต้องการส่งคืน คุณสามารถใช้พารามิเตอร์นี้กับคําขอใดๆ ที่ส่งคืนข้อมูลการตอบกลับ

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงการใช้พารามิเตอร์ fields กับ General (สมมติ) "Demo" API

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

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

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