ภาพรวม 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 หน่วย
• การอัปโหลดวิดีโอมีค่าใช้จ่าย 100 หน่วย

ตารางค่าใช้จ่ายโควต้าสำหรับคำขอ 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)