API Reference

Interfejs YouTube Data API pozwala na umieszczanie w swojej witrynie lub aplikacji funkcji, które zwykle są wykonywane w YouTube. Poniższe listy opisują różne typy zasobów, które można pobrać za pomocą interfejsu API. Interfejs API obsługuje też metody wstawiania, aktualizowania i usuwania wielu z tych zasobów.

Z tego przewodnika dowiesz się, jak używać interfejsu API do wykonywania wszystkich tych operacji. Przewodnik jest uporządkowany według typu zasobu. Zasób reprezentuje typ elementu stanowiącego część funkcji YouTube, np. film, playlistę lub subskrypcję. W przewodniku dla każdego typu zasobów znajduje się co najmniej 1 reprezentacja danych, a zasoby są przedstawiane jako obiekty JSON. Przewodnik zawiera też listę obsługiwanych metod (LIST, POST, DELETE itd.) dla każdego typu zasobów oraz wyjaśnia, jak ich używać w swojej aplikacji.

Wywoływanie interfejsu API

Żądania do interfejsu YouTube Data API muszą spełniać te wymagania:

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

  2. Musisz wysłać token autoryzacji w przypadku każdego żądania wstawienia, aktualizacji i usunięcia. Musisz też wysłać token autoryzacji dla każdego żądania pobierającego prywatne dane uwierzytelnionego użytkownika.

    Dodatkowo niektóre metody interfejsu API do pobierania zasobów mogą obsługiwać parametry, które wymagają autoryzacji lub mogą zawierać dodatkowe metadane po autoryzacji żądań. Na przykład żądanie pobrania przesłanych filmów przesłanych przez użytkownika może też zawierać filmy prywatne, jeśli zostało ono autoryzowane przez tego użytkownika.

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

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

    Kompletne instrukcje dotyczące wdrażania uwierzytelniania OAuth 2.0 w aplikacji znajdziesz w przewodniku po uwierzytelnianiu.

Typy zasobów

Ćwiczenia

Zasób activity zawiera informacje o działaniu podjętym przez dany kanał lub użytkownika w YouTube. Działania zgłaszane w kanałach aktywności obejmują ocenę filmu, udostępnienie go, oznaczenie filmu jako ulubionego, przesłanie filmu itd. Każdy zasób activity określa typ działania, kanał powiązany z działaniem oraz zasoby powiązane z tym działaniem, np. film, który został oceniony lub przesłany.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /activities Zwraca listę zdarzeń związanych z aktywnością na kanale, które spełniają kryteria żądania. Możesz na przykład pobierać 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. Ścieżka z napisami jest powiązana tylko z jednym filmem w YouTube.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
delete DELETE /captions Usuwa określoną ścieżkę z napisami.
download GET /captions/id Pobiera ścieżkę z napisami. Ścieżka z napisami jest zwracana w oryginalnym formacie, chyba że w żądaniu określono wartość parametru tfmt w oryginalnym języku, chyba że w żądaniu określisz wartość parametru tlang.
insert POST /captions Przesyła ścieżkę z napisami.
list GET /captions Zwraca listę ścieżek napisów powiązanych z określonym filmem. Zwróć uwagę, że odpowiedź interfejsu API nie zawiera rzeczywistych napisów, a metoda captions.download umożliwia pobranie ścieżki napisów.
update PUT /captions Aktualizuje ścieżkę z napisami. Podczas aktualizowania ścieżki napisów możesz zmienić stan wersji roboczej ścieżki, przesłać nowy plik z napisami lub skorzystać z obu tych opcji.

ChannelBanners

Zasób channelBanner zawiera adres URL, za pomocą którego ustawisz nowo przesłany obraz jako obraz banera kanału.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Przesyła obraz banera kanału do YouTube. Poniższa metoda przedstawia pierwsze 2 etapy 3-etapowego procesu aktualizowania obrazu banera kanału:

  1. Wywołaj metodę channelBanners.insert, aby przesłać dane obrazu binarnego do YouTube. Obraz musi mieć format 16:9 i minimalny rozmiar 2048 x 1152 piksele. Zalecamy przesłanie obrazu o wymiarach 2560 x 1440 pikseli.
  2. Wyodrębnij wartość właściwości url z odpowiedzi, którą interfejs API zwraca w kroku 1.
  3. Wywołaj metodę channels.update, aby zaktualizować ustawienia marki kanału. Jako wartość właściwości brandingSettings.image.bannerExternalUrl ustaw adres URL uzyskany w kroku 2.

ChannelSections

Zasób channelSection zawiera informacje o zbiorze filmów polecanych na kanale. Na przykład sekcja może zawierać najnowsze filmy z kanału, najpopularniejsze filmy lub filmy z jednej lub kilku playlist.

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

Na kanale można utworzyć maksymalnie 10 półek.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Usuwa 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 do interfejsu API.
update PUT /channelSections Aktualizuje sekcję kanału.

Kanały

Zasób channel zawiera informacje o kanale YouTube.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /channels Zwraca zbiór zawierający 0 lub więcej zasobów channel, które spełniają kryteria żądania.
update PUT /channels Aktualizuje metadane kanału. Pamiętaj, że obecnie ta metoda obsługuje 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 oraz ewentualnych odpowiedzi na ten komentarz. Zasób commentThread może reprezentować komentarze na temat filmu lub kanału.

Zarówno komentarz najwyższego poziomu, jak i odpowiedzi są zasobami typu comment umieszczonymi w zasobie commentThread. Zasób commentThread nie musi zawierać wszystkich odpowiedzi na komentarz. Jeśli chcesz pobrać wszystkie odpowiedzi na konkretny komentarz, musisz użyć metody comments.list. Pamiętaj też, że na niektóre komentarze nie ma odpowiedzi.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /commentThreads Zwraca listę wątków komentarzy pasujących do parametrów żądania do 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 na temat filmu lub kanału. Może to być komentarz najwyższego poziomu lub odpowiedź na komentarz najwyższego poziomu.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /comments Zwraca listę komentarzy pasujących do parametrów żądania do interfejsu API.
setModerationStatus POST /comments/setModerationStatus Określa stan moderowania co najmniej jednego komentarza. Żądanie do interfejsu 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 określa kategorię, którą YouTube przypisuje algorytmicznie na podstawie treści kanału lub innych wskaźników, takich jak popularność kanału. Lista jest podobna do kategorii filmów. Różnica polega na tym, że przesyłający może przypisać kategorię filmu, ale tylko YouTube może to zrobić.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

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

I18nLanguages

Zasób i18nLanguage określa język aplikacji obsługiwany przez witrynę YouTube. Język aplikacji może być też nazywany językiem interfejsu użytkownika. W przypadku strony 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 ze stopki witryny YouTube.

Każdy zasób i18nLanguage składa się z kodu języka i nazwy. Kod języka może być używany jako wartość parametru hl podczas wywoływania metod API takich jak videoCategories.list i guideCategories.list.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

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

I18nRegions

Zasób i18nRegion określa obszar geograficzny, który użytkownik YouTube może wybrać jako preferowany region treści. Region treści może być też nazywany regionem treści. W przypadku witryny YouTube region treści może zostać wybrany automatycznie na podstawie takich danych heurystycznych, 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 składa się z kodu regionu i nazwy. Kod regionu może służyć jako wartość parametru regionCode podczas wywoływania metod API takich jak search.list, videos.list, activities.list i videoCategories.list.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /i18nRegions Zwraca listę regionów treści obsługiwanych przez witrynę YouTube.

Wspierający

Zasób member reprezentuje osobę wspierającą kanał w YouTube. Wspierający zapewnia cyklicznie wsparcie finansowe twórcy i otrzymuje wyjątkowe korzyści. Na przykład wspierający mogą rozmawiać na czacie, gdy twórca włączy tryb tylko dla wspierających.

Więcej informacji o tym zasobie znajdziesz w reprezentacji tego zasobu i liście właściwości.

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

MembershipsLevels

Zasób membershipsLevel określa poziom cen twórcy, który autoryzował żądanie do interfejsu API.

Więcej informacji o tym zasobie znajdziesz w reprezentacji tego zasobu i liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /membershipsLevels Zwraca zbiór zawierający co najmniej 0 zasobów membershipsLevel należących do kanału, który autoryzował żądanie do interfejsu API. Poziomy są zwracane w niejawnej kolejności wyświetlania.

PlaylistItems

Zasób playlistItem określa inny zasób, np. film, który znajduje się na playliście. Dodatkowo zasób playlistItem zawiera szczegółowe informacje o uwzględnionym zasobie, które odnoszą się konkretnie do sposobu jego wykorzystania na playliście.

YouTube wykorzystuje też playlistę do identyfikowania listy przesłanych filmów na kanał, gdzie każdy element playlistItem z tej listy odpowiada 1 przesłanemu filmowi. Identyfikator playlisty dla tej listy możesz pobrać z channel resource dla danego kanału. Do wyświetlania listy możesz użyć metody playlistItems.list.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Usuwa element playlisty.
insert POST /playlistItems Dodaje zasób do playlisty.
list GET /playlistItems Zwraca kolekcję elementów playlisty, które pasują do parametrów żądania do interfejsu API. Możesz pobrać wszystkie elementy playlisty, które się na niej znajdują, albo jeden lub więcej elementów, podając ich unikalne identyfikatory.
update PUT /playlistItems Modyfikuje element playlisty. Możesz na przykład zmienić pozycję elementu na playliście.

Playlisty

Zasób playlist reprezentuje playlistę w YouTube. Playlista to zbiór filmów, które można oglądać w określonej kolejności i udostępniać innym użytkownikom. Playlista może zawierać do 200 filmów, a YouTube nie ogranicza liczby playlist tworzonych przez każdego użytkownika. Domyślnie playlisty są widoczne publicznie dla innych użytkowników, ale playlisty mogą być publiczne lub prywatne.

YouTube wykorzystuje też playlisty do identyfikowania specjalnych kolekcji filmów na kanale, na przykład:

  • przesłane filmy
  • pozytywnie oceniane (polubione) filmy
  • historia oglądania
  • Do obejrzenia
Uściślając, listy te są powiązane z kanałem, który jest zbiorem filmów, playlist i innych informacji z YouTube należących do osoby, grupy lub firmy. Identyfikatory playlist dla każdej z tych list znajdziesz w channel resource dla danego kanału.

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

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
delete DELETE /playlists Usuwa playlistę.
list GET /playlists Zwraca kolekcję playlist pasujących do parametrów żądania do interfejsu API. Możesz na przykład pobrać wszystkie playlisty należące do uwierzytelnionych użytkowników albo jedną lub więcej playlist, podając ich unikalne identyfikatory.
insert POST /playlists Tworzy playlistę.
update PUT /playlists Modyfikuje playlistę. Możesz na przykład zmienić tytuł, opis lub stan prywatności playlisty.

Wynik wyszukiwania zawiera informacje o filmie, kanale lub playliście w YouTube pasujące do parametrów wyszukiwania określonych w żądaniu do interfejsu API. Wynik wyszukiwania wskazuje unikalny zasób, taki jak film, ale nie ma własnych, trwałych danych.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu 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 do interfejsu API. Domyślnie zestaw wyników wyszukiwania identyfikuje pasujące zasoby video, channel i playlist, ale możesz skonfigurować zapytania pod kątem pobierania tylko określonego typu zasobów.

Subskrypcje

Zasób subscription zawiera informacje o subskrypcji użytkownika YouTube. Subskrypcja powiadamia użytkownika, gdy na kanale dodawany jest nowy film lub gdy inny użytkownik wykona jedną z kilku czynności w YouTube, takich jak przesłanie filmu, wystawienie oceny lub skomentowanie.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu 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 spełniające kryteria żądania do interfejsu API.

Miniatury

Zasób thumbnail określa różne rozmiary obrazów miniatur powiązane z zasobem. Pamiętaj o następujących cechach miniatur:

  • Właściwość snippet.thumbnails zasobu to obiekt, który określa miniatury dostępnych dla tego zasobu miniatur.
  • Zasób thumbnail zawiera serię obiektów. Nazwa każdego obiektu (default, medium, high itd.) odnosi się do rozmiaru obrazu miniatury.
  • Różne rodzaje zasobów mogą obsługiwać różne rozmiary obrazów miniatur.
  • Różne typy zasobów mogą definiować różne rozmiary miniatur obrazów o tej samej nazwie. Na przykład miniatura zasobu default w przypadku zasobu video ma zwykle 120 x 90 pikseli, a miniatura default zasobu channel ma zwykle 88 x 88 pikseli.
  • Zasoby tego samego typu mogą mieć różne rozmiary miniatur w przypadku niektórych obrazów w zależności od rozdzielczości oryginalnego obrazu lub treści przesłanych do YouTube. Na przykład film HD może obsługiwać miniatury w wyższej rozdzielczości niż filmy w innych formatach.
  • Każdy obiekt zawierający informacje o rozmiarze obrazu miniatury ma właściwość width i height. W przypadku tego obrazu mogą jednak nie być zwracane właściwości szerokości i wysokości.
  • Jeśli przesłany obraz miniatury nie spełnia wymaganych wymiarów, rozmiar obrazu jest zmieniany w taki sposób, by pasował do właściwego rozmiaru, bez zmiany proporcji. Obraz nie jest przycięty, ale może zawierać czarne paski zapewniające prawidłowy rozmiar.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Przesyła niestandardową miniaturę do filmu w YouTube i ustawia ją jako film.

VideoAbuseReportReasons

Zasób videoAbuseReportReason zawiera informacje o przyczynach, dla których film zawiera nieodpowiednie treści. Gdy aplikacja wywołuje metodę videos.reportAbuse, aby zgłosić nadużycie w filmie, żądanie korzysta z informacji z zasobu videoAbuseReportReason, aby określić przyczynę zgłoszenia filmu.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Pobierz listę powodów, na podstawie których możesz zgłosić filmy naruszające zasady.

VideoCategories

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

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu 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 jego reprezentacji i na liście właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu 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 pasujących do parametrów żądania do interfejsu API.
delete DELETE /videos Usuwa film z YouTube.
update PUT /videos Aktualizuje metadane filmu.
rate POST /videos/rate Dodaj do filmu ocenę „Podoba mi się” lub „Nie podoba mi się” lub usuń z niego ocenę.
getRating GET /videos/getRating Pobiera oceny nadane przez autoryzowanego użytkownika liście określonych filmów.
reportAbuse POST /videos/reportAbuse Zgłoś film, który zawiera nieodpowiednie treści.

znaki wodne,

Zasób watermark określa obraz, który wyświetla się podczas odtwarzania filmów z konkretnego kanału. Możesz też określić kanał docelowy, do którego będzie prowadzić obraz. Możesz też określić czas, który określa, kiedy znak wodny pojawi się podczas odtwarzania filmu i jak długo jest widoczny.

Więcej informacji o tym zasobie znajdziesz w jego reprezentacji i na liście właściwości.

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