Videos: list

Zwraca listę filmów pasujących do parametrów żądania do interfejsu API.

Wpływ na limit: wywołanie tej metody ma koszt limitu wynoszący 1 jednostkę.

Typowe przypadki użycia

Prośba

Żądanie HTTP

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

Parametry

W tabeli poniżej znajdziesz parametry obsługiwane przez to zapytanie. Wszystkie wymienione parametry są parametrami zapytania.

Parametry
Parametry wymagane
part string
Parametr part określa oddzieloną przecinkami listę właściwości zasobu video, które będzie zawierać odpowiedź interfejsu API.

Jeśli parametr wskazuje właściwość zawierającą właściwości podrzędne, w odpowiedzi zostaną uwzględnione właściwości podrzędne. Na przykład w zasobie video właściwość snippet zawiera właściwości channelId, title, description, tags i categoryId. Jeśli więc ustawisz part=snippet, odpowiedź interfejsu API będzie zawierać wszystkie te właściwości.

Na poniższej liście znajdziesz nazwy pól part, które możesz uwzględnić w wartości parametru:
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
Filtry (określ dokładnie jeden z tych parametrów)
chart string
Parametr chart wskazuje wykres, który chcesz pobrać.

Akceptowane wartości:
id string
Parametr id określa rozdzieloną przecinkami listę identyfikatorów filmów w YouTube dla pobieranych zasobów. W zasobie video właściwość id określa identyfikator filmu.
myRating string
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Ustaw wartość tego parametru na like lub dislike, aby interfejs API zwracał tylko filmy polubione i nielubiane przez uwierzytelnionego użytkownika.

Akceptowane wartości to:
  • dislike – zwraca tylko te filmy, które nie spodobały się uwierzytelnionemu użytkownikowi.
  • like – zwraca tylko film, który został polubiony przez uwierzytelnionego użytkownika.
Parametry opcjonalne
hl string
Parametr hl informuje interfejs API, aby pobierał zlokalizowane metadane zasobów dla określonego języka aplikacji obsługiwanego przez witrynę YouTube. Wartość parametru musi być kodem języka znajdującym się na liście zwracanej przez metodę i18nLanguages.list.

Jeśli w danym języku dostępne są zlokalizowane szczegóły zasobów, obiekt snippet.localized zasobu będzie zawierał te wartości. Jeśli jednak zlokalizowane szczegóły nie są dostępne, obiekt snippet.localized będzie zawierał szczegóły zasobu w domyślnym języku zasobu.
maxHeight unsigned integer
Parametr maxHeight określa maksymalną wysokość umieszczonego odtwarzacza zwracanego we właściwości player.embedHtml. Możesz użyć tego parametru, aby określić, że zamiast domyślnych wymiarów kod do umieszczenia powinien używać wysokości odpowiedniej dla układu aplikacji. Jeśli podany jest też parametr maxWidth, odtwarzacz może być krótszy niż maxHeight, aby nie przekroczyć maksymalnej szerokości. Akceptowane wartości to od 72 do 8192 (włącznie).
maxResults unsigned integer
Parametr maxResults określa maksymalną liczbę elementów, które powinny zostać zwrócone w zbiorze wyników.

Uwaga: tego parametru można używać w połączeniu z parametrem myRating, ale nie można go używać w połączeniu z parametrem id. Akceptowane wartości to od 1 do 50 (włącznie). Wartością domyślną jest 5.
maxWidth unsigned integer
Parametr maxWidth określa maksymalną szerokość umieszczonego odtwarzacza zwróconego we właściwości player.embedHtml. Możesz użyć tego parametru, aby określić, że zamiast domyślnych wymiarów kod do umieszczenia powinien mieć szerokość odpowiednią do układu aplikacji.

Jeśli podany jest również parametr maxHeight, odtwarzacz może być węższy niż maxWidth, aby nie przekroczyć maksymalnej wysokości. Akceptowane wartości to od 72 do 8192 (włącznie).
onBehalfOfContentOwner string
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Uwaga: ten parametr jest przeznaczony wyłącznie dla dostawców treści w YouTube.

Parametr onBehalfOfContentOwner wskazuje, że dane uwierzytelniające żądanie identyfikują użytkownika YouTube CMS działającego w imieniu właściciela treści określonego w wartości parametru. Jest on przeznaczony dla dostawców treści w YouTube, którzy mają wiele różnych kanałów w YouTube i nimi zarządzają. Dzięki niej właściciele treści mogą jednorazowo uwierzytelnić się i uzyskiwać dostęp do wszystkich swoich filmów oraz danych dotyczących kanałów bez konieczności podawania danych uwierzytelniających dla każdego kanału z osobna. Konto CMS, za pomocą którego użytkownik uwierzytelnia się, musi być powiązane z określonym właścicielem treści YouTube.
pageToken string
Parametr pageToken wskazuje w zestawie wyników konkretną stronę, która ma zostać zwrócona. W odpowiedzi interfejsu API właściwości nextPageToken i prevPageToken wskazują inne strony, które można pobrać.

Uwaga: tego parametru można używać w połączeniu z parametrem myRating, ale nie można go używać w połączeniu z parametrem id.
regionCode string
Parametr regionCode informuje interfejs API, by wybrał wykres wideo dostępny w wybranym regionie. Tego parametru można używać tylko w połączeniu z parametrem chart. Jego wartością jest kod kraju zgodny ze standardem ISO 3166-1 alfa-2.
videoCategoryId string
Parametr videoCategoryId określa kategorię filmu, z której należy pobrać wykres. Tego parametru można używać tylko w połączeniu z parametrem chart. Domyślnie wykresy nie są ograniczone do konkretnej kategorii. Wartością domyślną jest 0.

Treść żądania

Nie podawaj treści żądania podczas wywoływania tej metody.

Odpowiedź

Jeśli operacja się uda, metoda zwróci odpowiedź o następującej strukturze:

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

Właściwości

Poniższa tabela przedstawia właściwości, które pojawiają się w tym zasobie:

Właściwości
kind string
Określa typ zasobu interfejsu API. Wartością będzie youtube#videoListResponse.
etag etag
ETag tego zasobu.
nextPageToken string
Token, który może być używany jako wartość parametru pageToken w celu pobrania następnej strony w zestawie wyników.
prevPageToken string
Token, który może być używany jako wartość parametru pageToken do pobierania poprzedniej strony w zestawie wyników.
pageInfo object
Obiekt pageInfo zawiera informacje o stronicowaniu zbioru wyników.
pageInfo.totalResults integer
Łączna liczba wyników w zestawie.
pageInfo.resultsPerPage integer
Liczba wyników uwzględnionych w odpowiedzi interfejsu API.
items[] list
Lista filmów spełniających kryteria żądania.

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 szczegółów znajdziesz w dokumentacji komunikatów o błędach.

Typ błędu Szczegóły błędu Opis
badRequest (400) videoChartNotFound Żądany wykres wideo nie jest obsługiwany lub niedostępny.
forbidden (403) forbidden Żądanie nie ma poprawnie uprawnień dostępu do pliku wideo lub informacji o przetwarzaniu. Pamiętaj, że części fileDetails, processingDetails i suggestions są dostępne tylko dla właściciela tego filmu.
forbidden (403) forbidden Żądanie nie może uzyskać dostępu do informacji o ocenach użytkowników. Ten błąd może wystąpić, ponieważ żądanie nie jest prawidłowo autoryzowane do użycia parametru myRating.
notFound (404) videoNotFound Nie można znaleźć filmu, który próbujesz odzyskać. Sprawdź, czy wartość parametru id żądania jest prawidłowa.

Wypróbuj

Użyj interfejsu APIs Explorer, aby wywołać ten interfejs API i wyświetlić żądanie oraz odpowiedź interfejsu API.