Videos: list

Zwraca listę filmów, które pasują do parametrów żądania do interfejsu API.

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

Częste zastosowania

Żądanie

Żądanie HTTP

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

Parametry

W tabeli poniżej znajdziesz listę parametrów obsługiwanych przez to zapytanie. Wszystkie wymienione parametry to parametry zapytania.

Parametry
Parametry wymagane
part string
Parametr part określa rozdzieloną przecinkami listę co najmniej 1 właściwości zasobu video, które mają być uwzględnione w odpowiedzi interfejsu API.

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

Poniżej znajdziesz listę nazw part, które możesz uwzględnić w wartości parametru:
  • brandPartner
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
Filtry (określ dokładnie 1 z tych parametrów)
chart string
Parametr chart określa wykres, który chcesz pobrać.

Akceptowane wartości:
id string
Parametr id określa rozdzieloną przecinkami listę identyfikatorów filmów na YouTube dla pobieranych zasobów. W zasobie video właściwość id określa identyfikator filmu.
myRating string

Ten parametr można używać tylko w prawidłowo autoryzowanym żądaniu. Ustaw wartość tego parametru na like lub dislike, aby interfejs API zwracał tylko filmy, które zostały polubione lub niepolubione przez uwierzytelnionego użytkownika.



Interfejs API ogranicza zwracany zestaw wyników do maksymalnie 1000 filmów. Nawet jeśli właściwość pageInfo.totalResults w odpowiedzi wskazuje wyższą łączną liczbę, stronicowanie za pomocą parametru pageToken umożliwia pobranie tylko 1000 najnowszych elementów.



Parametr akceptuje te wartości:

  • dislike – zwraca tylko filmy, które zostały niepolubione przez uwierzytelnionego użytkownika.
  • like – zwraca tylko filmy, które zostały polubione przez uwierzytelnionego użytkownika.
Parametry opcjonalne
hl string
Parametr hl nakazuje interfejsowi API pobranie zlokalizowanych metadanych zasobu w określonym języku aplikacji obsługiwanym przez witrynę YouTube. Wartość parametru musi być kodem języka zawartym na liście zwracanej przez metodę i18nLanguages.list.

Jeśli zlokalizowane szczegóły zasobu są dostępne w danym języku, obiekt snippet.localized zasobu będzie zawierać zlokalizowane wartości. Jeśli jednak zlokalizowane szczegóły nie są dostępne, obiekt snippet.localized będzie zawierać szczegóły zasobu w języku domyślnym zasobu.
maxHeight unsigned integer
Parametr maxHeight określa maksymalną wysokość odtwarzacza osadzonego zwracanego we właściwości player.embedHtml. Za pomocą tego parametru możesz określić, że zamiast wymiarów domyślnych kod osadzania powinien używać wysokości odpowiedniej dla układu aplikacji. Jeśli podasz też parametr maxWidth, odtwarzacz może być krótszy niż maxHeight, aby nie przekraczać 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 mają być zwracane w zestawie wyników.

Uwaga: ten parametr jest obsługiwany w połączeniu z parametrem myRating, ale nie jest obsługiwany 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ść odtwarzacza osadzonego zwracanego we właściwości player.embedHtml. Za pomocą tego parametru możesz określić, że zamiast wymiarów domyślnych kod osadzania powinien używać szerokości odpowiedniej dla układu aplikacji.

Jeśli podasz też parametr maxHeight, odtwarzacz może być węższy niż maxWidth, aby nie przekraczać maksymalnej wysokości. Akceptowane wartości to od 72 do 8192 włącznie.
onBehalfOfContentOwner string
Ten parametr można używać tylko w prawidłowo autoryzowanym żądaniu. Uwaga: ten parametr jest przeznaczony wyłącznie dla partnerów YouTube.

Parametr onBehalfOfContentOwner wskazuje, że dane uwierzytelniające autoryzację żądania identyfikują użytkownika systemu CMS YouTube, który działa w imieniu właściciela treści określonego w wartości parametru. Parametr `**onBehalfOfContentOwner**` wskazuje, że dane uwierzytelniające żądania identyfikują użytkownika systemu CMS YouTube, który działa w imieniu właściciela treści określonego w wartości parametru. Umożliwia to właścicielom treści jednokrotne uwierzytelnienie i uzyskanie dostępu do wszystkich danych dotyczących ich filmów i kanałów bez konieczności podawania danych uwierzytelniających dla każdego pojedynczego kanału. Konto CMS, za pomocą którego użytkownik się uwierzytelnia, musi być połączone z określonym właścicielem treści w YouTube.
pageToken string
Parametr pageToken określa konkretną stronę w zestawie wyników, która ma zostać zwrócona. W odpowiedzi interfejsu API właściwości nextPageToken i prevPageToken identyfikują inne strony, które można pobrać.

Uwaga: ten parametr jest obsługiwany w połączeniu z parametrem myRating, ale nie jest obsługiwany w połączeniu z parametrem id.
regionCode string
Parametr regionCode nakazuje interfejsowi API wybranie wykresu wideo dostępnego w określonym regionie. Ten parametr można używać tylko w połączeniu z parametrem chart. Wartość parametru to kod kraju w formacie ISO 3166-1 alfa-2.
videoCategoryId string
Parametr videoCategoryId określa kategorię filmu, dla której należy pobrać wykres. Ten parametr można używać tylko w połączeniu z parametrem chart. Domyślnie wykresy nie są ograniczone do określonej kategorii. Wartością domyślną jest 0.

Treść żądania

Podczas wywoływania tej metody nie podawaj treści żądania.

Odpowiedź

Jeśli operacja się uda, ta metoda zwróci treść odpowiedzi o tej strukturze:

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

Właściwości

W tabeli poniżej znajdziesz definicje właściwości, które pojawiają się w tym zasobie:

Właściwości
kind string
Określa typ zasobu interfejsu API. Wartość to youtube#videoListResponse.
etag etag
Etag tego zasobu.
nextPageToken string
Token, którego można użyć jako wartości parametru pageToken, aby pobrać następną stronę w zestawie wyników.
prevPageToken string
Token, którego można użyć jako wartości parametru pageToken, aby pobrać poprzednią stronę w zestawie wyników.
pageInfo object
Obiekt pageInfo zawiera informacje o stronicowaniu zestawu wyników.
pageInfo.totalResults integer
Łączna liczba wyników w zestawie wyników.
pageInfo.resultsPerPage integer
Liczba wyników uwzględnionych w odpowiedzi interfejsu API.
items[] list
Lista filmów, które pasują do kryteriów żą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 informacji 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 jest niedostępny.
forbidden (403) forbidden Żądanie nie jest prawidłowo autoryzowane do uzyskiwania dostępu do pliku wideo ani informacji o przetwarzaniu. Pamiętaj, że części fileDetails, processingDetails i suggestions są dostępne tylko dla właściciela 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żywania parametru myRating.
notFound (404) videoNotFound Nie można znaleźć filmu, który próbujesz pobrać. Sprawdź wartość parametru id w żądaniu, aby upewnić się, że jest prawidłowa.

Wypróbuj

Aby wywołać ten interfejs API i zobaczyć żądanie do interfejsu API oraz odpowiedź, użyj APIs Explorer.