تعرض هذه الطريقة مجموعة من عناصر قوائم التشغيل التي تطابق مَعلمات طلب بيانات من واجهة برمجة التطبيقات. يمكنك استرداد جميع عناصر قائمة التشغيل في قائمة تشغيل محدّدة أو استرداد عنصر واحد أو أكثر من عناصر قائمة التشغيل حسب معرّفاتها الفريدة.
تأثير الحصة: تبلغ تكلفة الحصة لطلب هذه الطريقة وحدة واحدة.
حالات الاستخدام الشائعة
طلب
طلب HTTP
GET https://www.googleapis.com/youtube/v3/playlistItems
المعلمات
يسرد الجدول التالي المَعلمات التي يتيحها طلب البحث هذا. وجميع المَعلمات المُدرَجة هي مَعلمات طلب بحث.
| المعلمات | ||
|---|---|---|
| المعلمات المطلوبة | ||
part |
stringتحدّد المَعلمة part قائمة قيم مفصولة بفاصلة تتضمّن سمة واحدة أو أكثر من سمات مورد playlistItem التي سيتضمّنها الردّ من واجهة برمجة التطبيقات.إذا كانت المَعلمة تحدّد سمة تحتوي على سمات فرعية، سيتم تضمين السمات الفرعية في الردّ. على سبيل المثال، في مصدر 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 إلى أنّ بيانات الاعتماد الخاصة بتفويض الطلب تحدّد مستخدمًا في نظام إدارة محتوى YouTube يتصرّف نيابةً عن مالك المحتوى المحدّد في قيمة المَعلمة. هذه المَعلمة مخصّصة لشركاء المحتوى على YouTube الذين يملكون قنوات مختلفة على YouTube ويديرونها. تسمح هذه المَعلمة لمالكي المحتوى بالمصادقة مرة واحدة والوصول إلى جميع بيانات الفيديوهات والقنوات، بدون الحاجة إلى تقديم بيانات اعتماد المصادقة لكل قناة فردية. يجب ربط حساب نظام إدارة المحتوى الذي يصادق المستخدم من خلاله بمالك المحتوى المحدّد على YouTube. |
|
pageToken |
stringتحدّد المَعلمة pageToken صفحة معيّنة في مجموعة النتائج يجب عرضها. في الردّ من واجهة برمجة التطبيقات، تحدّد السمتان 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 |
etagعلامة ETag لهذا المصدر. |
nextPageToken |
stringالرمز المميّز الذي يمكن استخدامه كقيمة للمَعلمة pageToken لاسترداد الصفحة التالية في مجموعة النتائج. |
prevPageToken |
stringالرمز المميّز الذي يمكن استخدامه كقيمة للمَعلمة pageToken لاسترداد الصفحة السابقة في مجموعة النتائج. |
pageInfo |
objectيغلّف عنصر pageInfo معلومات تقسيم الصفحات لمجموعة النتائج. |
pageInfo.totalResults |
integerإجمالي عدد النتائج في مجموعة النتائج. |
pageInfo.resultsPerPage |
integerعدد النتائج المُدرَجة في الردّ من واجهة برمجة التطبيقات. |
items[] |
listقائمة بعناصر قائمة التشغيل التي تطابق معايير الطلب. |
أمثلة
ملاحظة: قد لا تمثّل عيّنات التعليمات البرمجية التالية كل لغات البرمجة المتوافقة. يُرجى الاطّلاع على مستندات مكتبات البرامج للاطّلاع على قائمة باللغات المتوافقة.
انتقال
تطلب عينة التعليمات البرمجية هذه الطريقةplaylistItems.list من واجهة برمجة التطبيقات لاسترداد قائمة بـ
الفيديوهات التي تم تحميلها إلى القناة المرتبطة بالطلب. تطلب التعليمات البرمجية أيضًا الطريقة channels.list
مع ضبط المَعلمة mine على true لاسترداد رقم تعريف قائمة التشغيل الذي يحدّد
الفيديوهات التي تم تحميلها إلى القناة.
يستخدم هذا المثال مكتبة برامج Go.
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() } } }
NET.
تطلب عينة التعليمات البرمجية التالية الطريقة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
الأخطاء
يحدّد الجدول التالي رسائل الخطأ التي يمكن أن تعرضها واجهة برمجة التطبيقات ردًا على طلب هذه الطريقة. يُرجى الاطّلاع على مستندات رسائل الخطأ لمزيد من التفاصيل.
| نوع الخطأ | تفاصيل الخطأ | الوصف |
|---|---|---|
forbidden (403) |
playlistItemsNotAccessible |
الطلب غير مُفوَّض بشكلٍ صحيح لاسترداد قائمة التشغيل المحدّدة. |
forbidden (403) |
watchHistoryNotAccessible |
لا يمكن استرداد بيانات سجلّ المشاهدة من خلال واجهة برمجة التطبيقات. |
forbidden (403) |
watchLaterNotAccessible |
لا يمكن استرداد العناصر في قوائم تشغيل "المشاهدة لاحقًا" من خلال واجهة برمجة التطبيقات. |
notFound (404) |
playlistNotFound |
يتعذّر العثور على قائمة التشغيل المحدّدة باستخدام المَعلمة playlistId في الطلب. |
notFound (404) |
videoNotFound |
يتعذّر العثور على الفيديو المحدّد باستخدام المَعلمة videoId في الطلب. |
required (400) |
playlistIdRequired |
لا يحدّد طلب الاشتراك قيمة للسمة المطلوبة playlistId. |
invalidValue (400) |
playlistOperationUnsupported |
لا تتيح واجهة برمجة التطبيقات إمكانية إدراج الفيديوهات في قائمة التشغيل المحدّدة. على سبيل المثال، لا يمكنك إدراج فيديو في قائمة التشغيل "المشاهدة لاحقًا". |
جرِّبها الآن.
استخدِم APIs Explorer لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب بيانات من واجهة برمجة التطبيقات والردّ.