ภาพรวม API ข้อมูลของ YouTube

เกริ่นนำ

เอกสารนี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการเขียนแอปพลิเคชันที่โต้ตอบกับ YouTube โดยจะอธิบายแนวคิดพื้นฐานของ YouTube และตัว API เอง นอกจากนี้ยังแสดงภาพรวมของฟังก์ชันต่างๆ ที่ API รองรับด้วย

ก่อนจะเริ่ม

1. คุณต้องมีบัญชี Google เพื่อเข้าถึงคอนโซล Google API, ขอคีย์ API และลงทะเบียนแอปพลิเคชัน

2. สร้างโปรเจ็กต์ใน Google Developers Console และรับข้อมูลเข้าสู่ระบบการให้สิทธิ์เพื่อให้แอปพลิเคชันของคุณส่งคำขอ API ได้

3. หลังจากสร้างโปรเจ็กต์แล้ว โปรดตรวจสอบว่า YouTube Data API เป็นหนึ่งในบริการที่คุณลงทะเบียนไว้เพื่อใช้งาน ดังนี้

   1. ไปที่คอนโซล API แล้วเลือกโครงการที่คุณเพิ่งลงทะเบียน
   2. ไปที่หน้า API ที่เปิดใช้ ในรายการ API ให้ตรวจสอบว่า YouTube Data API v3 มีสถานะเป็นเปิด

4. หากแอปพลิเคชันของคุณจะใช้วิธีการ API ที่ต้องใช้การอนุมัติของผู้ใช้ โปรดอ่านคู่มือการตรวจสอบ เพื่อเรียนรู้วิธีการนำการอนุมัติ OAuth 2.0 ไปใช้

5. เลือกไลบรารีไคลเอ็นต์ที่จะใช้เพื่อช่วยให้การนำ API ไปใช้สะดวกยิ่งขึ้น

6. ทำความคุ้นเคยกับแนวคิดหลักของรูปแบบข้อมูล JSON (JavaScript Object Notation) JSON คือรูปแบบข้อมูลทั่วไปที่ไม่ขึ้นอยู่กับภาษาซึ่งแสดงโครงสร้างข้อมูลที่กำหนดเองในรูปแบบข้อความธรรมดา สำหรับข้อมูลเพิ่มเติม โปรดดู json.org

ทรัพยากรและประเภททรัพยากร

ทรัพยากรคือเอนทิตีข้อมูลแต่ละรายการที่มีตัวระบุที่ไม่ซ้ำกัน ตารางด้านล่างอธิบายทรัพยากรประเภทต่างๆ ที่คุณโต้ตอบด้วยได้โดยใช้ API

โปรดทราบว่าในหลายๆ กรณี ทรัพยากรหนึ่งๆ จะมีการอ้างอิงไปยังทรัพยากรอื่นๆ เช่น พร็อพเพอร์ตี้ snippet.resourceId.videoId ของทรัพยากร playlistItem จะระบุทรัพยากรวิดีโอซึ่งมีข้อมูลที่ครบถ้วนเกี่ยวกับวิดีโอ อีกตัวอย่างหนึ่งคือผลการค้นหามีพร็อพเพอร์ตี้ videoId, playlistId หรือ channelId ที่ระบุทรัพยากรของวิดีโอ เพลย์ลิสต์ หรือช่องที่เฉพาะเจาะจง

การดำเนินการที่รองรับ

ตารางต่อไปนี้แสดงวิธีที่ใช้กันมากที่สุดที่ API รองรับ ทรัพยากรบางส่วนยังรองรับวิธีการอื่นๆ ที่ทำให้ฟังก์ชันเฉพาะของทรัพยากรเหล่านั้นดีขึ้นด้วย ตัวอย่างเช่น เมธอด videos.rate จะเชื่อมโยงการให้คะแนนของผู้ใช้กับวิดีโอ ส่วนเมธอด thumbnails.set จะอัปโหลดภาพขนาดย่อของวิดีโอไปยัง YouTube และเชื่อมโยงการให้คะแนนกับวิดีโอ

ปัจจุบัน API รองรับเมธอดเพื่อแสดงรายการทรัพยากรแต่ละประเภทที่รองรับ และรองรับการดำเนินการเขียนสำหรับทรัพยากรจำนวนมากด้วย

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

การใช้โควต้า

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. ตัวอย่างที่ 1 แสดงผลทรัพยากรวิดีโอที่มี 4 ส่วน รวมถึงพร็อพเพอร์ตี้ kind และ etag
2. ตัวอย่างที่ 2 แสดงผลทรัพยากรวิดีโอที่มี 2 ส่วน รวมถึงพร็อพเพอร์ตี้ kind และ etag
3. ตัวอย่างที่ 3 แสดงผลทรัพยากรวิดีโอที่มี 2 ส่วน แต่ไม่รวมพร็อพเพอร์ตี้ kind และ etag
4. ตัวอย่างที่ 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 a video 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 the part parameter value so that the
             contentDetails and status 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 the fields parameter to remove all
             kind and etag 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 the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId 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"
   }
  }
 ]
}

การเพิ่มประสิทธิภาพ

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