API Reference

Interfejs YouTube Data API umożliwia wdrażanie funkcji, które są zwykle wykonywane w witrynie YouTube, we własnej witrynie lub aplikacji. W sekcjach 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 używać interfejsu API do wykonywania wszystkich tych operacji. Przewodnik jest uporządkowany według typu zasobu. Zasób to typ elementu, który stanowi część YouTube, np. film, playlista lub subskrypcja. W przypadku każdego typu zasobu przewodnik zawiera co najmniej jedną reprezentację danych, a zasoby są reprezentowane jako obiekty JSON. Przewodnik zawiera też listę co najmniej jednej obsługiwanej metody (LIST, POST, DELETE itp.) dla każdego typu zasobu i 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 interfejsu API (w parametrze key) lub token OAuth 2.0. Klucz interfejsu API jest dostępny w panelu Dostępu do interfejsu API w Developer Console w przypadku Twojego projektu.

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

   Niektóre metody interfejsu API do pobierania zasobów mogą też obsługiwać parametry, które wymagają autoryzacji, lub zawierać dodatkowe metadane, gdy żądania są autoryzowane. Na przykład żądanie pobrania filmów przesłanych przez użytkownika może też zawierać 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 ten sposób: ?access_token=oauth2-token
   • Użyj nagłówka HTTP Authorization w ten sposób: Authorization: Bearer oauth2-token

   Pełne instrukcje wdrażania uwierzytelniania OAuth 2.0 w aplikacji znajdziesz w przewodniku po uwierzytelnianiu.

Typy zasobów

Działania

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ą ocenianie filmu, udostępnianie filmu, oznaczanie filmu jako ulubionego, przesyłanie filmu itp. Każdy zasób activity określa typ działania, kanał powiązany z działaniem i zasoby powiązane z 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 odnoszące się do elementu 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 pobrać zdarzenia powiązane z konkretnym kanałem lub z kanałem użytkownika.

Napisy

Zasób caption reprezentuje ścieżkę napisów w YouTube. Ścieżka napisów jest powiązana z dokładnie 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 odnoszące się do elementu 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 napisów jest zwracana w oryginalnym formacie, chyba że w żądaniu określono wartość parametru tfmt, oraz w oryginalnym języku, chyba że w żądaniu określono wartość parametru tlang.
insert	POST /captions	Przesyła ścieżkę z napisami.
list	GET /captions	Zwraca listę ścieżek z napisami powiązanych z określonym filmem. 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 z napisami możesz zmienić stan wersji roboczej ścieżki, przesłać nowy plik z napisami lub wykonać obie te czynności.

ChannelBanners

Zasób channelBanner zawiera adres URL, którego możesz użyć, aby ustawić 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
insert	POST /channelBanners/insert	Przesyła obraz na baner kanału do YouTube. Ta metoda obejmuje 2 pierwsze kroki z 3-etapowego procesu aktualizowania obrazu na banerze kanału: Wywołaj metodę channelBanners.insert, aby przesłać binarne dane obrazu do YouTube. Obraz musi mieć format 16:9 i rozmiar co najmniej 2048 x 1152 pikseli. Zalecamy przesłanie obrazu o wymiarach 2560 x 1440 pikseli. Wyodrębnij wartość właściwości url z odpowiedzi, którą interfejs API zwraca w kroku 1. Wywołaj metodę channels.update, aby zaktualizować ustawienia marki kanału. Ustaw wartość właściwości brandingSettings.image.bannerExternalUrl na adres URL uzyskany w kroku 2.

ChannelSections

channelSection Zasób zawiera informacje o zestawie filmów, które kanał wybrał do wyróżnienia. Na przykład sekcja może zawierać najnowsze lub najpopularniejsze filmy z kanału albo filmy z jednej lub kilku playlist.

Sekcje kanału są widoczne tylko wtedy, gdy kanał wyświetla treści w widoku przeglądania (a nie w widoku kanału). Aby umożliwić kanałowi wyświetlanie treści w widoku przeglądania, ustaw dla niego właściwość brandingSettings.channel.showBrowseView na true.

Kanał może 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 odnoszące się do elementu 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. Kanał może utworzyć maksymalnie 10 półek.
list	GET /channelSections	Zwraca listę zasobów channelSection, które spełniają kryteria żądania API.
update	PUT /channelSections	Aktualizuje sekcję kanału.

Kanały

Zasób channel zawiera informacje o kanale 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
list	GET /channels	Zwraca kolekcję zawierającą zero lub więcej zasobów channel, które spełniają kryteria żądania.
update	PUT /channels	Aktualizuje metadane kanału. Ta metoda obsługuje tylko aktualizacje obiektów channel zasobu brandingSettings i invideoPromotion 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 niego (jeśli takie istnieją). commentThread Zasób może reprezentować komentarze dotyczące filmu lub kanału.

Zarówno komentarz najwyższego poziomu, jak i odpowiedzi są w rzeczywistości comment zasobami zagnieżdżonymi 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. Niektóre komentarze nie mają też 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
list	GET /commentThreads	Zwraca listę wątków komentarzy, które pasują do parametrów żądania do interfejsu API.
insert	POST /commentThreads	Tworzy nowy komentarz najwyższego poziomu. Aby dodać odpowiedź do istniejącego komentarza, użyj metody comments.insert.

Komentarze

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

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

Metoda	Żądanie HTTP	Opis
Identyfikatory URI odnoszące się do elementu https://www.googleapis.com/youtube/v3
list	GET /comments	Zwraca listę komentarzy, które pasują do parametrów żądania do interfejsu API.
setModerationStatus	POST /comments/setModerationStatus	Ustawia stan moderowania co najmniej 1 komentarza. Żądanie 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.
delete	DELETE /comments	Usuwa komentarz.
update	PUT /comments	Modyfikuje komentarz.

I18nLanguages

i18nLanguage zasób identyfikuje język aplikacji obsługiwany przez witrynę YouTube. Język aplikacji jest 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 IP. Użytkownik może też ręcznie wybrać język interfejsu w stopce witryny YouTube.

Każdy i18nLanguage zasób zawiera kod języka i nazwę. Kod języka może być używany jako wartość parametru hl podczas wywoływania metod interfejsu API, takich jak 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
list	GET /i18nLanguages	Zwraca listę języków aplikacji obsługiwanych przez witrynę YouTube.

I18nRegions

i18nRegion to zasób, który określa 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 witryny YouTube region treści może być wybierany automatycznie na podstawie heurystyk, takich jak domena YouTube lub lokalizacja IP użytkownika. Użytkownik może też ręcznie wybrać region treści w stopce witryny YouTube.

Każdy zasób i18nRegion identyfikuje 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 jego reprezentacji i na liście właściwości.

Metoda	Żądanie HTTP	Opis
Identyfikatory URI odnoszące się do elementu https://www.googleapis.com/youtube/v3
list	GET /i18nRegions	Zwraca listę regionów, w których dostępne są treści w witrynie YouTube.

Użytkownicy

Zasób member reprezentuje wspierającego kanał w YouTube. Wspierający zapewnia twórcy regularne wsparcie finansowe i otrzymuje specjalne korzyści. Wspierający mogą na przykład czatować, gdy twórca włączy tryb czatu tylko dla wspierających.

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

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

MembershipsLevels

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

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

Metoda	Żądanie HTTP	Opis
Identyfikatory URI odnoszące się do elementu https://www.googleapis.com/youtube/v3
list	GET /membershipsLevels	Zwraca kolekcję zawierającą zero lub więcej zasobów membershipsLevel należących do kanału, który autoryzował żądanie interfejsu API. Poziomy są zwracane w niejawnej kolejności wyświetlania.

PlaylistItems

Zasób playlistItem identyfikuje inny zasób, np. film, który jest uwzględniony na playliście. Dodatkowo zasób playlistItem zawiera szczegóły dotyczące uwzględnionego zasobu, które odnoszą się konkretnie do sposobu wykorzystania tego zasobu na danej playliście.

YouTube używa też playlisty do identyfikowania listy przesłanych filmów na kanale. Każdy playlistItem na tej liście reprezentuje jeden przesłany film. Identyfikator playlisty możesz pobrać z channel resource dla danego kanału. Następnie możesz użyć metody playlistItems.list, aby dodać adres do listy.

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

Metoda	Żądanie HTTP	Opis
Identyfikatory URI odnoszące się do elementu 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 kolekcję elementów playlisty, które pasują do parametrów żądania interfejsu API. Możesz pobrać wszystkie elementy playlisty z określonej playlisty lub pobrać co najmniej 1 element playlisty według jego unikalnego identyfikatora.
update	PUT /playlistItems	Modyfikuje element playlisty. Możesz na przykład zaktualizować pozycję elementu na playliście.

Playlisty

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

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

• przesłane filmy,
• filmy ocenione pozytywnie (polubione);
• historia oglądania
• Do obejrzenia

Dokładniej mówiąc, te listy są powiązane z kanałem, czyli zbiorem filmów, playlist i innych informacji w YouTube należących do osoby, grupy lub firmy. Identyfikatory playlist dla każdej z tych list możesz pobrać z channel resource danego kanału.

 Możesz wtedy użyć metody playlistItems.list, aby pobrać dowolną z tych list. 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
delete	DELETE /playlists	Usuwa playlistę.
list	GET /playlists	Zwraca zbiór playlist, które pasują do parametrów żądania do interfejsu API. Możesz na przykład pobrać wszystkie playlisty, których właścicielem jest uwierzytelniony użytkownik, lub pobrać co najmniej jedną playlistę na podstawie jej unikalnego identyfikatora.
insert	POST /playlists	Tworzy playlistę.
update	PUT /playlists	Modyfikuje playlistę. Możesz na przykład zmienić tytuł, opis lub stan prywatności playlisty.

Szukaj

Wynik wyszukiwania zawiera informacje o filmie, kanale lub playliście w YouTube, które pasują do parametrów wyszukiwania określonych w żądaniu do interfejsu API. Wynik wyszukiwania wskazuje na unikalny zasób, np. 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
list	GET /search	Zwraca kolekcję 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 też skonfigurować zapytania tak, aby pobierały tylko określony typ zasobu.

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 w YouTube jedno z kilku działań, np. prześle film, oceni go lub skomentuje.

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

Metoda	Żądanie HTTP	Opis
Identyfikatory URI odnoszące się do elementu 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 spełniają kryteria żądania API.

Miniatury

Zasób thumbnail określa różne rozmiary obrazów miniatury powiązanych z zasobem. Te cechy 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 obrazów miniatury.
• Różne typy zasobów mogą definiować różne rozmiary obrazów miniaturowych 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 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 o wyższej rozdzielczości niż filmy w jakości innej niż HD.
• Każdy obiekt zawierający informacje o rozmiarze miniatury ma właściwości width i height. W przypadku tego obrazu właściwości szerokości i wysokości mogą jednak nie zostać zwrócone.
• 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 miał odpowiedni 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
set	POST /thumbnails/set	Przesyła do YouTube niestandardową miniaturę filmu i ustawia ją dla filmu.

VideoAbuseReportReasons

videoAbuseReportReason zawiera informacje o powodzie, dla którego film został oznaczony jako zawierający obraźliwe treści. Gdy aplikacja wywołuje metodę videos.reportAbuse, aby zgłosić film naruszający zasady, żądanie wykorzystuje informacje z zasobu videoAbuseReportReason do określenia powodu 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
list	GET /videoAbuseReportReasons	Pobierz listę powodów, które można wykorzystać do zgłaszania obraźliwych filmów.

VideoCategories

videoCategory zasób identyfikuje kategorię, która została lub może zostać 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
list	GET /videoCategories	Zwraca listę kategorii, które można powiązać z filmami w YouTube.

Filmy

video zasób 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 odnoszące się do elementu https://www.googleapis.com/youtube/v3
insert	POST /videos	Przesyła film do YouTube i opcjonalnie ustawia metadane filmu.
list	GET /videos	Zwraca listę filmów, które pasują do parametrów żądania do interfejsu API.
delete	DELETE /videos	Usuwa film w YouTube.
update	PUT /videos	Aktualizuje metadane filmu.
rate	POST /videos/rate	Dodawanie oceny filmu lub usuwanie jej.
getRating	GET /videos/getRating	Pobiera oceny, które autoryzowany użytkownik przyznał określonej liście filmów.
reportAbuse	POST /videos/reportAbuse	zgłosić film z powodu nieodpowiednich treści;

Znaki wodne

watermark zasób identyfikuje obraz wyświetlany podczas odtwarzania filmów z określonego kanału. Możesz też określić kanał docelowy, do którego będzie prowadzić link z obrazu, oraz szczegóły dotyczące czasu, które określają, kiedy znak wodny ma się pojawiać podczas odtwarzania filmów i jak długo ma być 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 odnoszące się do elementu 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 obraz znaku wodnego kanału.