تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

PlaylistItems: list

لعرض مجموعة من عناصر قائمة التشغيل التي تطابق معلمات طلب واجهة برمجة التطبيقات. يمكنك استرداد كل عناصر قائمة التشغيل في قائمة تشغيل محدّدة أو استعادة عنصر أو أكثر من عناصر قائمة التشغيل حسب أرقام التعريف الفريدة الخاصة بها.

تأثير الحصّة: إنّ استدعاء لهذه الطريقة لديه تكلفة حصة وحدة واحدة.

حالات الاستخدام الشائعة

طلب

طلب HTTP

GET https://www.googleapis.com/youtube/v3/playlistItems

المعلَمات

يسرد الجدول التالي المعلمات التي يدعمها طلب البحث هذا. جميع المعلمات المدرجة هي معلمات طلب بحث.

المعلَمات
المعلّمات المطلوبة
`part`	`string` تحدّد المعلمة `part` قائمة مفصولة بفواصل لخاصية مورد واحدة أو أكثر من `playlistItem` التي ستتضمّن استجابة واجهة برمجة التطبيقات. إذا حدّدت المعلّمة موقعًا يحتوي على مواقع فرعية، سيتم تضمين الخصائص الفرعية في الاستجابة. على سبيل المثال، في مورد `playlistItem`، تحتوي الخاصية `snippet` على العديد من الحقول، بما في ذلك الخصائص `title` و`description` و`position` و`resourceId`. وبالتالي، في حال ضبط `part=snippet`، ستحتوي استجابة واجهة برمجة التطبيقات على كل هذه المواقع. تحتوي القائمة التالية على أسماء `part` التي يمكنك تضمينها في قيمة المعلّمة: `contentDetails` `id` `snippet` `status`
الفلاتر (حدد معلمة واحدة من المعلمات التالية)
`id`	`string` تحدّد المعلمة `id` قائمة مفصولة بفواصل لمعرّف عنصر واحد أو أكثر من عناصر قائمة التشغيل الفريدة.
`playlistId`	`string` تحدد المعلمة `playlistId` المعرّف الفريد لقائمة التشغيل التي تريد استرداد عناصر قائمة التشغيل التابعة لها. تجدر الإشارة إلى أنه على الرغم من أن هذه معلمة اختيارية، فإن كل طلب لاسترداد عناصر قائمة التشغيل يجب أن يحدد قيمة للمعلمة `id` أو المعلمة `playlistId`.
المعلّمات الاختيارية
`maxResults`	`unsigned integer` تحدّد المعلمة `maxResults` الحد الأقصى لعدد العناصر التي يجب عرضها في مجموعة النتائج. القيم المقبولة هي `0` إلى `50`، بما في ذلك القيم الواقعة بينهما. القيمة التلقائية هي `5`.
`onBehalfOfContentOwner`	`string` لا يمكن استخدام هذه المعلّمة إلا في طلب مفوَّض بشكلٍ سليم. ملاحظة: هذه المعلمة مخصصة حصريًا لشركاء محتوى YouTube. تشير المعلمة `onBehalfOfContentOwner` إلى أن بيانات اعتماد تفويض الطلب تحدد مستخدم YouTube CMS الذي يتصرف نيابةً عن مالك المحتوى المحدد في قيمة المعلمة. هذه المعلمة مخصصة لشركاء محتوى 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()
		}
	}
}
my_uploads.go

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;
        }
      }
    }
  }
}
MyUploads.cs

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
my_uploads.rb

الأخطاء

يحدد الجدول التالي رسائل الخطأ التي يمكن أن تعرضها واجهة برمجة التطبيقات ردًا على استدعاء لهذه الطريقة. يرجى الاطلاع على وثائق رسالة الخطأ لمزيد من التفاصيل.

نوع الخطأ	تفاصيل الخطأ	الوصف
`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 لاستدعاء واجهة برمجة التطبيقات هذه والاطّلاع على طلب واجهة برمجة التطبيقات والاستجابة له.