Tổng quan về YouTube Data API

Giới thiệu

Tài liệu này dành cho các 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à bản thân API. Bài viết này cũng cung cấp thông tin tổng quan về nhiều hàm mà API hỗ trợ.

Trước khi bắt đầu

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

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

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

    1. Chuyển đến Bảng điều khiển API rồi chọn dự án mà bạn vừa đăng ký.
    2. Truy cập vào trang API đã bật. Trong danh sách API, hãy đảm bảo trạng thái của YouTube Data API v3BẬT.

  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 chính về đị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 phần 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à các 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 duy nhấ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ề 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 nguồn cấp dữ liệu hoạt động bao gồm xếp hạng video, chia sẻ video, đánh dấu video là yêu thích và đăng bản tin 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 ảnh biểu ngữ cho kênh.
channelSection Chứa thông tin về một loạt 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 tải lên mới nhất của một kênh, video tải lên phổ biến nhất hoặc video từ một hoặc nhiều danh sách phát.
guideCategory Xác định danh mục mà YouTube liên kết với 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 tìm cách sắp xếp các kênh theo cách giúp người dùng YouTube tìm thấy nội dung họ đang tìm kiếm dễ dàng hơn. Mặc dù các kênh có thể được liên kết với một hoặc nhiều danh mục hướng dẫn, nhưng chúng tôi không đảm bảo sẽ có trong bất kỳ danh mục hướng dẫn nào.
i18nLanguage Xác định một ngôn ngữ của ứng dụng mà trang web YouTube hỗ trợ. Ngôn ngữ ứng dụng cũng có thể đượ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 tập hợp các video mà người dùng có thể xem theo tuần 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, thuộc một danh sách phát. Tài nguyên listItem cũng chứa các thông tin chi tiết giải thích cách sử dụng tài nguyên đi kèm trong danh sách phát.
search result Chứa thông tin về video, kênh hoặc danh sách phát trên YouTube khớp với thông số tìm kiếm được chỉ định trong 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ể xác định danh tính chính xác, chẳng hạn như video, nhưng tài nguyên đó không có dữ liệu cố định riêng.
subscription Chứa thông tin về đăng ký của người dùng YouTube. Gói đă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 người dùng khác thực hiện một trong các hành động trên YouTube, chẳng hạn như tải video lên, xếp hạng video hoặc nhận xét 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 đã hoặc có thể được liên kết với các video đã tải lên.
watermark Xác định hình ảnh sẽ hiển thị trong khi phát lại video của một kênh cụ thể. Chủ sở hữu kênh cũng có thể chỉ định 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 khi phát lại video và khoảng thời gian hiển thị hình mờ đó.

Lưu ý rằng, trong nhiều trường hợp, tài nguyên 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 và chứa thông tin đầy đủ về video đó. Một ví dụ khác là kết quả tìm kiếm có chứa thuộc tính videoId, playlistId hoặc channelId giúp xác định một video, danh sách phát hoặc tài nguyên kênh cụ thể.

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

Bảng sau đây trình bày các phương thức phổ biến nhất mà API 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 của người dùng với một video, còn phương thức thumbnails.set sẽ tải hình thu nhỏ video lên YouTube rồi liên kết hình thu nhỏ đó với một video.

Toán tử
list Truy xuất (GET) một danh sách từ 0 trở lê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 này hiện hỗ trợ các phương thức liệt kê từng loại tài nguyên được hỗ trợ, đồng thời cũng hỗ trợ 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 các loại tài nguyên khác nhau. Các thao tác chèn, cập nhật hoặc xoá tài nguyên luôn yêu cầu sự cho phép của người dùng. Trong một số trường hợp, phương thức list hỗ trợ cả yêu cầu được uỷ quyền lẫn yêu cầu trái phép, trong đó các yêu cầu trái phép chỉ truy xuất dữ liệu công khai còn các yêu cầu được uỷ quyền cũng có thể truy xuất thông tin về hoặc riêng tư cho 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

Sử dụng hạn mức

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

Các dự án hỗ trợ YouTube Data API được phân bổ hạn mức mặc định là 10.000 đơn vị mỗi ngày, đủ để đáp ứng phần lớn người dùng API của chúng tôi. Hạn mức mặc định, có thể thay đổi, giúp chúng tôi tối ưu hóa việc phân bổ hạn mức và mở rộng cơ sở hạ tầng theo cách có ý nghĩa hơn đối với người dùng API. Bạn có thể xem mức sử dụng hạn mức của mình trên trang Hạn mức trong Bảng điều khiển API.

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 gia hạn hạn mức cho Dịch vụ API YouTube.

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

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

  • 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ị.
  • Thao tác ghi tạo, cập nhật hoặc xoá một tài nguyên thường tốn chi phí 50 đơn vị.
  • Một yêu cầu tìm kiếm có giá 100 đơn vị.
  • Một video tải lên có giá 1600 đơ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 mỗi phương thức API. Với những 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 bạn 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 một phần tài nguyê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ớ một cách hiệu quả hơn.

API hỗ trợ 2 tham số yêu cầu được giải thích trong các phần sau. Nhờ đó, bạn có thể 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 sẽ đượ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 những phần tài nguyên được yêu cầu.

Cách sử dụng thông 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 đư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à các đố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à các 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ự dùng. Yêu cầu này phục vụ hai mục đích chính:

  • Tính năng 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.
  • Nó làm 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 bổ sung nhiều phần hơn, những lợi ích này sẽ 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 ra mắt mà ứng dụng không hỗ trợ.

Cách sử dụng thông số fields

Tham số fields lọc phản hồi 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 nhóm 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, do đó giảm hơn nữa mức sử dụng băng thông. (Không thể dùng tham số part để lọc các thuộc tính lồng nhau khỏi 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, giá trị này dựa trên cú pháp XPath một cách lỏng lẻo:

  • 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 nhóm các 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 thuộc tính lồng nhau.

Trong thực tế, các quy tắc này thường cho phép nhiều giá trị tham số fields truy xuất cùng một phản hồi API. Ví dụ: nếu muốn truy xuất mã mục, 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 bỏ qua chế độ mã hoá.

Ví dụ về yêu cầu từng phần

Các ví dụ bên dưới minh hoạ cách bạn có thể sử dụng các tham số partfields để đảm bảo rằng các 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 kindetag.
  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 kindetag.
  3. Ví dụ 3 trả về một tài nguyên video bao gồm 2 phần nhưng không bao gồm các thuộc tính kindetag.
  4. Ví dụ 4 trả về tài nguyên video bao gồm 2 phần nhưng loại trừ kindetag 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 là 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ặt hàng 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 các tài nguyên đó vào bộ nhớ đệm. Sau đó, khi ứng dụng yêu cầu lại 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 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). Phản hồi này cho biết tài nguyên chưa thay đổi. Ứng dụng của bạn có thể giảm độ trễ và mức sử dụng băng thông 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.

    Thư viện ứng dụng dành cho các API của Google khác nhau về khả năng hỗ trợ ETags. Ví dụ: thư viện ứng dụng JavaScript hỗ trợ ETags 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-MatchIf-None-Match. Danh sách cho phép cho phép lưu vào bộ nhớ đệm thông thường của trình duyệt diễn ra để nếu ETag của tài nguyên không thay đổi, 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ợ ETags.

  • Tránh việc vô tình ghi đè các thay đổi – ETags 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 của bạn mang lại một số lợi ích sau:

  • API phản hồi nhanh hơn với các yêu cầu về tài nguyên được lưu vào bộ nhớ đệm nhưng không thay đổi, mang lại độ trễ thấp hơn và mức sử dụng băng thông thấp hơn.
  • Ứng dụng của bạn sẽ không vô tình ghi đè những thay đổi đối với tài nguyên được thực hiện qua 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-MatchIf-None-Match, do đó cho phép ETags hoạt động trong ngữ cảnh lưu vào bộ nhớ đệm của trình duyệt thông thường.

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 API bằng cách bật chức 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 thường lớn hơn chi phí đó.

Để nhận được phản hồi được mã hoá bằng gzip, bạn phải làm hai việ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ạ các yêu cầu sau để bật chức năng nén gzip:

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