PlaylistItems: list

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

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

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

درخواست

درخواست HTTP

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

مولفه های

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

مولفه های
پارامترهای مورد نیاز
part	string پارامتر part یک لیست جدا شده با کاما از یک یا چند ویژگی منبع playlistItem را مشخص می کند که پاسخ API شامل آن می شود. اگر پارامتر خاصیتی را مشخص کند که حاوی ویژگی های فرزند است، ویژگی های فرزند در پاسخ گنجانده می شود. به عنوان مثال، در یک منبع playlistItem ، ویژگی snippet شامل فیلدهای متعددی است، از جمله ویژگی‌های title ، description ، position و resourceId . به این ترتیب، اگر part=snippet را تنظیم کنید، پاسخ API حاوی تمام آن ویژگی ها خواهد بود. لیست زیر شامل نام 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 را مالک و مدیریت می‌کنند. این به صاحبان محتوا امکان می‌دهد یک بار احراز هویت کنند و به تمام داده‌های ویدیویی و کانال خود دسترسی داشته باشند، بدون اینکه نیازی به ارائه اعتبارنامه احراز هویت برای هر کانال جداگانه داشته باشند. حساب 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 نوع منبع API را مشخص می کند. مقدار youtube#playlistItemListResponse خواهد بود.
etag	etag Etag این منبع
nextPageToken	string نشانه ای که می تواند به عنوان مقدار پارامتر pageToken برای بازیابی صفحه بعدی در مجموعه نتایج استفاده شود.
prevPageToken	string نشانه ای که می تواند به عنوان مقدار پارامتر pageToken برای بازیابی صفحه قبلی در مجموعه نتایج استفاده شود.
pageInfo	object شی pageInfo اطلاعات صفحه‌بندی را برای مجموعه نتایج کپسوله می‌کند.
pageInfo. totalResults	integer تعداد کل نتایج در مجموعه نتایج.
pageInfo. resultsPerPage	integer تعداد نتایج موجود در پاسخ API.
items[]	list فهرستی از موارد لیست پخش که با معیارهای درخواست مطابقت دارند.

مثال ها

توجه: نمونه کد زیر ممکن است نشان دهنده همه زبان های برنامه نویسی پشتیبانی شده نباشد. برای فهرستی از زبان های پشتیبانی شده، به مستندات کتابخانه های سرویس گیرنده مراجعه کنید.

برو

این نمونه کد از روش playlistItems.list API فراخوانی می کند تا فهرستی از ویدیوهای آپلود شده در کانال مرتبط با درخواست را بازیابی کند. این کد همچنین روش 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

.خالص

نمونه کد زیر روش playlistItems.list API را فراخوانی می کند تا فهرستی از ویدیوهای آپلود شده در کانال مرتبط با درخواست را بازیابی کند. این کد همچنین روش channels.list را با پارامتر mine که روی true تنظیم شده است فراخوانی می‌کند تا شناسه لیست پخشی که ویدیوهای آپلود شده کانال را شناسایی می‌کند، بازیابی کند.

این مثال از کتابخانه سرویس گیرنده دات نت استفاده می کند.

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

روبی

این نمونه از روش playlistItems.list API فراخوانی می‌کند تا فهرستی از ویدیوهای آپلود شده در کانال مرتبط با درخواست را بازیابی کند. این کد همچنین روش 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 استفاده کنید.