مجموعهای از عناصر فهرست پخش را که با پارامترهای درخواست API مطابقت دارند برمیگرداند. میتوانید همه موارد فهرست پخش را در یک فهرست پخش مشخص بازیابی کنید یا یک یا چند مورد فهرست پخش را با شناسه یکتای آنها بازیابی کنید.
تأثیر سهمیه: فراخوانی این روش هزینه سهمیه ۱ واحدی دارد.
موارد استفاده رایج
درخواست
درخواست HTTP
GET https://www.googleapis.com/youtube/v3/playlistItems
پارامترها
جدول زیر پارامترهایی را که این پُرسمان پشتیبانی میکند فهرست میکند. همه پارامترهای فهرستشده پارامترهای پُرسمان هستند.
| پارامترها | ||
|---|---|---|
| پارامترهای الزامی | ||
part |
stringپارامتر part فهرستی جداشده با کاما از یک یا چند ویژگی منبع playlistItem را مشخص میکند که پاسخ API شامل آن خواهد بود.اگر پارامتر ویژگیای را شناسایی کند که حاوی ویژگیهای فرزند است، ویژگیهای فرزند در پاسخ گنجانده خواهند شد. برای مثال، در منبع playlistItem، ویژگی snippet حاوی فیلدهای متعددی است، ازجمله ویژگیهای title، description، position، و resourceId. بنابراین، اگر part=snippet را تنظیم کنید، پاسخ میانای برنامهسازی کاربردی حاوی همه آن ویژگیها خواهد بود.فهرست زیر حاوی نامهای part است که میتوانید در مقدار پارامتر اضافه کنید:
|
|
| فیلترها (دقیقاً یکی از پارامترهای زیر را مشخص کنید) | ||
id |
stringپارامتر id فهرست جداشده با کاما از یک یا چند شناسه یکتای عنصر فهرست پخش را مشخص میکند. |
|
playlistId |
stringپارامتر playlistId شناسه یکتای فهرست پخشی را که میخواهید موارد فهرست پخش آن را بازیابی کنید مشخص میکند. توجه داشته باشید که اگرچه این یک پارامتر اختیاری است، اما هر درخواست برای بازیابی موارد فهرست پخش باید مقداری را برای پارامتر id یا پارامتر playlistId مشخص کند. |
|
| پارامترهای اختیاری | ||
maxResults |
unsigned integerپارامتر maxResults حداکثر تعداد مواردی را که باید در مجموعه نتایج برگردانده شود مشخص میکند. مقادیر پذیرفتنی از 0 تا 50 (شامل این دو عدد) است. مقدار پیشفرض 5 است. |
|
onBehalfOfContentOwner |
stringاز این پارامتر فقط میتوان در درخواست مجاز مناسب استفاده کرد. توجه: این پارامتر منحصراً برای شرکای محتوای YouTube درنظر گرفته شده است. پارامتر onBehalfOfContentOwner نشان میدهد که اطلاعات کاربری مجوز درخواست، کاربر CMS YouTube را شناسایی میکند که از طرف مالک محتوای مشخصشده در مقدار پارامتر عمل میکند. این پارامتر برای شرکای محتوای YouTube است که مالک و مدیر کانالهای مختلف YouTube هستند. این ویژگی به مالکان محتوا اجازه میدهد یکبار اصالتسنجی کنند و به همه دادههای ویدیو و کانال خود دسترسی پیدا کنند، بدون اینکه نیاز باشد برای هر کانال بهطور جداگانه اعتبارنامههای اصالتسنجی ارائه دهند. حساب CMS که کاربر با آن اصالتسنجی میکند باید به مالک محتوای YouTube مشخصشده پیوند داده شده باشد. |
|
pageToken |
stringپارامتر pageToken صفحه خاصی را در مجموعه نتایج که باید برگردانده شود شناسایی میکند. در پاسخ API، ویژگیهای nextPageToken و prevPageToken صفحات دیگری را که میتوانند بازیابی شوند شناسایی میکنند. |
|
videoId |
stringپارامتر videoId مشخص میکند که درخواست باید فقط موارد فهرست پخشی را برگرداند که حاوی ویدیو مشخصشده هستند. |
|
متن درخواست
هنگام فراخوانی این روش، بدنه درخواست ارائه نکنید.
پاسخ
درصورت موفقیتآمیز بودن، این روش بدنه پاسخی با ساختار زیر برمیگرداند:
{
"kind": "youtube#playlistItemListResponse",
"etag": etag,
"nextPageToken": string,
"prevPageToken": string,
"pageInfo": {
"totalResults": integer,
"resultsPerPage": integer
},
"items": [
playlistItem Resource
]
}مشخصات
جدول زیر ویژگیهایی را که در این منبع ظاهر میشوند تعریف میکند:
| مشخصات | |
|---|---|
kind |
stringنوع منبع میانای برنامهسازی کاربردی را مشخص میکند. مقدار youtube#playlistItemListResponse خواهد بود. |
etag |
etagEtag این منبع. |
nextPageToken |
stringنشانهای که میتواند بهعنوان مقدار پارامتر pageToken برای بازیابی صفحه بعدی در مجموعه نتایج استفاده شود. |
prevPageToken |
stringنشانهای که میتواند بهعنوان مقدار پارامتر pageToken برای بازیابی صفحه قبلی در مجموعه نتایج استفاده شود. |
pageInfo |
objectشیء pageInfo اطلاعات صفحهبندی را برای مجموعه نتایج کپسولهسازی میکند. |
pageInfo.totalResults |
integerتعداد کل نتایج در مجموعه نتایج. |
pageInfo.resultsPerPage |
integerتعداد نتایج موجود در پاسخ میانای برنامهسازی کاربردی. |
items[] |
listفهرستی از موارد فهرست پخش که با معیارهای درخواست مطابقت دارند. |
مثالها
توجه: نمونههای کد زیر ممکن است نشاندهنده همه زبانهای برنامهنویسی پشتیبانیشده نباشد. برای مشاهده فهرست زبانهای پشتیبانیشده، مستندات کتابخانههای مشتری را ببینید.
رفتن
این نمونه کد متدplaylistItems.list میانای برنامهسازی کاربردی را برای بازیابی فهرست ویدیوهای بارگذاریشده در کانال منسوب به درخواست فرا میخواند. این کد همچنین روش channels.list را با پارامتر mine تنظیمشده روی true فراخوانی میکند تا شناسه فهرست پخش را که ویدیوهای بارگذاریشده کانال را شناسایی میکند بازیابی کند.
این مثال از کتابخانه Go client استفاده میکند.
package main import ( "fmt" "log" "google.golang.org/api/youtube/v3" ) // Retrieve playlistItems in the specified playlist func playlistItemsList(service *youtube.Service, part string, playlistId string, pageToken string) *youtube.PlaylistItemListResponse { call := service.PlaylistItems.List(part) call = call.PlaylistId(playlistId) if pageToken != "" { call = call.PageToken(pageToken) } response, err := call.Do() handleError(err, "") return response } // Retrieve resource for the authenticated user's channel func channelsListMine(service *youtube.Service, part string) *youtube.ChannelListResponse { call := service.Channels.List(part) call = call.Mine(true) response, err := call.Do() handleError(err, "") return response } func main() { client := getClient(youtube.YoutubeReadonlyScope) service, err := youtube.New(client) if err != nil { log.Fatalf("Error creating YouTube client: %v", err) } response := channelsListMine(service, "contentDetails") for _, channel := range response.Items { playlistId := channel.ContentDetails.RelatedPlaylists.Uploads // Print the playlist ID for the list of uploaded videos. fmt.Printf("Videos in list %s\r\n", playlistId) nextPageToken := "" for { // Retrieve next set of items in the playlist. playlistResponse := playlistItemsList(service, "snippet", playlistId, nextPageToken) for _, playlistItem := range playlistResponse.Items { title := playlistItem.Snippet.Title videoId := playlistItem.Snippet.ResourceId.VideoId fmt.Printf("%v, (%v)\r\n", title, videoId) } // Set the token to retrieve the next page of results // or exit the loop if all results have been retrieved. nextPageToken = playlistResponse.NextPageToken if nextPageToken == "" { break } fmt.Println() } } }
دات نت
نمونه کد زیر روشplaylistItems.list میانای برنامهسازی کاربردی را برای بازیابی فهرست ویدیوهای بارگذاریشده در کانال مرتبط با درخواست فراخوانی میکند. این کد همچنین متد channels.list را با پارامتر mine که روی true تنظیم شده است فراخوانی میکند تا شناسه فهرست پخشی را که ویدیوهای بارگذاریشده کانال را شناسایی میکند بازیابی کند.
این مثال از کتابخانه کارخواه.NET استفاده میکند.
using System; using System.IO; using System.Reflection; using System.Threading; using System.Threading.Tasks; using Google.Apis.Auth.OAuth2; using Google.Apis.Services; using Google.Apis.Upload; using Google.Apis.Util.Store; using Google.Apis.YouTube.v3; using Google.Apis.YouTube.v3.Data; namespace Google.Apis.YouTube.Samples { /// <summary> /// YouTube Data API v3 sample: retrieve my uploads. /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher. /// See https://developers.google.com/api-client-library/dotnet/get_started /// </summary> internal class MyUploads { [STAThread] static void Main(string[] args) { Console.WriteLine("YouTube Data API: My Uploads"); Console.WriteLine("============================"); try { new MyUploads().Run().Wait(); } catch (AggregateException ex) { foreach (var e in ex.InnerExceptions) { Console.WriteLine("Error: " + e.Message); } } Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } private async Task Run() { UserCredential credential; using (var stream = new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read)) { credential = await GoogleWebAuthorizationBroker.AuthorizeAsync( GoogleClientSecrets.Load(stream).Secrets, // This OAuth 2.0 access scope allows for read-only access to the authenticated // user's account, but not other types of account access. new[] { YouTubeService.Scope.YoutubeReadonly }, "user", CancellationToken.None, new FileDataStore(this.GetType().ToString()) ); } var youtubeService = new YouTubeService(new BaseClientService.Initializer() { HttpClientInitializer = credential, ApplicationName = this.GetType().ToString() }); var channelsListRequest = youtubeService.Channels.List("contentDetails"); channelsListRequest.Mine = true; // Retrieve the contentDetails part of the channel resource for the authenticated user's channel. var channelsListResponse = await channelsListRequest.ExecuteAsync(); foreach (var channel in channelsListResponse.Items) { // From the API response, extract the playlist ID that identifies the list // of videos uploaded to the authenticated user's channel. var uploadsListId = channel.ContentDetails.RelatedPlaylists.Uploads; Console.WriteLine("Videos in list {0}", uploadsListId); var nextPageToken = ""; while (nextPageToken != null) { var playlistItemsListRequest = youtubeService.PlaylistItems.List("snippet"); playlistItemsListRequest.PlaylistId = uploadsListId; playlistItemsListRequest.MaxResults = 50; playlistItemsListRequest.PageToken = nextPageToken; // Retrieve the list of videos uploaded to the authenticated user's channel. var playlistItemsListResponse = await playlistItemsListRequest.ExecuteAsync(); foreach (var playlistItem in playlistItemsListResponse.Items) { // Print information about each video. Console.WriteLine("{0} ({1})", playlistItem.Snippet.Title, playlistItem.Snippet.ResourceId.VideoId); } nextPageToken = playlistItemsListResponse.NextPageToken; } } } } }
Ruby
این نمونه روشplaylistItems.list میانای برنامهسازی کاربردی را برای بازیابی فهرست ویدیوهای بارگذاریشده
در کانال مرتبط با درخواست فراخوانی میکند. این کد همچنین روش channels.list را با پارامتر mine تنظیمشده روی true فراخوانی میکند تا شناسه فهرست پخش را که ویدیوهای بارگذاریشده کانال را شناسایی میکند، بازیابی کند.
این مثال از کتابخانه کارخواه Ruby استفاده میکند.
#!/usr/bin/ruby require 'rubygems' gem 'google-api-client', '>0.7' require 'google/api_client' require 'google/api_client/client_secrets' require 'google/api_client/auth/file_storage' require 'google/api_client/auth/installed_app' # This OAuth 2.0 access scope allows for read-only access to the authenticated # user's account, but not other types of account access. YOUTUBE_READONLY_SCOPE = 'https://www.googleapis.com/auth/youtube.readonly' YOUTUBE_API_SERVICE_NAME = 'youtube' YOUTUBE_API_VERSION = 'v3' def get_authenticated_service client = Google::APIClient.new( :application_name => $PROGRAM_NAME, :application_version => '1.0.0' ) youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION) file_storage = Google::APIClient::FileStorage.new("#{$PROGRAM_NAME}-oauth2.json") if file_storage.authorization.nil? client_secrets = Google::APIClient::ClientSecrets.load flow = Google::APIClient::InstalledAppFlow.new( :client_id => client_secrets.client_id, :client_secret => client_secrets.client_secret, :scope => [YOUTUBE_READONLY_SCOPE] ) client.authorization = flow.authorize(file_storage) else client.authorization = file_storage.authorization end return client, youtube end def main client, youtube = get_authenticated_service begin # Retrieve the "contentDetails" part of the channel resource for the # authenticated user's channel. channels_response = client.execute!( :api_method => youtube.channels.list, :parameters => { :mine => true, :part => 'contentDetails' } ) channels_response.data.items.each do |channel| # From the API response, extract the playlist ID that identifies the list # of videos uploaded to the authenticated user's channel. uploads_list_id = channel['contentDetails']['relatedPlaylists']['uploads'] # Retrieve the list of videos uploaded to the authenticated user's channel. next_page_token = '' until next_page_token.nil? playlistitems_response = client.execute!( :api_method => youtube.playlist_items.list, :parameters => { :playlistId => uploads_list_id, :part => 'snippet', :maxResults => 50, :pageToken => next_page_token } ) puts "Videos in list #{uploads_list_id}" # Print information about each video. playlistitems_response.data.items.each do |playlist_item| title = playlist_item['snippet']['title'] video_id = playlist_item['snippet']['resourceId']['videoId'] puts "#{title} (#{video_id})" end next_page_token = playlistitems_response.next_page_token end puts end rescue Google::APIClient::TransmissionError => e puts e.result.body end end main
خطاها
جدول زیر پیامهای خطایی را که ممکن است API در پاسخ به فراخوانی این روش برگرداند، مشخص میکند. لطفاً برای جزئیات بیشتر به سند پیام خطا مراجعه کنید.
| نوع خطا | جزئیات خطا | شرح |
|---|---|---|
forbidden (403) |
playlistItemsNotAccessible |
درخواست برای بازیابی فهرست پخش مشخصشده بهدرستی مجاز نشده است. |
forbidden (403) |
watchHistoryNotAccessible |
دادههای سابقه تماشا را نمیتوان ازطریق API بازیابی کرد. |
forbidden (403) |
watchLaterNotAccessible |
موارد موجود در فهرستهای پخش «تماشا در فرصتی دیگر» را نمیتوان ازطریق API بازیابی کرد. |
notFound (404) |
playlistNotFound |
فهرست پخش شناساییشده با پارامتر playlistId درخواست پیدا نشد. |
notFound (404) |
videoNotFound |
ویدیو شناساییشده با پارامتر videoId درخواست پیدا نشد. |
required (400) |
playlistIdRequired |
درخواست اشتراک مقداری برای ویژگی الزامی playlistId مشخص نمیکند. |
invalidValue (400) |
playlistOperationUnsupported |
این API از قابلیت فهرست کردن ویدیوها در فهرست پخش مشخصشده پشتیبانی نمیکند. برای مثال، نمیتوانید ویدیویی را در فهرست پخش «تماشا در فرصتی دیگر» خود فهرست کنید. |
امتحان کنید!
از APIs Explorer برای فراخوانی این API و دیدن درخواست و پاسخ API استفاده کنید.