PlaylistItems: list

API 요청 매개변수와 일치하는 재생목록 항목의 컬렉션을 반환합니다. 지정된 재생목록의 모든 항목을 검색하거나 고유 ID를 통해 하나 또는 여러 개의 재생목록 항목을 검색할 수 있습니다.

할당량 영향: 이 메서드에 대한 호출의 할당량 비용은 1단위입니다.

일반적인 사용 사례

요청

HTTP 요청

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

매개변수

다음 표에는 이 쿼리가 지원하는 매개변수가 나와 있습니다. 나열된 모든 매개변수는 쿼리 매개변수입니다.

매개변수
필수 매개변수
part	string part 매개변수는 API 응답이 포함하는 playlistItem 리소스 속성 하나 이상의 쉼표로 구분된 목록을 지정합니다. 매개변수가 하위 속성을 포함하는 속성을 식별하는 경우 하위 속성이 응답에 포함됩니다. 예를 들어 playlistItem 리소스에서 snippet 속성에는 title, description, position, resourceId 속성을 비롯한 여러 필드가 포함되어 있습니다. 따라서 part=snippet를 설정하면 API 응답에 이러한 모든 속성이 포함됩니다. 다음 목록에는 매개변수 값에 포함할 수 있는 part 이름이 포함되어 있습니다. contentDetails id snippet status
필터(다음 매개변수 중 하나를 정확하게 지정)
id	string id 매개변수는 쉼표로 구분된 하나 이상의 고유한 재생목록 항목 ID 목록을 지정합니다.
playlistId	string playlistId 매개변수는 재생목록 항목을 검색하려는 재생목록의 고유 ID를 지정합니다. 이 매개변수는 선택적 매개변수이지만 재생목록 항목을 검색하는 모든 요청은 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 요청 기준과 일치하는 재생목록 항목의 목록입니다.

예

참고: 다음 코드 샘플은 지원되는 일부 프로그래밍 언어를 나타내지 않을 수 있습니다. 지원되는 언어 목록은 클라이언트 라이브러리 문서를 참고하세요.

Go

이 코드 샘플은 API의 playlistItems.list 메서드를 호출하여 요청과 연결된 채널에 업로드된 동영상 목록을 검색합니다. 또한 이 코드는 mine 매개변수가 true로 설정된 채널의 channels.list 메서드를 호출하여 채널의 업로드된 동영상을 식별하는 재생목록 ID를 검색합니다.

이 예에서는 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

다음 코드 샘플은 API의 playlistItems.list 메서드를 호출하여 요청과 연결된 채널에 업로드된 동영상 목록을 검색합니다. 또한 이 코드는 mine 매개변수가 true로 설정된 채널의 channels.list 메서드를 호출하여 채널의 업로드된 동영상을 식별하는 재생목록 ID를 검색합니다.

.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

이 샘플은 API의 playlistItems.list 메서드를 호출하여 요청과 연결된 채널에 업로드된 동영상 목록을 검색합니다. 또한 이 코드는 mine 매개변수가 true로 설정된 channels.list 메서드를 호출하여 채널의 업로드된 동영상을 식별하는 재생목록 ID를 검색합니다.

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 요청 및 응답을 확인하세요.