เอกสารนี้อธิบายเทคนิคบางประการที่คุณสามารถใช้เพื่อปรับปรุงประสิทธิภาพของแอปพลิเคชันของคุณ ในบางกรณี ตัวอย่างจาก API อื่นๆ หรือ API ทั่วไปจะใช้เพื่อแสดงให้เห็นภาพของแนวคิดที่นำเสนอ แต่ Google Photos Library 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)
จะแสดงเฉพาะรหัสรายการและอีเมลผู้เขียนสำหรับแต่ละองค์ประกอบในอาร์เรย์ items หรือจะระบุช่องย่อยช่องเดียวก็ได้ โดยที่fields=items(id)
เทียบเท่ากับfields=items/id
- ใช้ไวลด์การ์ดในการเลือกช่อง หากจำเป็น
เช่น
fields=items/pagemap/*
เลือกออบเจ็กต์ทั้งหมดใน Pagemap
ตัวอย่างเพิ่มเติมเกี่ยวกับการใช้พารามิเตอร์ฟิลด์
ตัวอย่างด้านล่างมีคำอธิบายว่าค่าพารามิเตอร์ fields
ส่งผลต่อการตอบกลับอย่างไร
หมายเหตุ: ค่าพารามิเตอร์การค้นหา fields
ต้องเป็น URL ที่เข้ารหัส เช่นเดียวกับค่าพารามิเตอร์การค้นหาทั้งหมด ตัวอย่างในเอกสารนี้จะละเว้นการเข้ารหัสเพื่อให้อ่านง่ายขึ้น
- ระบุช่องที่คุณต้องการให้แสดงผล หรือเลือกช่อง
- ค่าพารามิเตอร์ของคำขอ
fields
เป็นรายการที่คั่นด้วยคอมมา และระบุแต่ละช่องโดยสัมพันธ์กับรูทของการตอบกลับ ดังนั้น หากคุณกําลังดําเนินการรายการ คําตอบจะเป็นคอลเล็กชัน และโดยทั่วไปจะมีอาร์เรย์ทรัพยากร หากคุณกำลังดำเนินการที่แสดงผลทรัพยากรเดียว ระบบจะระบุฟิลด์ให้สัมพันธ์กับทรัพยากรนั้น หากช่องที่คุณเลือกคือ (หรือเป็นส่วนหนึ่งของ) อาร์เรย์ เซิร์ฟเวอร์จะแสดงผลส่วนที่เลือกขององค์ประกอบทั้งหมดในอาร์เรย์
ตัวอย่างระดับคอลเล็กชันบางส่วนมีดังนี้
ตัวอย่าง ผลกระทบ items
แสดงผลองค์ประกอบทั้งหมดในอาร์เรย์ items รวมถึงช่องทั้งหมดในแต่ละองค์ประกอบ แต่ไม่รวมช่องอื่นๆ etag,items
แสดงผลทั้งช่อง etag
และองค์ประกอบทั้งหมดในอาร์เรย์ itemsitems/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
) ให้ใช้พารามิเตอร์เหล่านั้นเพื่อลดผลลัพธ์ของการค้นหาแต่ละรายการให้เป็นขนาดที่จัดการได้ มิฉะนั้น ประสิทธิภาพที่ได้รับอาจเพิ่มขึ้นจากการตอบสนองบางส่วนอาจไม่รับรู้