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 |
stringIl 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:
|
|
| Filtri (specifica esattamente uno dei seguenti parametri) | ||
id |
stringIl parametro id specifica un elenco separato da virgole di uno o più ID univoci di elementi della playlist. |
|
playlistId |
stringIl 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 integerIl 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 |
stringQuesto 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 |
stringIl 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 |
stringIl 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 |
stringIdentifica il tipo di risorsa API. Il valore sarà youtube#playlistItemListResponse. |
etag |
etagL'ETag di questa risorsa. |
nextPageToken |
stringIl token che può essere utilizzato come valore del parametro pageToken per recuperare la pagina successiva nel set di risultati. |
prevPageToken |
stringIl token che può essere utilizzato come valore del parametro pageToken per recuperare la pagina precedente nel set di risultati. |
pageInfo |
objectL'oggetto pageInfo incapsula le informazioni di paginazione per il set di risultati. |
pageInfo.totalResults |
integerIl numero totale di risultati nel set di risultati. |
pageInfo.resultsPerPage |
integerIl numero di risultati inclusi nella risposta dell'API. |
items[] |
listUn 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 metodoplaylistItems.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 metodoplaylistItems.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 metodoplaylistItems.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.