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 các ứng dụng có 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à API. Hướng dẫn này cũng cung cấp thông tin tổng quan về các hàm khác nhau 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 của mình.

  2. Tạo một dự án trong Google Developers Console và lấy thông tin đăng nhập cho phép để ứ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 API Console 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 BẬT cho YouTube Data API v3 (API Dữ liệu YouTube phiên bản 3).

  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 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, không phụ thuộc vào ngôn ngữ, cung cấp bả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à 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 trang 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, v.v.
channel Chứa thông tin về một kênh YouTube.
channelBanner Xác định URL cần sử dụng để đặt một hình ảnh mới tải lên làm ảnh biểu ngữ cho một 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ụ: Phần kênh có thể giới thiệu các video tải lên mới nhất, các video tải lên phổ biến nhất của một kênh hoặc các video thuộc một hoặc nhiều danh sách phát.
guideCategory Xác định một 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 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 rằng các kênh sẽ nằm trong bất kỳ danh mục hướng dẫn 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ũng có thể được gọi là ngôn ngữ giao diện người dùng.
i18nRegion Xác định 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. Vùng 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à bạn 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 danh sách phát. Tài nguyên playlistItem 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 các tham 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ể nhận dạng chính xác, chẳng hạn như video, nhưng kết quả này không có dữ liệu cố định riêng.
subscription Chứa thông tin về một gói thuê bao của người dùng trên YouTube. Gói thuê bao 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 số các thao tác trên YouTube, chẳng hạn như tải video lên, xếp hạng video hoặc bình luận về một 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 video được tải lên.
watermark Xác định hình ảnh hiển thị trong quá trình phát video của một kênh cụ thể. Chủ sở hữu kênh cũng có thể chỉ định kênh đích mà hình ảnh liên kết đến cũng như chi tiết thời gian xác định thời điểm hình mờ xuất hiện trong các lần phát video và sau đó là 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 thông tin 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: kết quả tìm kiếm 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 cho biết 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 dành riêng cho 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 tải hình thu nhỏ của video lên YouTube rồi liên kết hình thu nhỏ đó với một video.

Hoạt động tính toán
list Truy xuất (GET) một danh sách không có hoặc nhiều tài nguyên khác.
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ợ 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 các loại tài nguyên khác nhau. Những 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 và yêu cầu trái phép, trong đó yêu cầu trái phép 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 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 một hạn mức để đảm bảo nhà phát triển sử dụng dịch vụ như dự định và không tạo các ứng dụng làm giảm chất lượng dịch vụ hoặc giới hạn quyền truy cập của người khác một cách không chính đáng. Tất 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ể xem hạn mức ứng dụng của mình trong API Console.

Các dự án hỗ trợ API dữ liệu YouTube có hạn mức phân bổ mặc định là 10.000 đơn vị mỗi ngày, đủ cho 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 hoá 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 cho người dùng API. Bạn có thể xem mức sử dụng của hạn mức 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 bổ sung hạn mức bằng cách hoàn tất việc mở rộng hạn mức biểu mẫu yêu cầu liên quan đến 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 gán chi phí cho mỗi yêu cầu. Các loại các hoạt động có chi phí hạn mức khác nhau. Ví dụ:

  • Thao tác đọc sẽ truy xuất danh sách tài nguyên -- kênh, video, danh sách phát -- thường là có giá 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ó chi phí là 1600 đơn vị.

Bảng Chi phí hạn mức cho các yêu cầu API cho thấy hạn mức chi phí 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 này hỗ trợ 2 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 được đư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 cho 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 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 những đối tượng này là các nhóm trường siêu dữ liệu mà máy chủ API có thể truy xuất (hoặc có thể không truy xuất). Do đó, tham số part sẽ yêu cầu bạn chọn các thành phần tài nguyên mà ứng dụng thực sự sử dụng. Yêu cầu này phục vụ hai mục đích chính:

  • Tính năng này làm 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.
  • Tính năng này 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 tài nguyên được 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 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 hơn mức sử dụng băng thông của bạn. (Bạn không thể dùng tham số part để lọc các thuộc tính lồng nhau khỏi phản hồi.)

Các quy tắc sau 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 các thuộc tính lồng nhau sẽ được đưa vào phản hồi API.
  • Sử dụng dấu gạch chéo lên (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 khác nhau truy xuất cùng một phản hồi của API. Ví dụ: nếu bạn muốn truy xuất ID mục danh sách phát, tiêu đề và vị trí của 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 là URL được mã hoá. Để dễ đọc hơn, các ví dụ trong tài liệu này sẽ bỏ kiểu mã hoá.

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

Các ví dụ bên dưới minh hoạ cách bạn có thể 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 2 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 loại trừ 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 2 phần nhưng không bao gồm kind và etag cũng như một số thuộc tính lồng 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 thẻ 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 các 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 chưa 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ối các tài nguyên được lưu vào bộ nhớ đệm theo cách này.

    Thư viện ứng dụng cho API của Google có hỗ trợ ETag khác nhau. Ví dụ: thư viện ứng dụng JavaScript hỗ trợ ETag qua danh sách cho phép cho các tiêu đề yêu cầu được phép bao gồm If-Match và If-None-Match. Danh sách trắng cho phép lưu vào bộ nhớ đệm của trình duyệt thông thường để 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ợ ETag.

  • Ngăn chặn 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á 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 gần đây 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:

  • API phản hồi nhanh hơn 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 đè 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 đề yêu cầu HTTP If-Match và If-None-Match, do đó 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 API bằng cách bật 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 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 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.

Tiêu đề HTTP mẫu bên dưới minh hoạ các yêu cầu này để bật chức năng nén gzip:

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