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, תגובת ה-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 ה-e של המשאב הזה.
nextPageToken	string האסימון שיכול לשמש כערך של הפרמטר pageToken כדי לאחזר את הדף הבא בקבוצת התוצאות.
prevPageToken	string האסימון שיכול לשמש כערך הפרמטר pageToken כדי לאחזר את הדף הקודם בקבוצת התוצאות.
pageInfo	object האובייקט pageInfo כולל את פרטי החלוקה לדפים של קבוצת התוצאות.
pageInfo.totalResults	integer המספר הכולל של התוצאות בקבוצת התוצאות.
pageInfo.resultsPerPage	integer מספר התוצאות שכלולות בתגובת ה-API.
items[]	list רשימה של פריטים בפלייליסט שעומדים בקריטריונים של הבקשה.

דוגמאות

הערה: יכול להיות שדוגמאות הקוד הבאות לא מייצגות את כל שפות התכנות הנתמכות. כדי לקבל רשימה של שפות נתמכות, אפשר לעיין במסמכי התיעוד של ספריות הלקוח.

Go

דוגמת הקוד הזו מפעילה את השיטה 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

‎.NET

דוגמת הקוד הבאה מפעילה את השיטה playlistItems.list של ה-API כדי לאחזר רשימה של סרטונים שהועלו לערוץ המשויך לבקשה. בנוסף, הקוד מפעיל את השיטה 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 של ה-API כדי לאחזר רשימה של סרטונים שהועלו לערוץ המשויך לבקשה. בנוסף, הקוד מפעיל את השיטה channels.list עם הערך true של הפרמטר mine, כדי לאחזר את מזהה הפלייליסט שמזהה את הסרטונים שהועלו בערוץ.

בדוגמה הזו נשתמש בספריית הלקוח של 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.