API Reference

Interfejs YouTube Data API umożliwia wdrażanie funkcji, które są zwykle wykonywane na stronie YouTube, do własnej witryny lub aplikacji. W listach poniżej znajdziesz różne typy zasobów, które możesz pobrać za pomocą interfejsu API. Interfejs API obsługuje też metody wstawiania, aktualizowania i usuwania wielu z tych zasobów.

Ten przewodnik zawiera informacje o tym, jak korzystać z interfejsu API do wykonywania tych operacji. Przewodnik jest uporządkowany według typu zasobu. Zasób reprezentuje typ elementu, który stanowi część interfejsu YouTube, np. film, playlistę lub subskrypcję. W przypadku każdego typu zasobu w przewodniku wymieniono co najmniej jedną reprezentację danych, a zasoby są reprezentowane jako obiekty JSON. Przewodnik zawiera też listę co najmniej 1 obsługiwanej metody (LIST, POST, DELETE itp.) dla każdego typu zasobu oraz wyjaśnia, jak używać tych metod w aplikacji.

Wywoływanie interfejsu API

W przypadku żądań do interfejsu YouTube Data API obowiązują te wymagania:

  1. Każde żądanie musi zawierać klucz API (z parametrem key) lub token OAuth 2.0. Klucz interfejsu API jest dostępny w panelu Dostęp do interfejsu API w Konsoli programisty dla Twojego projektu.

  2. Musisz wysyłać token autoryzacji w przypadku każdego żądania wstawienia, aktualizacji i usunięcia. Musisz też wysłać token autoryzacji w przypadku każdego żądania, które pobiera prywatne dane zalogowanego użytkownika.

    Ponadto niektóre metody interfejsu API służące do pobierania zasobów mogą obsługiwać parametry, które wymagają autoryzacji, lub zawierać dodatkowe metadane, gdy prośby są autoryzowane. Na przykład żądanie pobrania filmów przesłanych przez użytkownika może obejmować również filmy prywatne, jeśli zostało autoryzowane przez tego użytkownika.

  3. Interfejs API obsługuje protokół uwierzytelniania OAuth 2.0. Token OAuth 2.0 możesz podać na jeden z tych sposobów:

    • Użyj parametru zapytania access_token w taki sposób: ?access_token=oauth2-token
    • Użyj nagłówka HTTP Authorization w ten sposób: Authorization: Bearer oauth2-token

    Pełne instrukcje implementowania uwierzytelniania OAuth 2.0 w aplikacji znajdziesz w przewodniku dotyczącym uwierzytelniania.

Typy zasobów

Działania

Zasób activity zawiera informacje o działaniach, które dany kanał lub użytkownik wykonał w YouTube. Działania zgłaszane w strumieniach aktywności obejmują ocenę filmu, udostępnianie filmu, oznaczanie filmu jako ulubionego, przesyłanie filmu itp. Każdy zasób activity identyfikuje typ działania, kanał powiązany z tym działaniem oraz zasoby powiązane z tym działaniem, takie jak film, który został oceniony lub przesłany.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /activities Zwraca listę zdarzeń aktywności kanału, które pasują do kryteriów żądania. Możesz na przykład pobrać zdarzenia powiązane z określonym kanałem lub z kanałem użytkownika.
insert POST /activities Uwaga: ta metoda została wycofana i nie jest już obsługiwana.

Napisy

Zasób caption reprezentuje ścieżkę z napisami w YouTube. Utwór z napisami jest powiązany z dokładnie jednym filmem w YouTube.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
delete DELETE /captions Usuwa określoną ścieżkę napisów.
download GET /captions/id Pobiera ścieżkę z napisami. Ścieżka z napisami jest zwracana w oryginalnym formacie, chyba że żądanie określa wartość parametru tfmt, oraz w oryginalnym języku, chyba że żądanie określa wartość parametru tlang.
insert POST /captions Przesyła ścieżkę z napisami.
list GET /captions Zwraca listę ścieżek z napisami, które są powiązane z określonym filmem. Pamiętaj, że odpowiedź interfejsu API nie zawiera faktycznych napisów, a metoda captions.download umożliwia pobranie ścieżki z napisami.
update PUT /captions Aktualizuje ścieżkę z napisami. Podczas aktualizowania ścieżki napisów możesz zmienić stan projektu ścieżki, przesłać nowy plik napisów lub wykonać obie te czynności.

ChannelBanners

Zasób channelBanner zawiera adres URL, którego użyjesz, aby ustawić nowo przesłany obraz jako baner kanału.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Przesyłanie obrazu banera kanału do YouTube. Ta metoda obejmuje 2 pierwsze kroki 3-etapowego procesu aktualizacji obrazu banera kanału:

  1. Aby przesłać binarne dane obrazu do YouTube, wywołaj metodę channelBanners.insert. Obraz musi mieć format 16:9 i rozmiar co najmniej 2048 x 1152 piksele. Zalecamy przesłanie obrazu o wymiarach 2560 × 1440 pikseli.
  2. Wyodrębnij wartość właściwości url z odpowiedzi zwróconej przez interfejs API w kroku 1.
  3. Aby zaktualizować ustawienia marki kanału, wywołaj metodę channels.update. Ustaw wartość właściwości brandingSettings.image.bannerExternalUrl na adres URL uzyskany w kroku 2.

ChannelSections

Zasób channelSection zawiera informacje o zestawie filmów, które kanał wybrał do wyróżnienia. Może to być na przykład sekcja z najnowszymi lub najpopularniejszymi filmami z kanału albo z playlist.

Pamiętaj, że sekcje kanału są widoczne tylko wtedy, gdy kanał wyświetla treści w widoku przeglądania (a nie w widoku kart). Aby umożliwić wyświetlanie treści na kanale w widoku przeglądania, dla wybranego kanału ustaw właściwość brandingSettings.channel.showBrowseView na true.

Kanał może utworzyć maksymalnie 10 półek.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
delete DELETE /channelSections usunąć sekcję kanału.
insert POST /channelSections Dodaje sekcję kanału do kanału uwierzytelnionego użytkownika. Na kanale można utworzyć maksymalnie 10 półek.
list GET /channelSections Zwraca listę zasobów channelSection, które spełniają kryteria żądania interfejsu API.
update PUT /channelSections Zaktualizuj sekcję kanału.

Kanały

Zasób channel zawiera informacje o kanale w YouTube.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /channels Zwraca zbiór co najmniej 0 zasobów channel, które spełniają kryteria żądania.
update PUT /channels Aktualizuje metadane kanału. Pamiętaj, że ta metoda obsługuje obecnie tylko aktualizacje obiektów brandingSettings i invideoPromotion zasobu channel oraz ich właściwości podrzędnych.

CommentThreads

Zasób commentThread zawiera informacje o wątku komentarzy w YouTube, który składa się z komentarza najwyższego poziomu i odpowiedzi na ten komentarz (jeśli takie istnieją). Zasób commentThread może reprezentować komentarze do filmu lub kanału.

Zarówno komentarz najwyższego poziomu, jak i odpowiedzi są w rzeczywistości zasobami comment zagnieżdżonymi w zasobie commentThread. Zasób commentThread niekoniecznie zawiera wszystkie odpowiedzi na komentarz. Jeśli chcesz pobrać wszystkie odpowiedzi na konkretny komentarz, musisz użyć metody comments.list. Pamiętaj też, że niektóre komentarze nie mają odpowiedzi.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /commentThreads Zwraca listę wątków komentarzy, które pasują do parametrów żądania interfejsu API.
insert POST /commentThreads Tworzy nowy komentarz najwyższego poziomu. Aby dodać odpowiedź na istniejący komentarz, użyj metody comments.insert.

Komentarze

Zasób comment zawiera informacje o pojedynczym komentarzu w YouTube. Zasób comment może reprezentować komentarz do filmu lub kanału. Komentarz może być komentarzem najwyższego poziomu lub odpowiedzią na komentarz najwyższego poziomu.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /comments Zwraca listę komentarzy, które pasują do parametrów żądania interfejsu API.
setModerationStatus POST /comments/setModerationStatus Ustawia stan moderacji co najmniej 1 komentarza. Żądanie przesłane przez interfejs API musi być autoryzowane przez właściciela kanału lub filmu powiązanego z komentarzami.
insert POST /comments tworzy odpowiedź na istniejący komentarz. Uwaga: aby utworzyć komentarz najwyższego poziomu, użyj metody commentThreads.insert.
markAsSpam POST /comments/markAsSpam Uwaga: ta metoda została wycofana i nie jest już obsługiwana.
delete DELETE /comments Usuwa komentarz.
update PUT /comments Modyfikuje komentarz.

GuideCategories

Zasób guideCategory identyfikuje kategorię przypisaną przez algorytm YouTube na podstawie treści kanału lub innych wskaźników, takich jak popularność kanału. Lista jest podobna do kategorii filmów, z tą różnicą, że przesyłający film może przypisać kategorię do filmu, ale tylko YouTube może przypisać kategorię do kanału.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /guideCategories Zwraca listę kategorii, które można powiązać z kanałami w YouTube.

I18nLanguages

Zasób i18nLanguage identyfikuje język aplikacji obsługiwany przez witrynę YouTube. Język aplikacji może być też nazywany językiem interfejsu. W przypadku witryny YouTube język aplikacji może być wybierany automatycznie na podstawie ustawień konta Google, języka przeglądarki lub lokalizacji adresu IP. Użytkownik może też ręcznie wybrać odpowiedni język interfejsu w stopce strony YouTube.

Każdy zasób i18nLanguage identyfikuje kod języka i jego nazwę. Kod języka może być używany jako wartość parametru hl podczas wywoływania metod interfejsu API, takich jak videoCategories.list i guideCategories.list.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /i18nLanguages Zwraca listę języków aplikacji obsługiwanych przez stronę YouTube.

I18nRegions

Zasób i18nRegion identyfikuje obszar geograficzny, który użytkownik YouTube może wybrać jako preferowany region treści. Region treści może być też określany jako lokalizacja treści. W przypadku strony YouTube region treści może być wybierany automatycznie na podstawie heurystyk, takich jak domena YouTube czy lokalizacja adresu IP użytkownika. Użytkownik może też ręcznie wybrać odpowiedni region treści w stopce witryny YouTube.

Każdy zasób i18nRegion ma kod regionu i nazwę. Kod regionu może być używany jako wartość parametru regionCode podczas wywoływania metod interfejsu API, takich jak search.list, videos.list, activities.list i videoCategories.list.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /i18nRegions Zwraca listę regionów, w których strona YouTube obsługuje treści.

Użytkownicy

Zasób member reprezentuje wspierającego kanał w YouTube. Wspierający regularnie wpłacają pieniądze twórcy i otrzymują specjalne korzyści. Na przykład wspierający mogą korzystać z czatu, gdy twórca włączy tryb tylko dla wspierających.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /members Lista wspierających (wcześniej nazywanych „sponsorami”) kanału. Żądanie do interfejsu API musi być autoryzowane przez właściciela kanału.

MembershipsLevels

Zasób membershipsLevel identyfikuje poziom cen dla twórcy, który autoryzował żądanie interfejsu API.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /membershipsLevels Zwraca kolekcję co najmniej 1 zasobu membershipsLevel należącego do kanału, który autoryzował żądanie interfejsu API. Poziomy są zwracane w ukrytej kolejności wyświetlania.

PlaylistItems

Zasób playlistItem identyfikuje inny zasób, np. film, który jest zawarty na playliście. Ponadto zasób playlistItem zawiera szczegółowe informacje o zawartym zasobie, które odnoszą się do sposobu jego wykorzystania na tej playliście.

YouTube używa też playlisty do identyfikowania listy przesłanych filmów na kanale, a każdy elementplaylistItem na tej liście reprezentuje jeden przesłany film. Identyfikator playlisty możesz pobrać z poziomu channel resource na danym kanale. Następnie możesz użyć metody playlistItems.list do listy.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Usuwa element z playlisty.
insert POST /playlistItems Dodaje zasób do playlisty.
list GET /playlistItems Zwraca zbiór elementów playlisty, które pasują do parametrów żądania interfejsu API. Możesz pobrać wszystkie elementy playlisty na określonej playliście lub pobrać co najmniej jeden element playlisty według jego unikalnego identyfikatora.
update PUT /playlistItems Modyfikuje element playlisty. Możesz na przykład zmienić pozycję elementu na liście odtwarzania.

Playlisty

Zasób playlist reprezentuje playlistę w YouTube. Playlista to zbiór filmów, które można oglądać sekwencyjnie i udostępniać innym użytkownikom. Domyślnie playlisty są publicznie widoczne dla innych użytkowników, ale mogą być publiczne lub prywatne.

YouTube używa playlist do identyfikowania specjalnych kolekcji filmów na kanale, takich jak:

  • przesłane filmy
  • filmy z pozytywnymi ocenami (polubione);
  • historia oglądania
  • Do obejrzenia
W szczególności te listy są powiązane z kanałem, czyli kolekcją filmów, playlist i innych informacji w YouTube należących do osoby, grupy lub firmy. Identyfikatory playlist możesz pobrać z channel resource danego kanału.

Następnie możesz użyć metody playlistItems.list, aby pobrać dowolną z tych list. Możesz też dodawać i usuwać elementy z tych list, wywołując metody playlistItems.insert i playlistItems.delete.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
delete DELETE /playlists Usuwa playlistę.
list GET /playlists Zwraca kolekcję playlist, które pasują do parametrów żądania interfejsu API. Możesz na przykład pobrać wszystkie playlisty należące do uwierzytelnionego użytkownika lub pobrać co najmniej jedną playlistę według jej unikalnego identyfikatora.
insert POST /playlists Tworzy playlistę.
update PUT /playlists Modyfikuje playlistę. Możesz na przykład zmienić tytuł, opis lub ustawienia prywatności playlisty.

Wynik wyszukiwania zawiera informacje o filmie, kanale lub playliście w YouTube, które pasują do parametrów wyszukiwania określonych w żądaniu interfejsu API. Wynik wyszukiwania wskazuje na zasób, który można jednoznacznie zidentyfikować, np. film, ale nie ma własnych trwałych danych.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /search Zwraca zbiór wyników wyszukiwania pasujących do parametrów zapytania określonych w żądaniu interfejsu API. Domyślnie zestaw wyników wyszukiwania identyfikuje pasujące zasoby video, channel i playlist, ale możesz też skonfigurować zapytania tak, aby pobierać tylko zasoby określonego typu.

Subskrypcje

Zasób subscription zawiera informacje o subskrypcji użytkownika YouTube. Subskrypcja powiadamia użytkownika, gdy na kanale pojawią się nowe filmy lub gdy inny użytkownik wykona jedno z kilku działań w YouTube, takich jak przesłanie filmu, ocena filmu lub dodanie komentarza.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions usuwa subskrypcję.
insert POST /subscriptions Dodaje subskrypcję kanału uwierzytelnionego użytkownika.
list GET /subscriptions Zwraca zasoby subskrypcji, które pasują do kryteriów żądania interfejsu API.

Miniatury

Zasób thumbnail identyfikuje różne rozmiary miniatur powiązane z zasobem. Pamiętaj o tych cechach miniatur:

  • Właściwość snippet.thumbnails zasobu to obiekt, który identyfikuje miniatury dostępne dla tego zasobu.
  • Zasób thumbnail zawiera serię obiektów. Nazwa każdego obiektu (default, medium, high itd.) odnosi się do rozmiaru miniatury.
  • Różne typy zasobów mogą obsługiwać różne rozmiary miniatur.
  • Różne typy zasobów mogą definiować różne rozmiary miniatur o tej samej nazwie. Na przykład miniatura default zasobu video ma zwykle wymiary 120 x 90 pikseli, a miniatura default zasobu channel ma zwykle wymiary 88 x 88 pikseli.
  • Zasoby tego samego typu mogą mieć różne rozmiary miniatur w zależności od rozdzielczości oryginalnego obrazu lub treści przesłanych do YouTube. Na przykład film w jakości HD może mieć miniatury w wyższej rozdzielczości niż filmy w niższej rozdzielczości.
  • Każdy obiekt zawierający informacje o rozmiarze miniatury ma właściwość width i właściwość height. Właściwości szerokość i wysokość mogą jednak nie zostać zwrócone dla tego obrazu.
  • Jeśli przesłana miniatura nie ma wymaganych wymiarów, jej rozmiar zostanie zmieniony na prawidłowy bez zmiany współczynnika proporcji. obraz nie jest przycięty, ale może zawierać czarne paski, aby zachować prawidłowy rozmiar;

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Przesyłanie do YouTube niestandardowej miniatury filmu i ustawianie jej jako miniatury filmu.

VideoAbuseReportReasons

videoAbuseReportReason zawiera informacje o tym, dlaczego film został oznaczony jako zawierający treści obraźliwe. Gdy Twoja aplikacja wywołuje metodę videos.reportAbuse, aby zgłosić film z nadużyciem, żądanie korzysta z informacji z zasobu videoAbuseReportReason, aby określić powód zgłoszenia filmu.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Pobierz listę powodów, które można podać, zgłaszając filmy z niedozwolonymi treściami.

VideoCategories

Zasób videoCategory wskazuje kategorię, która została lub może zostać powiązana z przesłanymi filmami.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
list GET /videoCategories Zwraca listę kategorii, które można powiązać z filmami w YouTube.

Filmy

Zasób video reprezentuje film w YouTube.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu oraz w liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
insert POST /videos Przesyła film do YouTube i opcjonalnie ustawia jego metadane.
list GET /videos Zwraca listę filmów, które pasują do parametrów żądania interfejsu API.
delete DELETE /videos usuwa film w YouTube.
update PUT /videos Aktualizuje metadane filmu.
rate POST /videos/rate Dodaj ocenę „Lubię” lub „Nie lubię” do filmu lub usuń ocenę z filmu.
getRating GET /videos/getRating Pobiera oceny przyznane przez upoważnionego użytkownika na liście określonych filmów.
reportAbuse POST /videos/reportAbuse zgłaszać filmy zawierające treści obraźliwe.

Znaki wodne

Zasób watermark to obraz wyświetlany podczas odtwarzania filmów na określonym kanale. Możesz też określić kanał docelowy, do którego będzie prowadzić link z obrazem, a także szczegóły dotyczące czasu, który określa, kiedy znak wodny ma się wyświetlać podczas odtwarzania filmu, oraz czas jego wyświetlania.

Więcej informacji o tym zasobie znajdziesz w sekcji reprezentacja zasobu i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względne do https://www.googleapis.com/youtube/v3
set POST /watermarks/set Przesyła obraz znaku wodnego do YouTube i ustawia go na kanale.
unset POST /watermarks/unset Usuwa obraz znaku wodnego kanału.