Zwraca kolekcję elementów playlisty pasujących do parametrów żądania do interfejsu API. Możesz pobrać wszystkie elementy playlisty z tej playlisty lub jej elementy według unikalnych identyfikatorów.
Wpływ limitu: wywołanie tej metody ma limit limitu wynoszący 1 jednostkę.
Typowe przypadki użycia
Żądanie
Żądanie HTTP
GET https://www.googleapis.com/youtube/v3/playlistItems
Parametry
W poniższej tabeli podano parametry obsługiwane przez to zapytanie. Wszystkie wymienione parametry są parametrami zapytania.
Parametry | ||
---|---|---|
Parametry wymagane | ||
part |
string Parametr part określa rozdzieloną przecinkami listę co najmniej jednej właściwości zasobu playlistItem , która ma być uwzględniona w odpowiedzi interfejsu API.Jeśli parametr wskazuje właściwość zawierającą właściwości podrzędne, zostaną one uwzględnione w odpowiedzi. Na przykład w zasobie playlistItem właściwość snippet zawiera wiele pól, w tym właściwości title , description , position i resourceId . Jeśli ustawisz part=snippet , odpowiedź interfejsu API będzie zawierać wszystkie te właściwości.Ta lista zawiera nazwy part , które możesz uwzględnić w wartości parametru:
|
|
Filtry (podaj jeden z tych parametrów) | ||
id |
string Parametr id określa rozdzieloną przecinkami listę co najmniej 1 unikalnego identyfikatora elementu playlisty. |
|
playlistId |
string Parametr playlistId określa unikalny identyfikator playlisty, w której przypadku chcesz pobierać elementy. Pamiętaj, że choć jest to parametr opcjonalny, każde żądanie pobrania elementów playlisty musi mieć określoną wartość parametru id lub playlistId . |
|
Parametry opcjonalne | ||
maxResults |
unsigned integer Parametr maxResults określa maksymalną liczbę elementów, które powinny zostać zwrócone w zestawie wyników. Akceptowane wartości to 0 –50 (włącznie). Wartością domyślną jest 5 . |
|
onBehalfOfContentOwner |
string Ten parametr może być używany tylko w poprawnie autoryzowanym żądaniu. Uwaga: ten parametr jest przeznaczony wyłącznie dla partnerów w sieci reklamowej YouTube. Parametr onBehalfOfContentOwner wskazuje, że dane logowania żądania autoryzacji to użytkownik YouTube, który działa w imieniu właściciela treści określonego w wartości parametru. Ten parametr jest przeznaczony dla partnerów w sieci reklamowej YouTube, którzy mają wiele kanałów YouTube i zarządzają nimi. Umożliwia właścicielom treści uwierzytelnianie tylko raz oraz dostęp do wszystkich filmów i kanałów bez konieczności podawania danych uwierzytelniających dla każdego kanału z osobna. Konto CMS, za pomocą którego użytkownik się uwierzytelni, musi być połączone z określonym właścicielem treści w YouTube. |
|
pageToken |
string Parametr pageToken wskazuje konkretną stronę w zestawie wyników, która powinna zostać zwrócona. W odpowiedzi interfejsu API właściwości nextPageToken i prevPageToken wskazują inne strony, które można pobrać. |
|
videoId |
string Parametr videoId wskazuje, że żądanie powinno zwracać tylko elementy playlisty, które zawierają określony film. |
Treść żądania
Podczas wywoływania tej metody nie podawaj treści żądania.
Odpowiedź
Jeśli operacja się uda, metoda zwróci odpowiedź w następującym formacie:
{ "kind": "youtube#playlistItemListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ playlistItem Resource ] }
Usługi
Poniższa tabela określa właściwości, które pojawiają się w tym zasobie:
Usługi | |
---|---|
kind |
string Określa typ zasobu interfejsu API. Wartość będzie wynosić youtube#playlistItemListResponse . |
etag |
etag Otagowanie tego zasobu. |
nextPageToken |
string Token, który może zostać użyty jako wartość parametru pageToken , by pobrać następną stronę z zestawu wyników. |
prevPageToken |
string Token, którego można użyć jako wartości parametru pageToken w celu pobrania poprzedniej strony z zestawu wyników. |
pageInfo |
object Obiekt pageInfo zawiera informacje o stronicowaniu dla zestawu wyników. |
pageInfo.totalResults |
integer Łączna liczba wyników w zestawie wyników. |
pageInfo.resultsPerPage |
integer Liczba wyników zawartych w odpowiedzi interfejsu API. |
items[] |
list Lista elementów playlist, które spełniają kryteria żądania. |
Przykłady
Uwaga: poniższe przykłady kodu mogą nie prezentować wszystkich obsługiwanych języków programowania. Listę obsługiwanych języków znajdziesz w dokumentacji bibliotek klienta.
Go
Ten przykładowy kod wywołuje metodęplaylistItems.list
interfejsu API, aby pobrać listę filmów przesłanych na kanał powiązany z żądaniem. Kod wywołuje też metodę channels.list
, w której parametr mine
jest ustawiony na true
, by pobrać identyfikator playlisty, która identyfikuje przesłane filmy kanału.
W tym przykładzie użyto biblioteki klienta 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
Ten przykładowy kod wywołuje metodęplaylistItems.list
interfejsu API, aby pobrać listę filmów przesłanych na kanał powiązany z żądaniem. Kod wywołuje też metodę channels.list
z parametrem mine
ustawionym na true
, by pobrać identyfikator playlisty, który identyfikuje przesłane filmy.
W tym przykładzie użyto biblioteki klienta.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
W tym przykładzie wywołana jest metodaplaylistItems.list
interfejsu API, która pobiera listę filmów przesłanych na kanał powiązany z żądaniem. Kod wywołuje też metodę channels.list
z parametrem mine
ustawionym na true
, by pobrać identyfikator playlisty, który identyfikuje przesłane filmy.
W tym przykładzie użyto biblioteki klienta 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
Błędy
W tabeli poniżej znajdziesz komunikaty o błędach, które interfejs API może zwrócić w odpowiedzi na wywołanie tej metody. Więcej informacji znajdziesz w dokumentacji komunikatów o błędach.
Typ błędu | Szczegóły błędu | Opis |
---|---|---|
forbidden (403) |
playlistItemsNotAccessible |
Żądanie nie jest prawidłowo autoryzowane do pobrania określonej playlisty. |
forbidden (403) |
watchHistoryNotAccessible |
Danych historii oglądania nie można pobrać za pomocą interfejsu API. |
forbidden (403) |
watchLaterNotAccessible |
Za pomocą interfejsu API nie można pobierać elementów z playlist „Do obejrzenia”. |
notFound (404) |
playlistNotFound |
Nie można znaleźć playlisty zidentyfikowanej za pomocą parametru playlistId żądania. |
notFound (404) |
videoNotFound |
Nie można znaleźć filmu wskazanego w parametrze videoId żądania. |
required (400) |
playlistIdRequired |
Prośba o subskrypcję nie określa wartości wymaganej właściwości playlistId . |
invalidValue (400) |
playlistOperationUnsupported |
Interfejs API nie obsługuje wyświetlania listy filmów z określonej playlisty. Na przykład nie możesz dodać filmu do playlisty Do obejrzenia. |
Wypróbuj
Użyj APIs Explorer, aby wywołać ten interfejs API i wyświetlić żądanie oraz odpowiedź interfejsu API.