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