เกริ่นนำ
เอกสารนี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการเขียนแอปพลิเคชันที่โต้ตอบกับ YouTube โดยจะอธิบายแนวคิดพื้นฐานของ YouTube และตัว API เอง นอกจากนี้ยังแสดงภาพรวมของฟังก์ชันต่างๆ ที่ API รองรับด้วย
ก่อนจะเริ่ม
-
คุณต้องมีบัญชี Google เพื่อเข้าถึงคอนโซล Google API, ขอคีย์ API และลงทะเบียนแอปพลิเคชัน
-
สร้างโปรเจ็กต์ใน Google Developers Console และรับข้อมูลเข้าสู่ระบบการให้สิทธิ์เพื่อให้แอปพลิเคชันของคุณส่งคำขอ API ได้
-
หลังจากสร้างโปรเจ็กต์แล้ว โปรดตรวจสอบว่า YouTube Data API เป็นหนึ่งในบริการที่คุณลงทะเบียนไว้เพื่อใช้งาน ดังนี้
- ไปที่คอนโซล API แล้วเลือกโครงการที่คุณเพิ่งลงทะเบียน
- ไปที่หน้า API ที่เปิดใช้ ในรายการ API ให้ตรวจสอบว่า YouTube Data API v3 มีสถานะเป็นเปิด
-
หากแอปพลิเคชันของคุณจะใช้วิธีการ API ที่ต้องใช้การอนุมัติของผู้ใช้ โปรดอ่านคู่มือการตรวจสอบ เพื่อเรียนรู้วิธีการนำการอนุมัติ OAuth 2.0 ไปใช้
-
เลือกไลบรารีไคลเอ็นต์ที่จะใช้เพื่อช่วยให้การนำ API ไปใช้สะดวกยิ่งขึ้น
-
ทำความคุ้นเคยกับแนวคิดหลักของรูปแบบข้อมูล JSON (JavaScript Object Notation) JSON คือรูปแบบข้อมูลทั่วไปที่ไม่ขึ้นอยู่กับภาษาซึ่งแสดงโครงสร้างข้อมูลที่กำหนดเองในรูปแบบข้อความธรรมดา สำหรับข้อมูลเพิ่มเติม โปรดดู json.org
ทรัพยากรและประเภททรัพยากร
ทรัพยากรคือเอนทิตีข้อมูลแต่ละรายการที่มีตัวระบุที่ไม่ซ้ำกัน ตารางด้านล่างอธิบายทรัพยากรประเภทต่างๆ ที่คุณโต้ตอบด้วยได้โดยใช้ API
แหล่งข้อมูล | |
---|---|
activity |
มีข้อมูลเกี่ยวกับการดำเนินการที่ผู้ใช้รายหนึ่งได้ดำเนินการบนเว็บไซต์ YouTube การดำเนินการของผู้ใช้ที่รายงานในฟีดกิจกรรมรวมถึงการให้คะแนนวิดีโอ การแชร์วิดีโอ การทำเครื่องหมายวิดีโอเป็นรายการโปรด การโพสต์กระดานข่าวสารของช่อง เป็นต้น |
channel |
มีข้อมูลเกี่ยวกับช่อง YouTube ช่องเดียว |
channelBanner |
ระบุ URL ที่จะใช้ตั้งค่ารูปภาพที่อัปโหลดใหม่เป็นรูปภาพแบนเนอร์สำหรับช่อง |
channelSection |
มีข้อมูลเกี่ยวกับชุดวิดีโอที่ช่องได้เลือกให้แสดง ตัวอย่างเช่น ส่วนหนึ่งอาจนำเสนอการอัปโหลดล่าสุดของช่อง การอัปโหลดที่ได้รับความนิยมสูงสุด หรือวิดีโอจากเพลย์ลิสต์อย่างน้อย 1 รายการ |
guideCategory |
ระบุหมวดหมู่ที่ YouTube เชื่อมโยงกับช่องโดยพิจารณาจากเนื้อหาหรือตัวบ่งชี้อื่นๆ เช่น ความนิยม หมวดหมู่ของคำแนะนำจะพยายามจัดระเบียบช่องในลักษณะที่ทำให้ผู้ใช้ YouTube พบเนื้อหาที่ต้องการได้ง่ายขึ้น ถึงแม้ช่องต่างๆ อาจเชื่อมโยงกับหมวดหมู่คำแนะนำตั้งแต่ 1 หมวดหมู่ขึ้นไป แต่ก็ไม่รับประกันว่าหมวดหมู่เหล่านี้จะอยู่ในหมวดหมู่ไกด์ใดๆ |
i18nLanguage |
ระบุภาษาของแอปพลิเคชันที่เว็บไซต์ YouTube รองรับ ภาษาของแอปพลิเคชันอาจเรียกว่าภาษาของ UI |
i18nRegion |
ระบุพื้นที่ทางภูมิศาสตร์ที่ผู้ใช้ YouTube สามารถเลือกเป็นภูมิภาคของเนื้อหาที่ต้องการได้ ภูมิภาคของเนื้อหาอาจเรียกว่าภาษาของเนื้อหา |
playlist |
แสดงเพลย์ลิสต์ YouTube รายการเดียว เพลย์ลิสต์คือคอลเล็กชันวิดีโอที่สามารถดูต่อเนื่องและแชร์กับผู้ใช้คนอื่นได้ |
playlistItem |
ระบุทรัพยากร เช่น วิดีโอที่เป็นส่วนหนึ่งของเพลย์ลิสต์ ทรัพยากรเพลย์ลิสต์ของเพลย์ลิสต์มีรายละเอียดที่อธิบายถึงวิธีการใช้ทรัพยากรที่รวมอยู่ในเพลย์ลิสต์ |
search result |
มีข้อมูลเกี่ยวกับวิดีโอ ช่อง หรือเพลย์ลิสต์ของ YouTube ที่ตรงกับพารามิเตอร์การค้นหาซึ่งระบุไว้ในคำขอ API แม้ว่าผลการค้นหาจะชี้ไปยังทรัพยากรที่ระบุตัวตนได้อย่างแน่ชัด เช่น วิดีโอ แต่จะไม่มีข้อมูลถาวรของตัวเอง |
subscription |
มีข้อมูลเกี่ยวกับการติดตามของผู้ใช้ YouTube การติดตามจะแจ้งผู้ใช้เมื่อมีการเพิ่มวิดีโอใหม่ลงในช่อง หรือเมื่อผู้ใช้อื่นดำเนินการอย่างใดอย่างหนึ่งบน YouTube เช่น อัปโหลดวิดีโอ ให้คะแนนวิดีโอ หรือการแสดงความคิดเห็นในวิดีโอ |
thumbnail |
ระบุภาพขนาดย่อที่เชื่อมโยงกับทรัพยากร |
video |
หมายถึงวิดีโอ YouTube รายการเดียว |
videoCategory |
ระบุหมวดหมู่ที่เกี่ยวข้องหรืออาจเชื่อมโยงกับวิดีโอที่อัปโหลด |
watermark |
ระบุรูปภาพที่แสดงระหว่างการเล่นวิดีโอของช่องที่ระบุ นอกจากนี้ เจ้าของช่องยังสามารถระบุช่องเป้าหมายที่ลิงก์กับรูปภาพ รวมถึงรายละเอียดช่วงเวลาที่ระบุเวลาที่ลายน้ำจะปรากฏระหว่างการเล่นวิดีโอและระยะเวลาที่ลายน้ำปรากฏ |
โปรดทราบว่าในหลายๆ กรณี ทรัพยากรหนึ่งๆ จะมีการอ้างอิงไปยังทรัพยากรอื่นๆ เช่น พร็อพเพอร์ตี้ snippet.resourceId.videoId
ของทรัพยากร playlistItem
จะระบุทรัพยากรวิดีโอซึ่งมีข้อมูลที่ครบถ้วนเกี่ยวกับวิดีโอ อีกตัวอย่างหนึ่งคือผลการค้นหามีพร็อพเพอร์ตี้ videoId
, playlistId
หรือ channelId
ที่ระบุทรัพยากรของวิดีโอ เพลย์ลิสต์ หรือช่องที่เฉพาะเจาะจง
การดำเนินการที่รองรับ
ตารางต่อไปนี้แสดงวิธีที่ใช้กันมากที่สุดที่ API รองรับ ทรัพยากรบางส่วนยังรองรับวิธีการอื่นๆ ที่ทำให้ฟังก์ชันเฉพาะของทรัพยากรเหล่านั้นดีขึ้นด้วย ตัวอย่างเช่น เมธอด videos.rate
จะเชื่อมโยงการให้คะแนนของผู้ใช้กับวิดีโอ ส่วนเมธอด thumbnails.set
จะอัปโหลดภาพขนาดย่อของวิดีโอไปยัง YouTube และเชื่อมโยงการให้คะแนนกับวิดีโอ
การทำงาน | |
---|---|
list |
เรียก (GET ) รายการทรัพยากร 0 รายการขึ้นไป |
insert |
สร้าง (POST ) ทรัพยากรใหม่ |
update |
แก้ไข (PUT ) ทรัพยากรที่มีอยู่เพื่อแสดงข้อมูลในคำขอของคุณ |
delete |
นำ (DELETE ) ทรัพยากรที่เฉพาะเจาะจงออก |
ปัจจุบัน API รองรับเมธอดเพื่อแสดงรายการทรัพยากรแต่ละประเภทที่รองรับ และรองรับการดำเนินการเขียนสำหรับทรัพยากรจำนวนมากด้วย
ตารางด้านล่างระบุการดำเนินการที่รองรับสำหรับทรัพยากรประเภทต่างๆ การดำเนินการที่แทรก อัปเดต หรือลบทรัพยากรจะต้องมีการให้สิทธิ์ผู้ใช้เสมอ ในบางกรณี เมธอด list
จะรองรับทั้งคำขอที่ได้รับอนุญาตและที่ไม่ได้รับอนุญาต โดยที่คำขอที่ไม่ได้รับอนุญาตจะดึงข้อมูลสาธารณะเท่านั้น ขณะที่คำขอที่ได้รับอนุญาตก็สามารถเรียกดูข้อมูลเกี่ยวกับหรือส่วนตัวของผู้ใช้ที่ตรวจสอบสิทธิ์แล้วในปัจจุบันได้เช่นกัน
การดำเนินการที่รองรับ | ||||
---|---|---|---|---|
list | insert | update | delete | |
activity |
||||
caption |
||||
channel |
||||
channelBanner |
||||
channelSection |
||||
comment |
||||
commentThread |
||||
guideCategory |
||||
i18nLanguage |
||||
i18nRegion |
||||
playlist |
||||
playlistItem |
||||
search result |
||||
subscription |
||||
thumbnail |
||||
video |
||||
videoCategory |
||||
watermark |
การใช้โควต้า
YouTube Data API ใช้โควต้าเพื่อให้แน่ใจว่านักพัฒนาแอปใช้บริการตามที่ตั้งใจไว้ และไม่สร้างแอปพลิเคชันที่ลดคุณภาพของบริการหรือจำกัดการเข้าถึงของผู้อื่นอย่างไม่เป็นธรรม คำขอ API ทั้งหมด รวมถึงคำขอที่ไม่ถูกต้อง จะมีค่าใช้จ่ายโควต้า 1 แต้มเป็นอย่างน้อย ดูโควต้าที่ใช้ได้กับแอปพลิเคชันของคุณใน API Console
โครงการที่เปิดใช้ YouTube Data API จะได้รับการจัดสรรโควต้าตามค่าเริ่มต้นที่ 10,000 หน่วยต่อวัน ซึ่งเป็นจำนวนที่เพียงพอสำหรับผู้ใช้ API ส่วนใหญ่ของเรา โควต้าเริ่มต้นซึ่งอาจมีการเปลี่ยนแปลงช่วยให้เราเพิ่มประสิทธิภาพการจัดสรรโควต้าและปรับขนาดโครงสร้างพื้นฐานได้ในลักษณะที่มีความหมายมากขึ้นสำหรับผู้ใช้ API ของเรา คุณสามารถดูการใช้งานโควต้าได้ในหน้าโควต้าในคอนโซล API
หมายเหตุ: หากใช้โควต้าถึงขีดจํากัดแล้ว คุณจะขอโควต้าเพิ่มเติมได้โดยกรอกแบบฟอร์มขอขยายโควต้าสำหรับบริการ API ของ YouTube
กำลังคำนวณการใช้โควต้า
Google จะคำนวณการใช้โควต้าโดยกำหนดค่าใช้จ่ายให้กับคำขอแต่ละรายการ การดำเนินการประเภทต่างๆ มีค่าใช้จ่ายโควต้าต่างกัน เช่น
- การดำเนินการอ่านที่ดึงรายการทรัพยากร ได้แก่ ช่อง วิดีโอ เพลย์ลิสต์ ซึ่งโดยปกติจะมีค่าใช้จ่าย 1 หน่วย
- โดยปกติแล้วการดำเนินการเขียนที่สร้าง อัปเดต หรือลบทรัพยากรจะมีค่าใช้จ่าย
50
หน่วย - คำขอการค้นหามีค่าใช้จ่าย
100
หน่วย - การอัปโหลดวิดีโอมีค่าใช้จ่าย
1600
หน่วย
ตารางต้นทุนโควต้าสำหรับคำขอ API แสดงต้นทุนโควต้าของเมธอด API แต่ละวิธี เมื่อคำนึงถึงกฎเหล่านี้แล้ว คุณจะประมาณจำนวนคำขอที่แอปพลิเคชันจะส่งได้ต่อวันโดยไม่เกินโควต้าได้
ทรัพยากรบางส่วน
API ช่วยให้สามารถเรียกทรัพยากรบางส่วนได้ และจริงๆ แล้วต้องใช้เพื่อให้แอปพลิเคชันสามารถหลีกเลี่ยงการโอน แยกวิเคราะห์ และจัดเก็บข้อมูลที่ไม่จำเป็น วิธีนี้ยังช่วยให้ API ใช้เครือข่าย, CPU และทรัพยากรหน่วยความจำอย่างมีประสิทธิภาพมากขึ้นอีกด้วย
API รองรับพารามิเตอร์คำขอ 2 รายการ ซึ่งอธิบายไว้ในส่วนต่อไปนี้ ซึ่งจะช่วยให้คุณระบุพร็อพเพอร์ตี้ทรัพยากรที่ควรรวมอยู่ในการตอบกลับของ API ได้
- พารามิเตอร์
part
จะระบุกลุ่มของพร็อพเพอร์ตี้ที่ควรแสดงผลสำหรับทรัพยากร - พารามิเตอร์
fields
จะกรองการตอบกลับของ API ให้แสดงเฉพาะพร็อพเพอร์ตี้ที่เจาะจงภายในส่วนทรัพยากรที่ขอ
วิธีใช้พารามิเตอร์ part
พารามิเตอร์ part
เป็นพารามิเตอร์ที่จําเป็นสําหรับคําขอ API ที่ดึงหรือแสดงผลทรัพยากร พารามิเตอร์จะระบุพร็อพเพอร์ตี้ของทรัพยากรระดับบนสุด (ไม่ได้ซ้อน) อย่างน้อย 1 รายการที่ควรรวมอยู่ในการตอบกลับของ API ตัวอย่างเช่น ทรัพยากร video
ประกอบด้วยส่วนต่อไปนี้
snippet
contentDetails
fileDetails
player
processingDetails
recordingDetails
statistics
status
suggestions
topicDetails
ส่วนทั้งหมดนี้เป็นออบเจ็กต์ที่มีพร็อพเพอร์ตี้ที่ซ้อนกันอยู่ คุณอาจคิดว่าออบเจ็กต์เหล่านี้เป็นกลุ่มช่องข้อมูลเมตาที่เซิร์ฟเวอร์ API อาจ (หรืออาจไม่) ดึงก็ได้ ดังนั้น พารามิเตอร์ part
จะทำให้คุณเลือกคอมโพเนนต์ทรัพยากรที่แอปพลิเคชันของคุณใช้อยู่จริง ข้อกำหนดนี้มีไว้เพื่อจุดประสงค์หลัก 2 ประการ ได้แก่
- วิธีนี้ลดเวลาในการตอบสนองโดยป้องกันไม่ให้เซิร์ฟเวอร์ API ใช้เวลาในการเรียกดูช่องข้อมูลเมตาที่แอปพลิเคชันของคุณไม่ได้ใช้งาน
- วิธีนี้ช่วยลดการใช้แบนด์วิดท์ด้วยการลด (หรือขจัด) ปริมาณข้อมูลที่ไม่จำเป็นที่แอปพลิเคชันของคุณอาจดึงกลับมา
เมื่อเวลาผ่านไป เมื่อทรัพยากรมีส่วนประกอบเพิ่มมากขึ้น ประโยชน์เหล่านี้ก็จะเพิ่มขึ้นตามไปด้วยเนื่องจากแอปพลิเคชันจะไม่ขอพร็อพเพอร์ตี้ที่เปิดตัวใหม่แต่ไม่รองรับ
วิธีใช้พารามิเตอร์ fields
พารามิเตอร์ fields
จะกรองการตอบกลับของ API ซึ่งมีเฉพาะส่วนทรัพยากรที่ระบุในค่าพารามิเตอร์ part
เพื่อให้การตอบกลับมีเฉพาะชุดช่องที่เจาะจง พารามิเตอร์ fields
ช่วยให้คุณนำพร็อพเพอร์ตี้ที่ซ้อนกันออกจากการตอบสนองของ API และลดการใช้งานแบนด์วิดท์ได้ (ใช้พารามิเตอร์ part
เพื่อกรองพร็อพเพอร์ตี้ที่ฝังจากการตอบกลับไม่ได้)
กฎต่อไปนี้อธิบายไวยากรณ์ที่รองรับสำหรับค่าพารามิเตอร์ fields
ซึ่งอิงตามไวยากรณ์ XPath แบบคร่าวๆ
- ใช้รายการที่คั่นด้วยเครื่องหมายจุลภาค (
fields=a,b
) เพื่อเลือกหลายฟิลด์ - ใช้เครื่องหมายดอกจัน (
fields=*
) เป็นไวลด์การ์ดเพื่อระบุช่องทั้งหมด - ใช้วงเล็บ (
fields=a(b,c)
) เพื่อระบุกลุ่มของพร็อพเพอร์ตี้ที่ซ้อนกันซึ่งจะรวมอยู่ในการตอบกลับของ API - ใช้เครื่องหมายทับ (
fields=a/b
) เพื่อระบุพร็อพเพอร์ตี้ที่ฝัง
ในทางปฏิบัติ กฎเหล่านี้มักจะอนุญาตให้ค่าพารามิเตอร์ fields
ที่ต่างกันหลายค่าเรียกการตอบกลับ API เดียวกันได้ เช่น หากต้องการเรียกข้อมูลรหัส ชื่อ และตำแหน่งของรายการในเพลย์ลิสต์สำหรับทุกรายการในเพลย์ลิสต์ คุณจะใช้ค่าใดก็ได้ต่อไปนี้
fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
fields=items(id,snippet/title,snippet/position)
fields=items(id,snippet(title,position))
หมายเหตุ: ค่าพารามิเตอร์ fields
ต้องเป็น URL ที่เข้ารหัส เช่นเดียวกับค่าพารามิเตอร์การค้นหาทั้งหมด ตัวอย่างในเอกสารนี้จึงไม่รวมการเข้ารหัสเพื่อให้อ่านง่ายขึ้น
ตัวอย่างคำขอบางส่วน
ตัวอย่างด้านล่างแสดงวิธีที่คุณสามารถใช้พารามิเตอร์ part
และ fields
เพื่อดูแลให้การตอบกลับของ API มีเฉพาะข้อมูลที่แอปพลิเคชันของคุณใช้เท่านั้น
- ตัวอย่างที่ 1 แสดงผลทรัพยากรวิดีโอที่มี 4 ส่วน รวมถึงพร็อพเพอร์ตี้
kind
และetag
- ตัวอย่างที่ 2 แสดงผลทรัพยากรวิดีโอที่มี 2 ส่วน รวมถึงพร็อพเพอร์ตี้
kind
และetag
- ตัวอย่างที่ 3 แสดงผลทรัพยากรวิดีโอที่มี 2 ส่วน แต่ไม่รวมพร็อพเพอร์ตี้
kind
และetag
- ตัวอย่างที่ 4 แสดงผลทรัพยากรวิดีโอที่มี 2 ส่วน แต่ไม่รวม
kind
และetag
รวมถึงพร็อพเพอร์ตี้ที่ฝังบางอย่างในออบเจ็กต์snippet
ของทรัพยากร
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status Description: This example retrieves avideo
resource and identifies several resource parts that should be included in the API response. API response:{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "contentDetails": { "duration": "PT15M51S", "aspectRatio": "RATIO_16_9" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" }, "status": { "uploadStatus": "STATUS_PROCESSED", "privacyStatus": "PRIVACY_PUBLIC" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics Description: This example modifies thepart
parameter value so that thecontentDetails
andstatus
properties are not included in the response. API response:{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics&fields=items(id,snippet,statistics) Description: This example adds thefields
parameter to remove allkind
andetag
properties from the API response. API response:{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics Description: This example modifies thefields
parameter from example 3 so that in the API response, each video resource'ssnippet
object only includes thechannelId
,title
, andcategoryId
properties. API response:{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
การเพิ่มประสิทธิภาพ
การใช้ ETag
ETags ซึ่งเป็นส่วนมาตรฐานของโปรโตคอล HTTP ช่วยให้แอปพลิเคชันอ้างถึงเวอร์ชันที่เฉพาะเจาะจงของทรัพยากร API บางอย่างได้ ทรัพยากรอาจเป็นฟีดทั้งหมดหรือรายการในฟีดนั้น ฟังก์ชันนี้รองรับกรณีการใช้งานต่อไปนี้
-
การแคชและการเรียกข้อมูลแบบมีเงื่อนไข – แอปพลิเคชันสามารถแคชทรัพยากร API และ ETag ได้ จากนั้น เมื่อแอปพลิเคชันขอทรัพยากรที่จัดเก็บไว้อีกครั้ง จะระบุ ETag ที่เชื่อมโยงกับทรัพยากรนั้น หากทรัพยากรมีการเปลี่ยนแปลง API จะส่งกลับทรัพยากรที่แก้ไขแล้วและ ETag ที่เชื่อมโยงกับทรัพยากรเวอร์ชันนั้น หากทรัพยากรไม่มีการเปลี่ยนแปลง API จะแสดงการตอบกลับ HTTP 304 (
Not Modified
) ซึ่งบ่งบอกว่าทรัพยากรไม่มีการเปลี่ยนแปลง แอปพลิเคชันของคุณสามารถลดเวลาในการตอบสนองและการใช้แบนด์วิดท์ได้โดยการแสดงทรัพยากรที่แคชในลักษณะนี้ไลบรารีของไคลเอ็นต์สำหรับ Google APIs นั้นรองรับ ETags แตกต่างกัน ตัวอย่างเช่น ไลบรารีของไคลเอ็นต์ JavaScript รองรับ ETag ผ่านรายการที่อนุญาตพิเศษสำหรับส่วนหัวของคำขอที่อนุญาตซึ่งมี
If-Match
และIf-None-Match
รายการที่อนุญาตพิเศษจะช่วยให้มีการแคชเบราว์เซอร์ตามปกติ ดังนั้นหาก ETag ของทรัพยากรไม่มีการเปลี่ยนแปลง ทรัพยากรนั้นสามารถใช้จากแคชของเบราว์เซอร์ได้ ในทางกลับกัน ไคลเอ็นต์ Obj-C ไม่รองรับ ETag -
การป้องกันการเขียนทับการเปลี่ยนแปลงโดยไม่ตั้งใจ – ETag ช่วยให้มั่นใจได้ว่าไคลเอ็นต์ API หลายไคลเอ็นต์จะไม่เขียนทับการเปลี่ยนแปลงของกันและกันโดยไม่ตั้งใจ เมื่ออัปเดตหรือลบทรัพยากร แอปพลิเคชันจะระบุ ETag ของทรัพยากรได้ หาก ETag ไม่ตรงกับเวอร์ชันล่าสุดของทรัพยากรนั้น คำขอ API จะล้มเหลว
การใช้ ETags ในแอปพลิเคชันของคุณมีประโยชน์หลายประการดังนี้
- API ตอบสนองต่อคำขอทรัพยากรที่แคชไว้แต่ไม่มีการเปลี่ยนแปลงได้รวดเร็วขึ้น ทำให้เวลาในการตอบสนองต่ำลงและใช้แบนด์วิดท์ต่ำลง
- แอปพลิเคชันของคุณจะไม่เขียนทับการเปลี่ยนแปลงทรัพยากรที่สร้างขึ้นจากไคลเอ็นต์ API อื่นโดยไม่ได้ตั้งใจ
Google APIs Client Library for JavaScript รองรับส่วนหัวของคำขอ HTTP If-Match
และ If-None-Match
จึงทำให้ ETags ทำงานได้ในบริบทของการแคชเบราว์เซอร์ตามปกติ
การใช้ gzip
นอกจากนี้คุณยังลดแบนด์วิดท์ที่ต้องใช้สำหรับการตอบสนองของ API แต่ละรายการได้ด้วยการเปิดใช้การบีบอัด gzip แม้ว่าแอปพลิเคชันของคุณจะต้องใช้เวลา CPU เพิ่มเติมเพื่อยกเลิกการบีบอัดการตอบสนองของ API แต่ประโยชน์ของการใช้ทรัพยากรเครือข่ายน้อยลงมักจะมีค่าใช้จ่ายมากกว่า
หากต้องการรับการตอบกลับที่เข้ารหัสด้วย gzip คุณต้องดำเนินการ 2 อย่างดังนี้
- ตั้งค่าส่วนหัวของคำขอ HTTP
Accept-Encoding
เป็นgzip
- แก้ไข User Agent ให้มีสตริง
gzip
ตัวอย่างส่วนหัว HTTP ด้านล่างแสดงข้อกำหนดในการเปิดใช้การบีบอัด gzip เหล่านี้
Accept-Encoding: gzip User-Agent: my program (gzip)