Tổng quan về API Dữ liệu YouTube

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à của chính API. Hướng dẫn này cũng cung cấp thông tin tổng quan về các hàm mà API 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 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 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 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 trạng thái là BẬT cho YouTube Data API v3.

  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 (Ký hiệu đối tượng JavaScript). JSON là một định dạng dữ liệu phổ biến, độc lập về ngôn ngữ, cung cấp văn bản đơn giản về 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ó một 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 thao tác 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 việc xếp hạng video, chia sẻ video, đánh dấu video là video 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 để dùng làm hình ảnh biểu ngữ cho một kênh mới tải lên.
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ể bao gồm các video tải lên mới nhất của kênh, các video tải lên phổ biến nhất hoặc cá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 các kênh dựa trên nội dung 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ể liên kết với một hoặc nhiều danh mục hướng dẫn, nhưng chúng không chắc được thuộc 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ữ của ứ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òn 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à tập hợp video mà bạn có thể xem tuần tự và chia sẻ với người dùng khác.
playlistItem Xác định tài nguyên, chẳng hạn như video, là một phần của danh sách phát. Tài nguyên listItem cũng chứa thông tin chi tiết giải thích cách sử dụng tài nguyên 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ể nhận dạng riêng biệt, chẳng hạn như video, nhưng lại không có dữ liệu cố định.
subscription Chứa thông tin về gói thuê bao của người dùng YouTube. Lượt đăng ký thông báo cho người dùng khi 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 bình luận về video.
thumbnail Xác định hình thu nhỏ được 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 danh mục đã hoặc có thể liên kết với video được tải lên.
watermark Xác định hình ảnh hiển thị trong các lượt 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 mục tiêu mà hình ảnh sẽ liên kết 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 thời gian phát video và sau đó là khoảng thời gian hình mờ đó được hiển thị.

Xin lưu ý rằng trong nhiều trường hợp, một tài nguyên chứa các tệp 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 tương ứng 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 giúp 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 hỗ trợ. Một số tài nguyên cũng hỗ trợ các phương thức thực hiện chức năng cụ thể hơn cho các 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 một hình thu nhỏ video lên YouTube và liên kết video đó với một video.

Hoạt động vận hành
list Truy xuất (GET) danh sách từ 0 tài nguyên 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 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à 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 phải có 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à không được phép, trong đó các yêu cầu trái phép chỉ truy xuất dữ liệu công khai trong khi 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ư đối với người dùng hiện đã xác thực.

Toán tử đượ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

Mức sử dụng hạn mức

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

Các dự án hỗ trợ API dữ liệu YouTube có mức phân bổ mặc định là 10.000 đơn vị mỗi ngày, số tiền đủ lớn 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 sẽ 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 đố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 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 gia hạn 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 toán mức sử dụng hạn mức của bạn bằng cách gán chi phí cho từng yêu cầu. Mỗi loại hình vận hành sẽ có mức chi phí 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ị.
  • Thao tác ghi để tạo, cập nhật hoặc xoá tài nguyên thường có chi phí là 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í 1600 đơn vị.

Bảng Chi phí định mức cho các yêu cầu API cho biết chi phí định mức của từng phương thức API. Với 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ó 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 thực sự cho phép 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. Cách này cũng đảm bảo API sử dụng tài nguyên mạng, CPU và 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 những thuộc tính tài nguyên cần có trong các 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 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 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 được lồng) cần đư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 thuộc tính lồng nhau và bạn có thể coi những đối tượng này là nhóm các 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 có hai mục đích chính:

  • Phương pháp này làm giảm độ trễ bằng cách ngăn máy chủ API thời gian truy xuất những trường siêu dữ liệu mà ứng dụng không dùng.
  • Giải pháp này 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 thêm các phầ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 này không hỗ trợ.

Cách sử dụng tham 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 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 API, nhờ đó giảm 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 thuộc tính lồng nhau khỏi nội dung 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, là lỗi cú pháp dựa trên 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.
  • Hãy 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 API.
  • Sử dụng dấu gạch chéo lên (fields=a/b) để xác định một 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 API. Ví dụ: nếu bạn muốn truy xuất mã, tiêu đề và vị trí của mục 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ư với tất cả các giá trị tham số truy vấn, giá trị tham số fields phải được mã hóa URL. Để dễ đọc hơn, các ví dụ trong tài liệu này sẽ bỏ qua việc mã hoá.

Yêu cầu mẫu một 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ố part và fields để đảm bảo rằng phản hồi 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 loại trừ 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 thẻ điện tử

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 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ợ những trường hợp sử dụng sau đây:

  • 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 chúng vào bộ nhớ đệm. Sau đó, khi yêu cầu lại một tài nguyên đã 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 được sửa đổi và ETag được 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. Ứng dụng của bạn có thể giảm độ trễ và 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 cho API của Google khác nhau trong việc hỗ trợ 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 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 lưu vào bộ nhớ đệm của trình duyệt thông thườ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.

  • 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 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:

  • API phản hồi nhanh hơn với các yêu cầu 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à 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 tạo từ một ứng dụng API khác.

Google APIs Client Library for JavaScript hỗ trợ tiêu đề của yêu cầu HTTP If-Match và If-None-Match, cho phép ETag hoạt động trong bối 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 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 để xử lý các phản hồi của API không nén, nhưng việc tốn ít tài nguyên mạng hơn thường tốn nhiều chi phí hơn.

Để nhận được phản hồi đã mã hoá gzip, bạn phải thực hiện 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 tính năng nén gzip:

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