Trang này trình bày các yêu cầu mẫu cho API Dữ liệu YouTube. Bạn sử dụng API dữ liệu YouTube để truy xuất và thao tác các tài nguyên trên YouTube như video, kênh và danh sách phát. Mỗi mẫu liên kết đến và điền vào Trình khám phá API của Google để bạn có thể thực thi mẫu và xem phản hồi.
Để biết thông tin về cách tải lên nội dung bằng API dữ liệu YouTube, hãy xem Tải lên tiếp nối.
Tổng quan
Để trình bày rõ ràng, các mẫu trên trang này cho thấy các thành phần riêng biệt của từng yêu cầu và viết tắt URL cơ sở cho máy chủ xử lý các yêu cầu API dữ liệu (https://www.googleapis.com/youtube/v3). Để đưa ra yêu cầu bên ngoài ngữ cảnh của các mẫu, bạn cần bao gồm URL đầy đủ.
Ví dụ: sau đây là một yêu cầu mẫu như xuất hiện trên trang này:
GET {base-URL}/channels?part=contentDetails &mine=true
URL hoàn chỉnh cho yêu cầu này là:
GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails &mine=true
Một số yêu cầu truy xuất dữ liệu chỉ dành cho chủ sở hữu của kênh YouTube, chẳng hạn như danh sách người đăng ký. Những yêu cầu này yêu cầu chủ sở hữu kênh cấp cho Google API Explorer quyền thay mặt họ thực hiện các yêu cầu API dữ liệu YouTube. (Xem bài viết Triển khai xác thực OAuth 2.0 để biết thông tin chi tiết về cách uỷ quyền truy cập vào dữ liệu kênh riêng tư.) Sau khi liên kết với APIs Explorer, hãy nhấp vào nút Uỷ quyền yêu cầu bằng OAuth 2.0. Bước này sẽ cho phép APIs Explorer thay mặt chủ sở hữu đưa ra yêu cầu. Bạn cũng chọn phạm vi uỷ quyền để chỉ định loại yêu cầu mà Trình khám phá API có thể thực hiện.
Phản hồi cho từng yêu cầu là bản trình bày JSON của một tài nguyên YouTube. Tham số part trong yêu cầu chỉ định phần nào của tài nguyên được đưa vào phản hồi. 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. Ví dụ: một số phần của tài nguyên video là:
- đoạn trích
- Chi tiết nội dung
- cầu thủ
- thống kê
- trạng thái
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.Hãy xem bài viết Làm quen với YouTube Data API để biết thêm thông tin.
Truy xuất thông tin kênh
Yêu cầu này sử dụng phương thức channels.list để truy xuất thông tin chi tiết về các kênh của người dùng đã xác thực.
GET {base_URL}/channels?part=contentDetails &mine=true
Phản hồi cho yêu cầu này bao gồm mã nhận dạng kênh và contentDetails cho kênh của người dùng đã xác thực. contentDetails bao gồm một số danh sách phát do hệ thống tạo ra liên kết với kênh. Nhiều yêu cầu tiếp theo yêu cầu mã nhận dạng kênh hoặc một trong các mã nhận dạng danh sách phát, vì vậy, bạn cần phải ghi lại các yêu cầu đó.
{
"id": {CHANNEL_ID},
"kind": "youtube#channel",
"etag": etag,
"contentDetails": {
"relatedPlaylists": {
"likes": {LIKES_PLAYLIST_ID},
"favorites": {FAVORITES_PLAYLIST_ID},
"uploads": {UPLOADS_PLAYLIST_ID},
"watchHistory": {WATCHHISTORY_PLAYLIST_ID},
"watchLater": {WATCHLATER_PLAYLIST_ID}
},
"googlePlusUserId": string
},
}
Video đã tải lên và danh sách phát do hệ thống tạo
YouTube thêm tất cả các video đã tải lên vào danh sách phát liên kết với kênh. Để xem danh sách video đã tải lên, hãy truy vấn danh sách phát "video tải lên" trong phản hồi xuất hiện ở trên để biết thông tin về kênh bằng cách sử dụng phương thức playlistItems.list để truy xuất video trong danh sách phát đó.
Trước khi thực thi yêu cầu mẫu sau đây trong Google APIs Explorer, hãy thay thế {UPLOADS_PLAYLIST_ID} bằng mã nhận dạng danh sách phát từ yêu cầu trước đó.
GET {base_URL}/playlistItems?part=contentDetails &playlistId={UPLOADS_PLAYLIST_ID}
Vui lòng lưu ý giá trị "id" cho mỗi mục được trả về chính là mã itemItem của nó. Mã video của mục danh sách phát là videoId trong phần contentDetails.
Bạn có thể truy xuất danh sách yêu thích, lượt thích, lịch sử xem hoặc danh sách xem sau của người dùng bằng cách sử dụng yêu cầu trên bằng cách thay thế ID danh sách phát tương ứng từ phản hồi thông tin kênh.
Danh sách phát do người dùng tạo
Yêu cầu này sử dụng phương thức playlists.list để truy xuất các danh sách phát được liên kết với kênh đã xác thực. Xin lưu ý rằng yêu cầu này không truy xuất danh sách phát do hệ thống tạo có trong thông tin kênh (video tải lên, nhật ký xem, v.v.). Phương thức này chỉ truy xuất danh sách phát do người dùng tạo.
GET {base_URL}/playlists?part=snippet &mine=true
Sau khi có mã nhận dạng danh sách phát, bạn có thể truy xuất các mục từ danh sách phát đó bằng cách sử dụng yêu cầu nêu trong phần trước.
Bạn có thể yêu cầu cung cấp thông tin về các danh sách phát công khai của một kênh mà không cần xác thực. Khi gửi yêu cầu chưa được xác thực, bạn cần đưa vào đối số key chỉ định khoá API duy nhất cho ứng dụng thực hiện yêu cầu. Ví dụ: yêu cầu này truy xuất các danh sách phát được liên kết với kênh Googledevelopers.
GET {base_URL}/playlists?part=snippet &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw &key={YOUR_API_KEY}
Truy xuất đăng ký
Tài nguyên subscription xác định mối quan hệ giữa người dùng YouTube (người đăng ký) và kênh. Phương thức subscriptions.list truy xuất người đăng ký vào một kênh cụ thể hoặc các kênh đăng ký của một người dùng cụ thể, tuỳ thuộc vào tham số nào bạn đưa vào yêu cầu.
Số người đăng ký kênh
Yêu cầu này truy xuất danh sách người đăng ký kênh đã xác thực.
GET {base_URL}/subscriptions?part=snippet &mySubscribers=true
Gói thuê bao của người dùng
Bạn có thể dùng chính phương thức liệt kê người đăng ký (subscriptions.list) để liệt kê các kênh mà người dùng đăng ký. Yêu cầu này sử dụng thông số mine để truy xuất danh sách các kênh YouTube mà người dùng đã xác thực đăng ký.
GET {base_URL}/subscriptions?part=snippet &mine=true
Truy xuất hoạt động của người dùng
Tài nguyên activity chứa thông tin về hành động mà một kênh hoặc người dùng cụ thể đã thực hiện trên YouTube – tải video lên, đăng ký kênh, v.v. Phương thức activities.list truy xuất các hành động liên kết với một kênh hoặc người dùng phù hợp với tiêu chí của yêu cầu. Ví dụ: bạn có thể truy xuất các hành động được liên kết với một kênh cụ thể, với các kênh đăng ký của người dùng hoặc trang chủ YouTube tùy chỉnh của người dùng.
Hoạt động trong một khoảng thời gian
Yêu cầu này truy xuất tất cả các hành động mà người dùng đã xác thực đã thực hiện trong tháng 4 năm 2013.
GET {base_URL}/activities?part=snippet,contentDetails &mine=true &publishedAfter=2013-04-01T00%3A00%3A00Z &publishedBefore=2013-05-01T00%3A00%3A00Z
Hoạt động trên trang chủ
Yêu cầu này truy xuất nguồn cấp dữ liệu hoạt động tùy chỉnh hiển thị trên trang chủ YouTube của người dùng đã xác thực.
GET {base_URL}/activities?part=snippet,contentDetails &home=true
Để truy xuất số liệu thống kê lượt xem, chỉ số mức độ phổ biến và thông tin nhân khẩu học cho video và kênh trên YouTube, bạn cần sử dụng API YouTube Analytics. Trang Yêu cầu API mẫu trình bày cách truy xuất các báo cáo phổ biến từ YouTube Analytics.
Tìm kiếm
Phương thức search.list cho phép bạn tìm kiếm video, kênh hoặc danh sách phát trên YouTube phù hợp với tiêu chí xác định. Bạn có thể tìm kiếm dựa trên thuộc tính video, từ khóa hoặc chủ đề (hoặc kết hợp các thuộc tính này) và bạn có thể sắp xếp kết quả dựa trên các yếu tố như ngày tạo, số lượt xem hoặc điểm xếp hạng.
Giống như các yêu cầu API dữ liệu YouTube khác, phương thức search.list trả về bản trình bày JSON của một tài nguyên YouTube. Tuy nhiên, không giống như các tài nguyên khác trên YouTube, kết quả tìm kiếm không phải là đối tượng ổn định có mã nhận dạng duy nhất.
Nhiều yêu cầu tìm kiếm nội dung có sẵn công khai và do đó không yêu cầu xác thực. Trong số các mẫu dưới đây, chỉ có mẫu đầu tiên yêu cầu xác thực vì mẫu đó yêu cầu cụ thể các video "của tôi". Khi gửi yêu cầu chưa được xác thực, bạn cần thêm đối số key có vai trò chỉ định khoá API duy nhất cho ứng dụng của bạn.
Các video mà tôi xem nhiều nhất
Yêu cầu này truy xuất tất cả video của người dùng đã xác thực và liệt kê video theo thứ tự giảm dần theo số lượt xem.
GET {base_URL}/search?part=snippet &forMine=true &order=viewCount &type=video
Video có độ phân giải cao có thể nhúng được
Yêu cầu này tìm kiếm các video có thuộc tính cụ thể, cụ thể là các video có độ phân giải cao có thể được nhúng vào các trang web khác. Công cụ này liệt kê các kết quả theo thứ tự xếp hạng giảm dần.
GET {base_URL}/search?part=snippet &order=rating &type=video &videoDefinition=high &videoEmbeddable=true &key={YOUR_API_KEY}
Video về một chủ đề cụ thể
Yêu cầu này thực hiện tìm kiếm từ khoá cho các video về API Dữ liệu YouTube có chứa phụ đề.
GET {base_URL}/search?part=snippet &q=YouTube+Data+API &type=video &videoCaption=closedCaption &key={YOUR_API_KEY}
Tìm kiếm theo chủ đề
Một cách phức tạp hơn để tìm kiếm video về một chủ đề cụ thể là sử dụng chủ đề Freebase thay vì từ khoá. Tài nguyên kênh và video trên YouTube đều chứa đối tượng topicDetails chứa danh sách mã chủ đề Freebase liên kết với tài nguyên. Tìm kiếm dựa trên chủ đề thông minh hơn tìm kiếm từ khóa, bởi vì chủ đề Freebase đại diện cho tất cả các khía cạnh của khái niệm hoặc sự vật trong thế giới thực.
Để tìm kiếm bằng chủ đề Freebase, trước tiên, bạn cần truy xuất mã chủ đề bằng API cơ sở miễn phí. Yêu cầu này trả về các video liên kết với chủ đề Freebase cho Python và có mã chủ đề là /m/05z1_.
GET {base_URL}/search?part=snippet &topicId=/m/05z1_ &type=video &key={YOUR_API_KEY}
Tìm kiếm danh sách phát hoặc kênh
Tìm kiếm không bị giới hạn ở video. Bạn cũng có thể tìm kiếm danh sách phát hoặc kênh. Yêu cầu này truy xuất danh sách phát khớp với từ khóa 'soccer'.
GET {base_URL}/search?part=snippet &q=soccer &type=playlist &key={YOUR_API_KEY}
Nếu muốn tìm các kênh bóng đá, bạn chỉ cần thay đổi thông số type.
GET {base_URL}/search?part=snippet &q=soccer &type=channel &key={YOUR_API_KEY}
Nếu muốn tất cả nội dung liên quan đến bóng đá (kênh, danh sách phát và video), bạn có thể tìm kiếm toàn bộ. Nếu bạn bỏ qua tham số type, yêu cầu sẽ truy xuất nội dung thuộc mọi loại
GET {base_URL}/search?part=snippet &q=soccer &key={YOUR_API_KEY}
Tạo và cập nhật tài nguyên
Các yêu cầu mà chúng ta đã xem xét cho đến nay đều sử dụng phương thức HTTP GET để truy xuất dữ liệu của YouTube. API Dữ liệu YouTube cũng cung cấp các phương thức sử dụng HTTP POST để tạo hoặc cập nhật tài nguyên YouTube như video, danh sách phát hoặc kênh. Các yêu cầu sau đây cung cấp ví dụ.
Phương thức POST bao gồm Request body, là đại diện JSON của tài nguyên đang được tạo hoặc cập nhật. Bạn có thể tạo các đại diện JSON trong Trình khám phá API của Google bằng một công cụ tương tác.
Tạo gói thuê bao
Yêu cầu này đăng ký người dùng đã xác thực vào kênh Googledevelopers. Nói cách khác, thao tác này sẽ tạo ra một tài nguyên cho gói thuê bao.
POST {base_URL}/subscriptions?part=snippet
Request body: { 'snippet': { 'resourceId': { 'kind': 'youtube#channel', 'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' } } }
Tạo danh sách phát
Yêu cầu này sẽ tạo ra một danh sách phát công khai mới.
POST {base_URL}/playlists?part=snippet
Request body: { 'snippet': { 'title': 'New playlist', 'description': 'Sample playlist for Data API', } }
Thêm video vào danh sách phát
Sau khi tạo danh sách phát, chúng ta hãy thêm video vào danh sách phát. Yêu cầu này sẽ thêm một video vào đầu danh sách phát ('position': 0).
POST {base_URL}/playlistItems?part=snippet Request body: { 'snippet': { 'playlistId': '{PLAYLIST_ID}', 'resourceId': { 'kind': 'youtube#video', 'videoId': '{VIDEO_ID}' } 'position': 0 } }