PlaylistItems: list

Restituisce una raccolta di elementi della playlist che corrispondono ai parametri della richiesta API. Puoi recuperare tutti gli elementi della playlist in una playlist specificata o recuperare uno o più elementi della playlist in base ai relativi ID univoci.

Impatto sulla quota: una chiamata a questo metodo ha un costo della quota di 1 unità.

Casi d'uso comuni

Richiesta

Richiesta HTTP

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

Parametri

La tabella seguente elenca i parametri supportati da questa query. Tutti i parametri elencati sono parametri di query.

Parametri
Parametri obbligatori
part string
Il parametro part specifica un elenco separato da virgole di una o più proprietà della risorsa playlistItem che la risposta dell'API includerà.

Se il parametro identifica una proprietà che contiene proprietà figlio, queste verranno incluse nella risposta. Ad esempio, in una risorsa playlistItem, la proprietà snippet contiene numerosi campi, tra cui le proprietà title, description, position e resourceId. Di conseguenza, se imposti part=snippet, la risposta dell'API conterrà tutte queste proprietà.

L'elenco seguente contiene i nomi part che puoi includere nel valore del parametro:
  • contentDetails
  • id
  • snippet
  • status
Filtri (specifica esattamente uno dei seguenti parametri)
id string
Il parametro id specifica un elenco separato da virgole di uno o più ID univoci di elementi della playlist.
playlistId string
Il parametro playlistId specifica l'ID univoco della playlist per cui vuoi recuperare gli elementi della playlist. Tieni presente che, anche se si tratta di un parametro facoltativo, ogni richiesta di recupero degli elementi della playlist deve specificare un valore per il parametro id o per il parametro playlistId.
Parametri facoltativi
maxResults unsigned integer
Il parametro maxResults specifica il numero massimo di elementi da restituire nel set di risultati. I valori accettabili sono compresi tra 0 e 50, inclusi. Il valore predefinito è 5.
onBehalfOfContentOwner string
Questo parametro può essere utilizzato solo in una richiesta autorizzata correttamente. Nota: questo parametro è destinato esclusivamente ai partner di contenuti di YouTube.

Il parametro onBehalfOfContentOwner indica che le credenziali di autorizzazione della richiesta identificano un utente di YouTube CMS che agisce per conto del proprietario dei contenuti specificato nel valore del parametro. Questo parametro è destinato ai partner di contenuti di YouTube che possiedono e gestiscono molti canali YouTube diversi. Consente ai proprietari dei contenuti di eseguire l'autenticazione una sola volta e di accedere a tutti i dati dei video e dei canali, senza dover fornire le credenziali di autenticazione per ogni singolo canale. L'account CMS con cui l'utente esegue l'autenticazione deve essere collegato al proprietario dei contenuti di YouTube specificato.
pageToken string
Il parametro pageToken identifica una pagina specifica nel set di risultati da restituire. In una risposta dell'API, le proprietà nextPageToken e prevPageToken identificano altre pagine che potrebbero essere recuperate.
videoId string
Il parametro videoId specifica che la richiesta deve restituire solo gli elementi della playlist che contengono il video specificato.

Corpo della richiesta

Non fornire un corpo della richiesta quando chiami questo metodo.

Risposta

In caso di esito positivo, questo metodo restituisce un corpo della risposta con la seguente struttura:

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

Proprietà

La tabella seguente definisce le proprietà che appaiono in questa risorsa:

Proprietà
kind string
Identifica il tipo di risorsa API. Il valore sarà youtube#playlistItemListResponse.
etag etag
L'ETag di questa risorsa.
nextPageToken string
Il token che può essere utilizzato come valore del parametro pageToken per recuperare la pagina successiva nel set di risultati.
prevPageToken string
Il token che può essere utilizzato come valore del parametro pageToken per recuperare la pagina precedente nel set di risultati.
pageInfo object
L'oggetto pageInfo incapsula le informazioni di paginazione per il set di risultati.
pageInfo.totalResults integer
Il numero totale di risultati nel set di risultati.
pageInfo.resultsPerPage integer
Il numero di risultati inclusi nella risposta dell'API.
items[] list
Un elenco di elementi della playlist che corrispondono ai criteri della richiesta.

Esempi

Nota: gli esempi di codice seguenti potrebbero non rappresentare tutti i linguaggi di programmazione supportati. Consulta la documentazione delle librerie client per un elenco dei linguaggi supportati.

Vai

Questo esempio di codice chiama il metodo playlistItems.list dell'API per recuperare un elenco di video caricati sul canale associato alla richiesta. Il codice chiama anche il channels.list metodo con il mine parametro impostato su true per recuperare l'ID playlist che identifica i video caricati del canale.

Questo esempio utilizza la libreria client 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()
		}
	}
}

.NET

Il seguente esempio di codice chiama il metodo playlistItems.list dell'API per recuperare un elenco di video caricati sul canale associato alla richiesta. Il codice chiama anche il metodo channels.list con il parametro mine impostato su true per recuperare l'ID playlist che identifica i video caricati del canale.

Questo esempio utilizza la libreria client.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;
        }
      }
    }
  }
}

Ruby

Questo esempio chiama il metodo playlistItems.list dell'API per recuperare un elenco di video caricati sul canale associato alla richiesta. Il codice chiama anche il metodo channels.list con il parametro mine impostato su true per recuperare l'ID playlist che identifica i video caricati del canale.

Questo esempio utilizza la libreria client 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

Errori

La tabella seguente identifica i messaggi di errore che l'API potrebbe restituire in risposta a una chiamata a questo metodo. Per maggiori dettagli, consulta la documentazione sui messaggi di errore.

Tipo di errore Dettagli errore Descrizione
forbidden (403) playlistItemsNotAccessible La richiesta non è autorizzata correttamente per recuperare la playlist specificata.
forbidden (403) watchHistoryNotAccessible I dati della cronologia visualizzazioni non possono essere recuperati tramite l'API.
forbidden (403) watchLaterNotAccessible Gli elementi delle playlist "Guarda più tardi" non possono essere recuperati tramite l'API.
notFound (404) playlistNotFound Impossibile trovare la playlist identificata con il parametro playlistId della richiesta.
notFound (404) videoNotFound Impossibile trovare il video identificato con il parametro videoId della richiesta.
required (400) playlistIdRequired La richiesta di iscrizione non specifica un valore per la proprietà obbligatoria playlistId.
invalidValue (400) playlistOperationUnsupported L'API non supporta la possibilità di elencare i video nella playlist specificata. Ad esempio, non puoi elencare un video nella playlist Guarda più tardi.

Prova

Utilizza APIs Explorer per chiamare questa API e visualizzare la richiesta API e la risposta.