Interfejs YouTube Data API pozwala włączyć do własnej witryny lub aplikacji funkcje, które zwykle są wykonywane w YouTube. Na listach poniżej znajdziesz różne typy zasobów, które można pobrać przy użyciu interfejsu API. Interfejs API obsługuje też metody wstawiania, aktualizowania i usuwania wielu z tych 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 reprezentuje typ elementu, który stanowi część usługi YouTube. Może to być np. film, playlista lub subskrypcja. W przypadku każdego typu zasobu w przewodniku znajduje się co najmniej 1 reprezentacja danych, a zasoby są przedstawiane jako obiekty JSON. Przewodnik zawiera też informacje o co najmniej 1 obsługiwanych metodach (LIST
, POST
, DELETE
itp.) dla każdego typu zasobów oraz wyjaśnia, jak używać tych metod w aplikacji.
Wywoływanie interfejsu API
Żądania do interfejsu YouTube Data API muszą spełniać te wymagania:
-
Każde żądanie musi określać klucz interfejsu API (z parametrem
key
) lub podawać 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. -
Do każdego żądania wstawienia, aktualizacji i usunięcia musisz wysłać token autoryzacji. Musisz też wysłać token autoryzacji w przypadku każdego żądania pobierającego prywatne dane uwierzytelnionego użytkownika.
Dodatkowo niektóre metody interfejsu API do pobierania zasobów mogą obsługiwać parametry wymagające autoryzacji lub zawierać dodatkowe metadane po autoryzacji żądań. Na przykład żądanie pobrania filmów przesłanych przez użytkownika może też zawierać filmy prywatne, jeśli dany użytkownik wyraził na to zgodę.
-
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 takiego nagłówka HTTP
Authorization
:Authorization: Bearer
oauth2-token
Pełne instrukcje dotyczące implementowania uwierzytelniania OAuth 2.0 w aplikacji znajdziesz w przewodniku uwierzytelniania.
- Użyj parametru zapytania
Typy zasobów
Zadania
Zasób activity
zawiera informacje na temat działań wykonanych w YouTube przez określony kanał lub użytkownika. Działania zgłaszane w kanałach aktywności obejmują ocenę filmu, udostępnienie go, oznaczenie go jako ulubionego, przesłanie filmu itd. Każdy zasób activity
określa typ działania, powiązany z nim kanał oraz zasoby powiązane z tym działaniem, np. film, który został oceniony lub przesłany.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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ń aktywności na kanale, które spełniają kryteria żądania. Możesz na przykład pobrać zdarzenia powiązane z określonym kanałem lub z własnym 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ę napisów w YouTube. Ścieżka napisów jest powiązana tylko z jednym filmem w YouTube.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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ę napisów. |
download |
GET /captions/id |
Pobiera ścieżkę z napisami. Ścieżka napisów jest zwracana w pierwotnym formacie, chyba że w żądaniu określono wartość parametru tfmt 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 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ę z napisami. Podczas aktualizowania ścieżki z napisami możesz zmienić stan wersji roboczej ścieżki, przesłać nowy plik z napisami lub jedno i drugie. |
Banery kanału
Zasób channelBanner
zawiera URL, którego można użyć do ustawienia nowo przesłanego obrazu jako obrazu banera kanału.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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. Ta metoda przedstawia dwa pierwsze kroki trzyetapowego procesu aktualizowania obrazu banera kanału:
|
Sekcje kanału
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 co najmniej 1 playlisty.
Pamiętaj, że sekcje kanału są widoczne tylko wtedy, gdy zawartość kanału jest widoczna w widoku przeglądania (a nie w widoku obszaru aktywności). Aby umożliwić wyświetlanie treści na kanale w widoku przeglądania, ustaw w przypadku określonego kanału właściwość brandingSettings.channel.showBrowseView
na true
.
Kanał może utworzyć maksymalnie 10 półek.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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. Kanał może utworzyć maksymalnie 10 półek. |
list |
GET /channelSections |
Zwraca listę channelSection zasobów, 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.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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 ta metoda obsługuje obecnie tylko aktualizacje obiektów brandingSettings i invideoPromotion zasobu channel oraz ich właściwości podrzędnych. |
Wątki komentarzy
Zasób commentThread
zawiera informacje o wątku komentarzy w YouTube, który składa się z komentarza najwyższego poziomu oraz odpowiedzi do tego komentarza (jeśli istnieją). Zasób commentThread
może reprezentować komentarze na temat 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
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 na niektóre komentarze nie mają odpowiedzi.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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. Komentarz może też być komentarzem najwyższego poziomu lub odpowiedzią na komentarz najwyższego poziomu.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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 jednego lub większej liczby komentarzy. Żą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. |
Kategorie przewodnika
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ć.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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. |
Języki
Zasób i18nLanguage
wskazuje język aplikacji obsługiwany przez witrynę YouTube. Język aplikacji może być też określany jako język interfejsu użytkownika. 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ć język interfejsu ze stopki witryny YouTube.
Każdy zasób i18nLanguage
określa kod języka i nazwę. Kod języka może być używany jako wartość parametru hl
podczas wywoływania metod API takich jak videoCategories.list
czy guideCategories.list
.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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. |
Regiony i regiony
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 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
określa kod regionu i nazwę. 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
.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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 oferuje cykliczną pomoc finansową twórcy i otrzymuje specjalne korzyści. Na przykład wspierający mogą czatować, gdy twórca włączy tryb tylko dla wspierających w czacie.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację zasobu i listę właściwości.
Metoda | Żądanie HTTP | Opis |
---|---|---|
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3 |
||
list |
GET /members |
Wyświetla listę wspierających (dawniej nazywanych sponsorami) kanału. Żądanie do interfejsu API musi być autoryzowane przez właściciela kanału. |
Poziomy wspierania
Zasób membershipsLevel
określa poziom cen dla twórcy, który autoryzował żądanie do interfejsu API.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację zasobu i listę 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 0 lub więcej zasobów membershipsLevel należących do kanału, który autoryzował żądanie do interfejsu API. Poziomy są zwracane w niejawnej kolejności wyświetlania. |
Elementy playlisty
Zasób playlistItem
identyfikuje inny zasób (np. film) uwzględniony w playliście. Dodatkowo zasób playlistItem
zawiera szczegółowe informacje na temat uwzględnionego zasobu, które odnoszą się konkretnie do sposobu jego wykorzystania na danej playliście.
YouTube używa też playlisty do wskazania listy przesłanych filmów na kanał. Każdy element playlistItem
na tej liście oznacza 1 przesłany film. Identyfikator playlisty dla tej listy możesz pobrać z channel resource
dla danego kanału. Następnie możesz użyć metody playlistItems.list
do wyświetlania listy.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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 zbiór elementów playlisty, które pasują do parametrów żądania do interfejsu API. Możesz pobrać wszystkie elementy playlisty znajdujące się na określonej playliście lub co najmniej jeden element, podając ich unikalne identyfikatory. |
update |
PUT /playlistItems |
Modyfikuje element playlisty. Możesz na przykład zmienić jego pozycję 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 filmy wideo (polubione)
- historia oglądania
- Do obejrzenia
channel resource
dla danego kanału.Następnie możesz użyć metody
playlistItems.list
, aby pobrać dowolną z tych list. Możesz też dodawać elementy do tych list i je z nich usuwać, wywołując metody playlistItems.insert
i playlistItems.delete
.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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 zbiór playlist pasujących do parametrów żądania do interfejsu API. Możesz na przykład pobrać wszystkie playlisty należące do uwierzytelnionego użytkownika 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 ustawienia prywatności playlisty. |
Wyszukiwarka
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 zasób, który można zidentyfikować, np. film, ale nie ma własnych trwałych danych.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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 też skonfigurować zapytania w taki sposób, 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 na kanale dodawane są nowe filmy lub gdy inny użytkownik wykona jedną z kilku czynności w YouTube, takich jak przesłanie filmu, wystawienie oceny lub skomentowanie filmu.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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 pasujące do kryteriów żądania do interfejsu API. |
Miniatury
Zasób thumbnail
określa różne rozmiary miniatur powiązanych z danym zasobem. Pamiętaj o tych cechach miniatur:
- Właściwość
snippet.thumbnails
zasobu to obiekt, który wskazuje 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 obrazu miniatury. - Różne rodzaje 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 zasobu
default
w przypadku zasobuvideo
ma zwykle wymiary 120 x 90 pikseli, a w przypadku zasobuchannel
miniaturadefault
ma zwykle wymiary 88 x 88 pikseli. - Zasoby tego samego typu mogą nadal mieć różne rozmiary miniatur w przypadku niektórych obrazów w zależności od rozdzielczości oryginalnego obrazu lub treści przesłanej 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 właściwościheight
. 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 ma wymaganych wymiarów, jego rozmiar zostanie zmieniony tak, aby pasował do właściwego rozmiaru, bez zmiany proporcji. Obraz nie jest przycięty, ale może zawierać czarne paski informujące o prawidłowym rozmiarze.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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ę filmu do YouTube i ustawia ją jako film. |
Przyczyny zgłaszania nadużyć do filmów
Zasób videoAbuseReportReason
zawiera informacje o przyczynie oznaczenia filmu jako zawierającego nieodpowiednie treści. Gdy aplikacja wywołuje metodę videos.reportAbuse
, aby zgłosić nadużycie wideo, żądanie korzysta z informacji z zasobu videoAbuseReportReason
, aby ustalić przyczynę zgłoszenia filmu.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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. |
Kategorie wideo
Zasób videoCategory
określa kategorię, która została lub może być powiązana z przesłanymi filmami.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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.
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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, 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 ocenę filmu lub ocenę treści jako „Nie podoba mi się” lub usuń ocenę z filmu. |
getRating |
GET /videos/getRating |
Pobiera oceny, które autoryzowany użytkownik przyznał liście określonych filmów. |
reportAbuse |
POST /videos/reportAbuse |
Zgłoś film, który zawiera obraźliwe treści. |
Znaki wodne
Zasób watermark
określa obraz, który wyświetla się podczas odtwarzania filmów na konkretnym kanale. Możesz też określić kanał docelowy, do którego będzie link z obrazem, a także szczegóły czasu (w tym te decydujące o tym, kiedy znak wodny pojawi się podczas odtwarzania filmu oraz jak długo jest on widoczny).
Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę 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 jako kanał. |
unset |
POST /watermarks/unset |
Usuwa znak wodny kanału. |