Tổng quan về YouTube Data API

Giới thiệu

Tài liệu này dành cho những nhà phát triển muốn viết ứng dụng tương tác với YouTube. Tài liệu này giải thích các khái niệm cơ bản về YouTube và chính API này. Tài liệu này cũng cung cấp thông tin tổng quan về các hàm mà API này hỗ trợ.

Trước khi bắt đầu

  1. Bạn cần có một Tài khoản Google để truy cập vào Google Cloud Console, yêu cầu khoá API và đăng ký ứng dụng.

  2. Tạo một dự án trong Google Developers Console và lấy thông tin xác thực uỷ quyền để ứng dụng của bạn có thể gửi các yêu cầu API.

  3. Sau khi tạo dự án, hãy đảm bảo YouTube Data API là một trong những dịch vụ mà ứng dụng của bạn được đăng ký sử dụng:

    1. Chuyển đến Cloud Console rồi chọn dự án bạn vừa đăng ký.
    2. Truy cập vào trang API đã bật. Đảm bảo rằng YouTube Data API có trong danh sách các API đã bật. Nếu không, hãy mở Thư viện API rồi bật API này.

  4. Nếu ứng dụng của bạn sử dụng bất kỳ phương thức API nào yêu cầu có xác thực của người dùng, hãy đọc hướng dẫn xác thực để biết cách thực hiện xác thực OAuth 2.0.

  5. Chọn thư viện ứng dụng để đơn giản hóa quá trình thực hiện API của bạn.

  6. Làm quen với các khái niệm cốt lõi của định dạng dữ liệu JSON (JavaScript Object Notation). JSON là một định dạng dữ liệu phổ biến, độc lập về ngôn ngữ, cung cấp nội dung trình bày văn bản đơn giản của các cấu trúc dữ liệu tuỳ ý. Để biết thêm thông tin, hãy xem json.org.

Tài nguyên và loại tài nguyên

Tài nguyên là một thực thể dữ liệu riêng lẻ có giá trị nhận dạng riêng biệt. Bảng dưới đây mô tả các loại tài nguyên mà bạn có thể tương tác bằng API.

Tài nguyên
activity Chứa thông tin về một hành động mà một người dùng cụ thể đã thực hiện trên trang web YouTube. Các hành động của người dùng được báo cáo trong Bảng tin hoạt động bao gồm đánh giá video, chia sẻ video, đánh dấu video là video yêu thích và đăng bản tin trên kênh, cùng nhiều hành động khác.
channel Chứa thông tin về một kênh YouTube.
channelBanner Xác định URL cần dùng để đặt hình ảnh mới tải lên làm hình ảnh biểu ngữ cho kênh.
channelSection Chứa thông tin về một nhóm video mà một kênh đã chọn để giới thiệu. Ví dụ: một phần có thể giới thiệu video mới nhất, video phổ biến nhất hoặc video trong một hay nhiều danh sách phát của một kênh.
guideCategory Xác định danh mục mà YouTube liên kết với các kênh dựa trên nội dung của kênh hoặc các chỉ báo khác, chẳng hạn như mức độ phổ biến. Danh mục hướng dẫn sắp xếp các kênh theo cách giúp người dùng YouTube dễ dàng tìm thấy nội dung họ muốn xem. Mặc dù kênh có thể được liên kết với một hoặc nhiều danh mục trong hướng dẫn, nhưng không có gì đảm bảo rằng kênh sẽ xuất hiện trong danh mục nào đó.
i18nLanguage Xác định ngôn ngữ ứng dụng mà trang web YouTube hỗ trợ. Ngôn ngữ ứng dụng còn được gọi là ngôn ngữ giao diện người dùng.
i18nRegion Xác định một khu vực địa lý mà người dùng YouTube có thể chọn làm khu vực nội dung ưu tiên. Khu vực nội dung cũng có thể được gọi là ngôn ngữ nội dung.
playlist Đại diện cho một danh sách phát trên YouTube. Danh sách phát là một tuyển tập video có thể xem theo trình tự và chia sẻ với người dùng khác.
playlistItem Xác định một tài nguyên (chẳng hạn như video) có trong danh sách phát. Tài nguyên playlistItem cũng chứa thông tin chi tiết giải thích cách tài nguyên có trong danh sách phát được sử dụng.
search result Chứa thông tin về một video trên YouTube, kênh hoặc danh sách phát phù hợp với các thông số tìm kiếm được chỉ định trong một yêu cầu API. Mặc dù kết quả tìm kiếm trỏ đến một tài nguyên có thể nhận dạng chính xác (chẳng hạn như video), nhưng kết quả tìm kiếm không có dữ liệu cố định riêng.
subscription Chứa thông tin về gói thuê bao của người dùng YouTube. Tính năng đăng ký sẽ thông báo cho người dùng khi có video mới được thêm vào kênh hoặc khi một người dùng khác thực hiện một trong số các hành động trên YouTube, chẳng hạn như tải video lên, đánh giá video hoặc bình luận về video.
thumbnail Xác định hình thu nhỏ liên kết với một tài nguyên.
video Đại diện cho một video trên YouTube.
videoCategory Xác định một danh mục đã được hoặc có thể được liên kết với video đã tải lên.
watermark Xác định hình ảnh xuất hiện trong khi phát video của một kênh cụ thể. Chủ sở hữu kênh cũng có thể chỉ định một kênh mục tiêu mà hình ảnh liên kết đến, cũng như thông tin chi tiết về thời gian xác định thời điểm hình mờ xuất hiện trong quá trình phát video và thời lượng hiển thị của hình mờ.

Xin lưu ý rằng trong nhiều trường hợp, một tài nguyên có chứa các tham chiếu đến các tài nguyên khác. Ví dụ: thuộc tính snippet.resourceId.videoId của tài nguyên playlistItem xác định một tài nguyên video, trong đó chứa thông tin đầy đủ về video. Một ví dụ khác là kết quả tìm kiếm chứa thuộc tính videoId, playlistId hoặc channelId để xác định một tài nguyên video, danh sách phát hoặc kênh cụ thể.

Thao tác được hỗ trợ

Bảng sau đây cho thấy các phương thức phổ biến nhất mà API này hỗ trợ. Một số tài nguyên cũng hỗ trợ các phương thức khác thực hiện các chức năng cụ thể hơn đối với những tài nguyên đó. Ví dụ: phương thức videos.rate liên kết điểm xếp hạng từ người dùng với một video, còn phương thức thumbnails.set tải hình thu nhỏ video lên YouTube và liên kết hình thu nhỏ đó với một video.

Vận hành
list Truy xuất (GET) danh sách gồm 0 hoặc nhiều tài nguyên.
insert Tạo (POST) một tài nguyên mới.
update Sửa đổi (PUT) một tài nguyên hiện có để phản ánh dữ liệu trong yêu cầu của bạn.
delete Xoá (DELETE) một tài nguyên cụ thể.

API hiện hỗ trợ các phương thức liệt kê từng loại tài nguyên được hỗ trợ và cũng hỗ trợ các thao tác ghi cho nhiều tài nguyên.

Bảng dưới đây xác định các thao tác được hỗ trợ cho nhiều loại tài nguyên. Các thao tác chèn, cập nhật hoặc xoá tài nguyên luôn yêu cầu uỷ quyền cho người dùng. Trong một số trường hợp, các phương thức list hỗ trợ cả yêu cầu được uỷ quyền và yêu cầu không được uỷ quyền, trong đó yêu cầu không được uỷ quyền chỉ truy xuất dữ liệu công khai, còn yêu cầu được uỷ quyền cũng có thể truy xuất thông tin về hoặc thông tin riêng tư của người dùng hiện đã được xác thực.

Thao tác được hỗ trợ
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

Hạn mức sử dụng

YouTube Data API sử dụng hạn mức để đảm bảo rằng các nhà phát triển sử dụng dịch vụ theo đúng mục đích và không tạo ra các ứng dụng làm giảm chất lượng dịch vụ hoặc hạn chế quyền truy cập của người khác một cách không công bằng. Tất cả các yêu cầu API, bao gồm cả yêu cầu không hợp lệ, đều phải chịu chi phí hạn mức ít nhất là một điểm. Bạn có thể tìm thấy hạn mức dành cho ứng dụng của mình trong API Console.

Các dự án bật YouTube Data API có hạn mức phân bổ mặc định là 100 lệnh gọi search.list, 100 lệnh gọi videos.insert và 10.000 đơn vị mỗi ngày (kết hợp cho tất cả các điểm cuối khác). Hạn mức mặc định (có thể thay đổi) giúp chúng tôi tối ưu hoá việc phân bổ hạn mức và mở rộng cơ sở hạ tầng theo cách phù hợp hơn với người dùng API. Bạn có thể xem hạn mức sử dụng trên trang Hạn mức trong API Console.

Lưu ý: Nếu đạt đến hạn mức, bạn có thể yêu cầu tăng hạn mức bằng cách hoàn tất Biểu mẫu yêu cầu tăng hạn mức cho Các dịch vụ API YouTube.

Đang tính toán mức sử dụng hạn mức

Google tính mức sử dụng hạn mức của bạn bằng cách chỉ định một chi phí cho mỗi yêu cầu. Các loại thao tác khác nhau có chi phí hạn mức khác nhau. Ví dụ:

  • Một thao tác đọc truy xuất danh sách tài nguyên (kênh, video, danh sách phát) thường tốn 1 đơn vị.
  • Một thao tác ghi tạo, cập nhật hoặc xoá một tài nguyên thường tốn 50 đơn vị.
  • Một cụm từ tìm kiếm có chi phí là 1 đơn vị.
  • Một video tải lên tốn 1 đơn vị.

Bảng Chi phí hạn mức cho các yêu cầu API cho biết chi phí hạn mức của từng phương thức API. Khi nắm rõ các quy tắc này, bạn có thể ước tính số lượng yêu cầu mà ứng dụng của mình có thể gửi mỗi ngày mà không vượt quá hạn mức.

Tài nguyên một phần

API này cho phép và thực sự yêu cầu truy xuất tài nguyên một phần để các ứng dụng tránh chuyển, phân tích cú pháp và lưu trữ dữ liệu không cần thiết. Phương pháp này cũng đảm bảo rằng API sử dụng mạng, CPU và tài nguyên bộ nhớ hiệu quả hơn.

API này hỗ trợ hai tham số yêu cầu (được giải thích trong các phần sau) cho phép bạn xác định các thuộc tính tài nguyên cần đưa vào phản hồi của API.

  • Tham số part xác định các nhóm thuộc tính cần được trả về cho một tài nguyên.
  • Tham số fields lọc phản hồi của API để chỉ trả về các thuộc tính cụ thể trong các phần tài nguyên được yêu cầu.

Cách sử dụng tham số part

Tham số part là tham số bắt buộc đối với mọi yêu cầu API truy xuất hoặc trả về tài nguyên. Tham số này xác định một hoặc nhiều thuộc tính tài nguyên cấp cao nhất (không lồng nhau) cần được đưa vào phản hồi của API. Ví dụ: tài nguyên video có các phần sau:

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

Tất cả các phần này đều là đối tượng chứa các thuộc tính lồng nhau và bạn có thể coi các đối tượng này là nhóm trường siêu dữ liệu mà máy chủ API có thể (hoặc không thể) truy xuất. Do đó, tham số part yêu cầu bạn chọn các thành phần tài nguyên mà ứng dụng của bạn thực sự sử dụng. Yêu cầu này phục vụ 2 mục đích chính:

  • Việc này giúp giảm độ trễ bằng cách ngăn máy chủ API dành thời gian truy xuất các trường siêu dữ liệu mà ứng dụng của bạn không sử dụng.
  • Điều này giúp giảm mức sử dụng băng thông bằng cách giảm (hoặc loại bỏ) lượng dữ liệu không cần thiết mà ứng dụng của bạn có thể truy xuất.

Theo thời gian, khi các tài nguyên thêm nhiều phần hơn, những lợi ích này sẽ chỉ tăng lên vì ứng dụng của bạn sẽ không yêu cầu các thuộc tính mới được giới thiệu mà ứng dụng không hỗ trợ.

Cách sử dụng tham số fields

Tham số fields sẽ lọc phản hồi của API, chỉ chứa các phần tài nguyên được xác định trong giá trị tham số part, để phản hồi chỉ bao gồm một tập hợp các trường cụ thể. Tham số fields cho phép bạn xoá các thuộc tính lồng nhau khỏi phản hồi của API, nhờ đó giảm thêm mức sử dụng băng thông. (Bạn không thể dùng tham số part để lọc các thuộc tính lồng nhau trong một phản hồi.)

Các quy tắc sau đây giải thích cú pháp được hỗ trợ cho giá trị tham số fields, dựa trên cú pháp XPath:

  • Sử dụng danh sách được phân tách bằng dấu phẩy (fields=a,b) để chọn nhiều trường.
  • Sử dụng dấu hoa thị (fields=*) làm ký tự đại diện để xác định tất cả các trường.
  • Sử dụng dấu ngoặc đơn (fields=a(b,c)) để chỉ định một nhóm thuộc tính lồng nhau sẽ được đưa vào phản hồi của API.
  • Sử dụng dấu gạch chéo xuôi (fields=a/b) để xác định một thuộc tính lồng nhau.

Trên thực tế, các quy tắc này thường cho phép một số giá trị tham số fields khác nhau truy xuất cùng một phản hồi của API. Ví dụ: nếu muốn truy xuất mã nhận dạng, tiêu đề và vị trí của mục trong danh sách phát cho mọi mục trong danh sách phát, bạn có thể sử dụng bất kỳ giá trị nào sau đây:

  • fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
  • fields=items(id,snippet/title,snippet/position)
  • fields=items(id,snippet(title,position))

Lưu ý: Giống như tất cả giá trị tham số truy vấn, giá trị tham số fields phải được mã hoá URL. Để dễ đọc hơn, các ví dụ trong tài liệu này sẽ bỏ qua quá trình mã hoá.

Yêu cầu một phần mẫu

Các ví dụ dưới đây minh hoạ cách bạn có thể sử dụng tham số part và fields để đảm bảo rằng phản hồi của API chỉ bao gồm dữ liệu mà ứng dụng của bạn sử dụng:

  1. Ví dụ 1 trả về một tài nguyên video bao gồm 4 phần cũng như các thuộc tính kind và etag.
  2. Ví dụ 2 trả về một tài nguyên video bao gồm hai phần cũng như các thuộc tính kind và etag.
  3. Ví dụ 3 trả về một tài nguyên video bao gồm hai phần nhưng không bao gồm các thuộc tính kind và etag.
  4. Ví dụ 4 trả về một tài nguyên video bao gồm hai phần nhưng không bao gồm kind và etag cũng như một số thuộc tính lồng nhau trong đối tượng snippet của tài nguyên.
Ví dụ 1
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"
   }
  }
 ]
}
Ví dụ 2
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"
   }
  }
 ]
}
Ví dụ 3
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"
   }
  }
 ]
}
Ví dụ 4
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"
   }
  }
 ]
}

Tối ưu hoá hiệu suất

Sử dụng ETag

ETags, một phần tiêu chuẩn của giao thức HTTP, cho phép các ứng dụng tham chiếu đến một phiên bản cụ thể của một tài nguyên API cụ thể. Tài nguyên có thể là toàn bộ nguồn cấp dữ liệu hoặc một mục trong nguồn cấp dữ liệu đó. Chức năng này hỗ trợ các trường hợp sử dụng sau:

  • Lưu vào bộ nhớ đệm và truy xuất có điều kiện – Ứng dụng của bạn có thể lưu tài nguyên API và ETag của tài nguyên vào bộ nhớ đệm. Sau đó, khi ứng dụng của bạn yêu cầu lại một tài nguyên được lưu trữ, ứng dụng sẽ chỉ định ETag liên kết với tài nguyên đó. Nếu tài nguyên đã thay đổi, API sẽ trả về tài nguyên đã sửa đổi và ETag liên kết với phiên bản đó của tài nguyên. Nếu tài nguyên không thay đổi, API sẽ trả về phản hồi HTTP 304 (Not Modified), cho biết tài nguyên không thay đổi. Bằng cách phân phát tài nguyên được lưu vào bộ nhớ đệm theo cách này, ứng dụng của bạn có thể giảm độ trễ và mức sử dụng băng thông.

    Các thư viện ứng dụng cho API của Google có mức độ hỗ trợ khác nhau đối với ETag. Ví dụ: thư viện ứng dụng JavaScript hỗ trợ ETag thông qua danh sách cho phép đối với các tiêu đề của yêu cầu được phép, bao gồm If-Match và If-None-Match. Danh sách cho phép cho phép bộ nhớ đệm thông thường của trình duyệt hoạt động để nếu ETag của một tài nguyên không thay đổi, thì tài nguyên đó có thể được phân phát từ bộ nhớ đệm của trình duyệt. Mặt khác, ứng dụng Obj-C không hỗ trợ ETag.

  • Bảo vệ khỏi việc vô tình ghi đè các thay đổi – ETag giúp đảm bảo rằng nhiều ứng dụng API không vô tình ghi đè các thay đổi của nhau. Khi cập nhật hoặc xoá một tài nguyên, ứng dụng của bạn có thể chỉ định ETag của tài nguyên đó. Nếu ETag không khớp với phiên bản mới nhất của tài nguyên đó, thì yêu cầu API sẽ không thành công.

Việc sử dụng ETag trong ứng dụng mang lại một số lợi ích:

  • Phản hồi của API nhanh hơn đối với các yêu cầu về tài nguyên đã lưu vào bộ nhớ đệm nhưng không thay đổi, giúp giảm độ trễ và mức sử dụng băng thông.
  • Ứng dụng của bạn sẽ không vô tình ghi đè các thay đổi đối với tài nguyên được thực hiện từ một ứng dụng API khác.

Google APIs Client Library for JavaScript hỗ trợ các tiêu đề của yêu cầu HTTP If-Match và If-None-Match, nhờ đó cho phép ETag hoạt động trong bối cảnh lưu vào bộ nhớ đệm thông thường của trình duyệt.

Sử dụng gzip

Bạn cũng có thể giảm băng thông cần thiết cho mỗi phản hồi của API bằng cách bật tính năng nén gzip. Mặc dù ứng dụng của bạn sẽ cần thêm thời gian của CPU để giải nén các phản hồi của API, nhưng lợi ích của việc tiêu thụ ít tài nguyên mạng hơn thường lớn hơn chi phí đó.

Để nhận được phản hồi được mã hoá sau khi nén gzip, bạn phải thực hiện 2 thao tác:

  • Đặt tiêu đề của yêu cầu HTTP Accept-Encoding thành gzip.
  • Sửa đổi tác nhân người dùng để chứa chuỗi gzip.

Các tiêu đề HTTP mẫu dưới đây minh hoạ những yêu cầu này để bật tính năng nén gzip:

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