API Reference

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Interfejs API danych YouTube pozwala umieścić funkcje normalnie wykonywane w witrynie YouTube w witrynie lub aplikacji. Poniższa lista zawiera różne typy zasobów, które możesz pobierać za pomocą interfejsu API. Interfejs API obsługuje też metody wstawiania, aktualizowania i usuwania wielu zasobów.

Z tego przewodnika dowiesz się, jak wykonywać wszystkie te operacje za pomocą interfejsu API. Przewodnik jest uporządkowany według typu zasobu. Zasób oznacza element, który wchodzi w skład YouTube, np. film, playlistę lub subskrypcję. W przypadku każdego typu zasobów w przewodniku znajdziesz co najmniej jedno przedstawienie danych, a zasoby będą przedstawione jako obiekty JSON. W tym przewodniku znajdziesz też listę typów obsługiwanych (LIST, POST, DELETE itd.) obsługiwanych przez poszczególne typy zasobów oraz wyjaśnienia, jak używać ich w swojej 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 (z parametrem key) lub udostępnić token OAuth 2.0. Twój klucz API jest dostępny w panelu Dostęp do interfejsów API Konsoli Play projektu.

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

    Dodatkowo niektóre metody pobierania zasobów przez API mogą obsługiwać parametry wymagające autoryzacji lub zawierać dodatkowe metadane w przypadku autoryzowanych żądań. Na przykład żądanie pobrania przesłanych filmów użytkownika może również obejmować filmy prywatne, jeśli dany użytkownik wyraził na to zgodę.

  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

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

Typy zasobów

Zadania

Zasób activity zawiera informacje o czynnościach wykonanych przez użytkownika lub kanał 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 działaniem, takie jak film, który został oceniony lub przesłany.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: 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 dotyczące konkretnego kanału lub kanału użytkownika.
insert POST /activities Uwaga: ta metoda została wycofana i nie jest już obsługiwana.

Napisy

Zasób caption reprezentuje ścieżkę napisów YouTube. Ścieżka napisów jest powiązana dokładnie z jednym filmem w YouTube.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku 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 i w jego 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 napisów powiązanych z określonym filmem. Pamiętaj, ż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ę napisów. Aktualizując ścieżkę napisów, możesz zmienić jej wersję, przesłać nowy plik napisów lub obie te opcje.

Banery kanału

Zasób channelBanner zawiera adres URL, którego można użyć do ustawienia nowo przesłanego obrazu jako banera kanału.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Prześlij obraz banera kanału do YouTube. Ta metoda pozwala wykonać 2 pierwsze kroki, które pozwolą zaktualizować obraz banera kanału:

  1. Wywołaj metodę channelBanners.insert, aby przesłać dane obrazu binarnego do YouTube. Obraz musi mieć współczynnik proporcji 16:9 i wymiary co najmniej 2048 x 1152 piksele. Zalecamy przesyłanie obrazu o wymiarach 2560 na 1440 pikseli.
  2. Wyodrębnij wartość właściwości url z odpowiedzi zwróconej przez interfejs API w kroku 1.
  3. 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.

Sekcje kanału

Zasób channelSection zawiera informacje o zestawie filmów, które poleca kanał. Na przykład sekcja może zawierać najnowsze przesłane filmy, najpopularniejsze filmy lub filmy z co najmniej jednej playlisty.

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

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

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Usunięcie sekcji kanału.
insert POST /channelSections Dodaje sekcję kanału do kanału uwierzytelnionego użytkownika. Kanał może mieć maksymalnie 10 półek.
list GET /channelSections Zwraca listę channelSection zasobów spełniających kryteria żądania do interfejsu API.
update PUT /channelSections Aktualizuje sekcję kanału.

Kanały

Zasób channel zawiera informacje o kanale w YouTube.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

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

Wątki komentarza

Zasób commentThread zawiera informacje na temat wątku komentarza w YouTube, który składa się z komentarza najwyższego poziomu i ewentualnych odpowiedzi do tego komentarza. Zasób commentThread może reprezentować komentarze do filmu lub kanału.

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

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: 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

Zasób comment zawiera informacje na temat pojedynczego komentarza w YouTube. Zasób comment może reprezentować komentarz dotyczący filmu lub kanału. Może to też być komentarz najwyższego poziomu lub odpowiedź na komentarz najwyższego poziomu.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: 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 Ustawia stan moderacji co najmniej jednego komentarza. Żądanie do interfejsu API musi zostać autoryzowane przez właściciela kanału lub filmu powiązanego z komentarzami.
insert POST /comments Powoduje utworzenie odpowiedzi na istniejący komentarz. Uwaga: aby utworzyć komentarz najwyższego poziomu, użyj metody commentThreads.insert.
markAsSpam POST /comments/markAsSpam Wskazuje, że co najmniej jeden komentarz należy oznaczyć jako spam.
delete DELETE /comments Usunięcie komentarza.
update PUT /comments Modyfikuje komentarz.

Kategorie przewodników

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 z tą różnicą, że przesyłający może przypisać kategorię filmów, ale tylko YouTube może przypisać kategorię kanału.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

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

I18nJęzyki

Zasób i18nLanguage określa język aplikacji, który obsługuje witryna YouTube. Język aplikacji można też określić jako język 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 ze stopki witryny YouTube.

Każdy zasób i18nLanguage zawiera kod języka oraz nazwę. Kodu języka można używać jako wartości parametru hl podczas wywoływania metod interfejsu API, np. videoCategories.list i guideCategories.list.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

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

Regiony I18n

Zasób i18nRegion określa obszar geograficzny, który użytkownik YouTube może wybrać jako preferowany region treści. Region treści można też określić jako język treści. W przypadku witryny YouTube region treści może być wybierany automatycznie na podstawie heurystyki, takiej jak domena YouTube lub lokalizacja adresu IP użytkownika. Użytkownik może też ręcznie wybrać odpowiedni region treści ze stopki witryny YouTube.

Każdy zasób i18nRegion określa 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.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: 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. Twórca zapewnia twórcom cykliczne wsparcie finansowe i specjalne korzyści. Twórcy mogą na przykład rozmawiać na czacie, gdy twórca włączy tryb tylko dla wspierających.

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

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
list GET /members Przedstawia osoby, które wspierają kanał (dawniej nazywane „sponsorami”). Żądanie interfejsu API musi być autoryzowane przez właściciela kanału.

Poziomy wspierania

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

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

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
list GET /membershipsLevels Zwraca zbiór zero lub więcej zasobów membershipsLevel należących do kanału, który autoryzował żądanie do interfejsu API. Poziomy są zwracane w domyślnej kolejności wyświetlania.

Elementy playlisty

Zasób playlistItem określa inny zasób, taki jak film, który znajduje się na playliście. Dodatkowo zasób playlistItem zawiera szczegółowe informacje o dołączeniu zasobu, który odnosi się do sposobu wykorzystania tego zasobu na tej playliście.

YouTube używa też playlisty do wskazywania listy filmów na kanale, przy czym każdy symbol playlistItem na tej liście reprezentuje 1 film. Identyfikator playlisty tej listy możesz pobrać z channel resource konkretnego kanału. Następnie możesz użyć metody playlistItems.list na liście.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Usunięcie elementu playlisty.
insert POST /playlistItems Dodaje zasób do playlisty.
list GET /playlistItems Zwraca kolekcję elementów playlisty pasujących do parametrów żądania do interfejsu API. Możesz pobrać wszystkie elementy playlisty z tej playlisty lub jej elementy według unikalnych identyfikatorów.
update PUT /playlistItems Modyfikuje element playlisty. Możesz na przykład zaktualizować pozycję elementu na playliście.

w playlistach.

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 utworzonych przez każdego użytkownika. Domyślnie playlisty są widoczne publicznie, ale mogą być publiczne lub prywatne.

YouTube wykorzystuje też playlisty do identyfikowania specjalnych kolekcji filmów na kanale, takich jak:

  • przesłane filmy
  • filmy oceniane pozytywnie (polubienia)
  • historia oglądania
  • Do obejrzenia
. Te listy są bardziej powiązane z kanałem, czyli zbiorem filmów, playlist lub innych informacji o YouTube dotyczących osoby, grupy lub firmy. Identyfikatory playlist dla każdej z tych list możesz pobrać z channel resource konkretnego kanału.

Możesz użyć metody playlistItems.list, aby pobrać dowolną z tych list. Możesz też dodawać pozycje do tych list lub je z nich usuwać, wywołując metody playlistItems.insert i playlistItems.delete.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
delete DELETE /playlists Usunięcie playlisty.
list GET /playlists Zwraca kolekcję playlist pasujących do parametrów żądania do interfejsu API. Możesz na przykład pobrać wszystkie playlisty, których właścicielem jest uwierzytelniony użytkownik, albo pobrać jedną lub więcej playlist według ich unikalnych identyfikatorów.
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, które odpowiadają parametrom wyszukiwania określonym w żądaniu do interfejsu API. Chociaż wynik wyszukiwania wskazuje zasób, który można jednoznacznie zidentyfikować, np. film, nie ma własnych danych trwałych.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
list GET /search Zwraca kolekcję wyników wyszukiwania, które pasują do parametrów zapytania określonych w żądaniu do interfejsu API. Domyślnie zestaw wyników wyszukiwania zawiera zasoby pasujące do video, channel i playlist, ale możesz też skonfigurować zapytania tak, aby pobierały tylko określony typ zasobów.

Subskrypcje

Zasób subscription zawiera informacje o subskrypcji użytkownika YouTube. Subskrypcja powiadamia użytkownika, gdy do kanału zostaną dodane nowe filmy lub gdy inny użytkownik wykona jedną z kilku czynności w YouTube, na przykład prześle film, oceni film lub skomentuje film.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

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

Miniatury

Zasób thumbnail określa różne rozmiary obrazów miniatur powiązanych z zasobem. Zwróć uwagę na następujące cechy obrazów miniatur:

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

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Przesłanie niestandardowej miniatury filmu do YouTube i ustawienie jej dla filmu.

Powód zgłoszenia filmu

Zasób videoAbuseReportReason zawiera informacje o przyczynie zgłoszenia filmu jako naruszającego zasady. Gdy Twoja aplikacja wywołuje metodę videos.reportAbuse, by zgłosić film naruszający zasady, żądanie używa informacji z zasobu videoAbuseReportReason, aby zidentyfikować przyczynę zgłoszenia filmu.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Pobierz listę przyczyn, które mogą służyć do zgłoszenia filmu naruszającego zasady.

Kategorie filmów

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

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku 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.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
insert POST /videos Przesłanie filmu do YouTube i opcjonalnie ustawienie jego metadanych.
list GET /videos Zwraca listę filmów, które pasują 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ę” albo usuń ocenę z filmu.
getRating GET /videos/getRating Pobiera oceny, które autoryzowany użytkownik dodał do listy określonych filmów.
reportAbuse POST /videos/reportAbuse Zgłoś film zawierający nieodpowiednie treści.

Znaki wodne

Zasób watermark określa obraz, który wyświetla się podczas odtwarzania filmów na danym kanale. Możesz też podać kanał docelowy, do którego będzie prowadził obraz, a także szczegóły czasowe, które określają, kiedy znak wodny będzie się wyświetlać podczas odtwarzania filmu i jak długo będzie on widoczny.

Aby dowiedzieć się więcej o tym zasobie, zobacz jego reprezentowanie zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI w stosunku do: https://www.googleapis.com/youtube/v3
set POST /watermarks/set Przesyła obraz ze znakiem wodnym do YouTube i ustawia go jako kanał.
unset POST /watermarks/unset Usuwa obraz wodny kanału.