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

בדוגמה הזו אנחנו משתמשים בספריית הלקוחות של Rubby.

#!/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 ואת התשובה.