Esta página foi traduzida pela API Cloud Translation.

PlaylistItems: list

Retorna um conjunto de itens da playlist que correspondem aos parâmetros da solicitação de API. Você pode recuperar todos os itens da playlist em uma playlist especificada ou recuperar um ou mais itens da playlist por seus IDs exclusivos.

Impacto na cota:uma chamada para esse método tem um custo de cota de uma unidade.

Casos de uso comuns

Solicitação

Solicitação HTTP

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

Parâmetros

A tabela a seguir lista os parâmetros compatíveis com essa consulta. Todos os parâmetros listados são os parâmetros de consulta.

Parâmetros
Parâmetros obrigatórios
`part`	`string` O parâmetro `part` especifica uma lista separada por vírgulas de uma ou mais propriedades de recurso `playlistItem` que a resposta da API incluirá. Se o parâmetro identificar uma propriedade que contenha propriedades filhas, elas serão incluídas na resposta. Por exemplo, em um recurso `playlistItem`, a propriedade `snippet` contém vários campos, incluindo as propriedades `title`, `description`, `position` e `resourceId`. Dessa forma, se você definir `part=snippet`, a resposta da API vai conter todas essas propriedades. A lista a seguir contém os nomes de `part` que podem ser incluídos no valor de parâmetro: `contentDetails` `id` `snippet` `status`
Filtros (especifique exatamente um dos seguintes parâmetros)
`id`	`string` O parâmetro `id` especifica uma lista separada por vírgulas de um ou mais IDs exclusivos de itens da playlist.
`playlistId`	`string` O parâmetro `playlistId` especifica o ID exclusivo da playlist em que você quer recuperar itens. Embora este seja um parâmetro opcional, toda solicitação para recuperar itens da playlist precisa especificar um valor para o parâmetro `id` ou `playlistId`.
Parâmetros opcionais
`maxResults`	`unsigned integer` O parâmetro `maxResults` especifica o número máximo de itens que precisam ser retornados no conjunto de resultados. Os valores aceitos são de `0` a `50`, inclusive. O valor padrão é `5`.
`onBehalfOfContentOwner`	`string` Esse parâmetro só pode ser usado em uma solicitação autorizada corretamente. Observação:esse parâmetro é destinado exclusivamente a parceiros de conteúdo do YouTube. O parâmetro `onBehalfOfContentOwner` indica que as credenciais de autorização da solicitação identificam um usuário do CMS do YouTube que atua em nome do proprietário do conteúdo especificado no valor do parâmetro. Este parâmetro destina-se a parceiros de conteúdo do YouTube que possuem e gerenciam vários canais do YouTube diferentes. Ele permite que os proprietários de conteúdo autentiquem uma vez e tenham acesso a todos os dados de seu canal e de seus vídeos sem ter que fornecer credenciais de autenticação para cada canal. A conta do CMS com a qual o usuário autentica deve estar vinculada ao proprietário do conteúdo do YouTube especificado.
`pageToken`	`string` O parâmetro `pageToken` identifica uma página específica no conjunto de resultados que precisa ser retornada. Em uma resposta da API, as propriedades `nextPageToken` e `prevPageToken` identificam outras páginas que podem ser recuperadas.
`videoId`	`string` O parâmetro `videoId` especifica que a solicitação precisa retornar apenas os itens da playlist que contêm o vídeo especificado.

Corpo da solicitação

Não forneça um corpo de solicitação ao chamar este método.

Resposta

Se for bem-sucedido, esse método retornará um corpo de resposta com esta estrutura:

{
  "kind": "youtube#playlistItemListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    playlistItem Resource
  ]
}

Propriedades

A tabela a seguir define as propriedades que aparecem neste recurso:

Propriedades
`kind`	`string` Identifica o tipo do recurso da API. O valor será `youtube#playlistItemListResponse`.
`etag`	`etag` A ETag deste recurso.
`nextPageToken`	`string` O token que pode ser usado como o valor do parâmetro `pageToken` para recuperar a próxima página no conjunto de resultados.
`prevPageToken`	`string` O token que pode ser usado como o valor do parâmetro `pageToken` para recuperar a página anterior do conjunto de resultados.
`pageInfo`	`object` O objeto `pageInfo` encapsula informações de paginação para o conjunto de resultados.
`pageInfo.totalResults`	`integer` O número total de resultados no conjunto de resultados.
`pageInfo.resultsPerPage`	`integer` O número de resultados incluídos na resposta da API.
`items[]`	`list` Uma lista de itens da playlist que correspondem aos critérios da solicitação.

Exemplos

Observação:as amostras de código a seguir podem não representar todas as linguagens de programação compatíveis. Consulte a documentação bibliotecas clientes para uma lista das linguagens suportadas.

Go

Nesta amostra de código, o método playlistItems.list da API é chamado para recuperar uma lista de vídeos enviados ao canal associado à solicitação. O código também chama o método channels.list com o parâmetro mine definido como true para recuperar o ID da playlist que identifica os vídeos enviados do canal.

Este exemplo usa a biblioteca de cliente 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

O exemplo de código a seguir chama o método playlistItems.list da API para recuperar uma lista de vídeos enviados ao canal associado à solicitação. O código também chama o método channels.list com o parâmetro mine definido como true para recuperar o ID da playlist que identifica os vídeos enviados do canal.

Este exemplo usa a biblioteca cliente .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

Este exemplo chama o método playlistItems.list da API para recuperar uma lista de vídeos enviados ao canal associado à solicitação. O código também chama o método channels.list com o parâmetro mine definido como true para recuperar o ID da playlist que identifica os vídeos enviados do canal.

Este exemplo utiliza a biblioteca cliente 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

Erros

A tabela a seguir identifica mensagens de erro que a API pode retornar em resposta a uma chamada para esse método. Consulte a documentação mensagem de erro para mais detalhes.

Tipo de erro	Detalhe do erro	Descrição
`forbidden (403)`	`playlistItemsNotAccessible`	A solicitação não está devidamente autorizada a recuperar a playlist especificada.
`forbidden (403)`	`watchHistoryNotAccessible`	Não é possível recuperar os dados do histórico de exibição pela API.
`forbidden (403)`	`watchLaterNotAccessible`	Os itens das playlists "Assistir mais tarde" não podem ser recuperados pela API.
`notFound (404)`	`playlistNotFound`	A playlist identificada com o parâmetro `playlistId` da solicitação não pode ser encontrada.
`notFound (404)`	`videoNotFound`	O vídeo identificado com o parâmetro `videoId` da solicitação não foi encontrado.
`required (400)`	`playlistIdRequired`	A solicitação de assinatura não especifica um valor para a propriedade `playlistId` necessária.
`invalidValue (400)`	`playlistOperationUnsupported`	A API não é compatível com a capacidade de listar vídeos na playlist especificada. Por exemplo, não é possível listar um vídeo da playlist "Assistir mais tarde".

Confira!

Use o APIs Explorer para chamar a API e ver a solicitação e a resposta da API.