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

บทนำ

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

ก่อนจะเริ่มต้น

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

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

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

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

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

5. เลือกไลบรารีของไคลเอ็นต์เพื่อลดความซับซ้อนในการติดตั้งใช้งาน API

6. ทำความคุ้นเคยกับแนวคิดหลักของรูปแบบข้อมูล JSON (ออบเจ็กต์ JavaScript 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 จะมีการจัดสรรโควต้าเริ่มต้นเป็น search.list การเรียกใช้ 100 ครั้ง, videos.insert การเรียกใช้ 100 ครั้ง และ 10,000 หน่วยต่อวันรวมกันสำหรับปลายทางอื่นๆ ทั้งหมด โควต้าเริ่มต้นซึ่งอาจมีการเปลี่ยนแปลงช่วยให้เราเพิ่มประสิทธิภาพการจัดสรรโควต้าและปรับขนาดโครงสร้างพื้นฐานในลักษณะที่มีความหมายต่อผู้ใช้ API มากขึ้น คุณดูการใช้งานโควต้าได้ในหน้าโควต้าในคอนโซล API

หมายเหตุ: หากถึงขีดจำกัดโควต้าแล้ว คุณสามารถขอโควต้าเพิ่มเติมได้โดยกรอกแบบฟอร์มคำขอขยายโควต้าสำหรับบริการ API ของ YouTube

การคำนวณการใช้โควต้า

Google จะคำนวณการใช้งานโควต้าโดยกำหนดต้นทุนให้กับคำขอแต่ละรายการ การดำเนินการประเภทต่างๆ มีค่าใช้จ่ายโควต้าที่แตกต่างกัน เช่น

• การดำเนินการอ่านที่ดึงข้อมูลรายการทรัพยากร เช่น ช่อง วิดีโอ เพลย์ลิสต์ มักจะใช้ 1 หน่วย
• การดำเนินการเขียนที่สร้าง อัปเดต หรือลบทรัพยากรจะมีค่าใช้จ่ายโดยปกติอยู่ที่ 50 หน่วย
• คำค้นหาใช้ 1 หน่วย
• การอัปโหลดวิดีโอมีค่าใช้จ่าย 1 หน่วย

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