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