‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

PlaylistItems: list

مجموعه‌ای از عناصر فهرست پخش را که با پارامترهای درخواست API مطابقت دارند برمی‌گرداند. می‌توانید همه موارد فهرست پخش را در یک فهرست پخش مشخص بازیابی کنید یا یک یا چند مورد فهرست پخش را با شناسه یکتای آن‌ها بازیابی کنید.

تأثیر سهمیه: فراخوانی این روش هزینه سهمیه ۱ واحدی دارد.

موارد استفاده رایج

درخواست

درخواست HTTP

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

پارامترها

جدول زیر پارامترهایی را که این پُرسمان پشتیبانی می‌کند فهرست می‌کند. همه پارامترهای فهرست‌شده پارامترهای پُرسمان هستند.

پارامترها
پارامترهای الزامی
`part`	`string` پارامتر `part` فهرستی جداشده با کاما از یک یا چند ویژگی منبع `playlistItem` را مشخص می‌کند که پاسخ API شامل آن خواهد بود. اگر پارامتر ویژگی‌ای را شناسایی کند که حاوی ویژگی‌های فرزند است، ویژگی‌های فرزند در پاسخ گنجانده خواهند شد. برای مثال، در منبع `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` نشان می‌دهد که اطلاعات کاربری مجوز درخواست، کاربر 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`	`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 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()
		}
	}
}
my_uploads.go

دات نت

نمونه کد زیر روش 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

خطاها

جدول زیر پیام‌های خطایی را که ممکن است 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 استفاده کنید.

PlaylistItems: list با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.