Wprowadzenie
Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje, które współpracują z YouTube. Opisuje podstawowe zagadnienia dotyczące YouTube i samego interfejsu API. Znajdziesz tam też omówienie różnych funkcji obsługiwanych przez ten interfejs API.
Zanim rozpoczniesz
-
Musisz mieć konto Google, aby uzyskać dostęp do konsoli interfejsu Google API, zażądać klucza API i zarejestrować swoją aplikację.
-
Utwórz projekt w Google Developers Console i uzyskaj dane uwierzytelniające, aby Twoja aplikacja mogła przesyłać żądania do interfejsu API.
-
Po utworzeniu projektu upewnij się, że YouTube Data API jest jedną z usług, w których rejestrujesz aplikację:
- Otwórz Konsolę interfejsów API i wybierz zarejestrowany przed chwilą projekt.
- Wejdź na stronę Włączone interfejsy API. Na liście interfejsów API sprawdź, czy YouTube Data API v3 ma stan WŁ.
-
Jeśli Twoja aplikacja ma wykorzystywać którąś z metod API, które wymagają autoryzacji użytkownika, przeczytaj przewodnik dotyczący autoryzacji, aby dowiedzieć się, w jaki sposób zaimplementować protokół OAuth 2.0.
-
Wybierz bibliotekę klienta, aby ułatwić sobie implementację interfejsu API.
-
Zapoznaj się z podstawowymi pojęciami dotyczącymi formatu danych JSON (JavaScript Object Notation). JSON to powszechny, niezależny od języka format danych, który w prosty sposób prezentuje dowolne struktury danych. Więcej informacji znajdziesz na stronie json.org.
Zasoby i typy zasobów
Zasób to konkretna jednostka danych z unikalnym identyfikatorem. W tabeli poniżej opisujemy różne typy zasobów, z których możesz korzystać za pomocą interfejsu API.
Zasoby | |
---|---|
activity |
Zawiera informacje o czynnościach wykonanych przez użytkownika w witrynie YouTube. Informacje o działaniach użytkowników zgłaszane w kanałach aktywności obejmują między innymi ocenianie filmu, udostępnianie go, oznaczanie filmu jako ulubionego oraz publikowanie newslettera kanału. |
channel |
Zawiera informacje o 1 kanale w YouTube. |
channelBanner |
Określa adres URL, którego należy użyć, aby ustawić nowo przesłany obraz jako baner kanału. |
channelSection |
Zawiera informacje o zestawie filmów polecanych przez kanał. Sekcja może na przykład zawierać najnowsze filmy na kanale, najpopularniejsze filmy lub filmy z co najmniej jednej playlisty. |
guideCategory |
Identyfikuje kategorię skojarzoną przez YouTube z kanałami na podstawie ich treści lub innych wskaźników, takich jak popularność. Kategorie w wytycznych pomagają uporządkować kanały w sposób, który ułatwia użytkownikom YouTube znajdowanie treści, których szukają. Kanały mogą być powiązane z co najmniej jedną kategorią przewodnika, ale nie możemy zagwarantować, że pojawią się one w żadnej z tych kategorii. |
i18nLanguage |
Określa język aplikacji obsługiwany w witrynie YouTube. Język aplikacji można też określić jako język interfejsu. |
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. |
playlist |
Reprezentuje jedną 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. |
playlistItem |
Określa zasób, np. film, który jest częścią playlisty. Zasób playlistyItem zawiera także szczegółowe informacje o sposobie wykorzystania zasobu na playliście. |
search result |
Zawiera informacje o filmie, kanale lub playliście w YouTube pasujące do parametrów wyszukiwania określonych 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. |
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. |
thumbnail |
Identyfikuje miniatury obrazów powiązane z zasobem. |
video |
Reprezentuje jeden film w YouTube. |
videoCategory |
Identyfikuje kategorię, która była lub może być powiązana z przesłanymi filmami. |
watermark |
Określa obraz, który wyświetla się podczas odtwarzania filmów z danego kanału. Właściciel kanału może też określić kanał docelowy, do którego prowadzi obraz, oraz informacje o czasie, co pozwala określić, kiedy znak wodny ma się wyświetlać podczas odtwarzania filmu, a następnie przez jaki czas będzie widoczny. |
Pamiętaj, że w wielu przypadkach zasób zawiera odwołania do innych zasobów. Na przykład właściwość snippet.resourceId.videoId
zasobu playlistItem
określa zasób wideo, który z kolei zawiera pełne informacje o filmie. Inny przykład wyniku wyszukiwania zawiera właściwość videoId
, playlistId
lub channelId
, która identyfikuje określony film, playlistę lub kanał.
Obsługiwane operacje
Poniższa tabela przedstawia najczęstsze metody obsługiwane przez interfejs API. Niektóre zasoby obsługują też inne metody, które pozwalają wykonywać bardziej szczegółowe funkcje. Metoda videos.rate
pozwala na przykład powiązać ocenę użytkownika z filmem, a metoda thumbnails.set
przesyła do YouTube obraz miniatury i kojarzy go z filmem.
Zarządzanie | |
---|---|
list |
Pobiera (GET ) listę z 0 lub większą liczbą zasobów. |
insert |
Tworzy (POST ) nowy zasób. |
update |
Modyfikuje (PUT ) istniejący zasób, aby odzwierciedlał on dane w żądaniu. |
delete |
Usuwa (DELETE ) konkretny zasób. |
Interfejs API obsługuje obecnie metody wyświetlania wszystkich obsługiwanych typów zasobów oraz obsługuje operacje zapisu w wielu zasobach.
Poniższa tabela przedstawia operacje, które są obsługiwane w przypadku różnych typów zasobów. Operacje wstawiania, aktualizowania lub usuwania zasobów zawsze wymagają autoryzacji użytkownika. W niektórych przypadkach metody list
obsługują zarówno autoryzowane, jak i nieautoryzowane żądania. Nieautoryzowane żądania pobierają tylko dane publiczne, natomiast autoryzowane żądania mogą też pobierać informacje dotyczące aktualnie uwierzytelnionego użytkownika lub te prywatne.
Obsługiwane operacje | ||||
---|---|---|---|---|
list | insert | update | delete | |
activity |
||||
caption |
||||
channel |
||||
channelBanner |
||||
channelSection |
||||
comment |
||||
commentThread |
||||
guideCategory |
||||
i18nLanguage |
||||
i18nRegion |
||||
playlist |
||||
playlistItem |
||||
search result |
||||
subscription |
||||
thumbnail |
||||
video |
||||
videoCategory |
||||
watermark |
Wykorzystanie limitu
YouTube Data API używa limitu, aby zapewnić, że deweloperzy korzystają z usługi zgodnie z oczekiwaniami, i nie tworzyć aplikacji, które w sposób nieuczciwy obniżają jakość usług lub ograniczają dostęp innym użytkownikom. Wszystkie żądania do interfejsu API, w tym nieprawidłowe żądania, wiążą się z kosztami co najmniej 1 punktu. Limit dostępny dla Twojej aplikacji znajdziesz w API Console.
Projekty,które włączają interfejs YouTube Data API, używają domyślnego przydziału wynoszącego 10 000 jednostek dziennie. Jest to wystarczająca ilość przytłaczającej większości użytkowników interfejsu API. Domyślny limit, który może ulec zmianie, pomaga nam optymalizować przydzielanie limitów i skalować naszą infrastrukturę w sposób bardziej odpowiedni dla użytkowników interfejsu API. Wykorzystanie limitu możesz sprawdzić na stronie Limity w konsoli API.
Uwaga: jeśli osiągniesz limit, możesz poprosić o zwiększenie limitu, wypełniając formularz prośby o zwiększenie limitu usług YouTube API.
Obliczam wykorzystanie limitu
Google oblicza wykorzystanie limitu, przypisując koszt do każdego żądania. Różne rodzaje operacji mają różne koszty. Przykład:
- Operacja odczytu, która pobiera listę zasobów (kanałów, filmów, playlist), zwykle kosztuje 1 jednostkę.
- Operacja zapisu, która tworzy, aktualizuje lub usuwa zasób, zwykle kosztuje
50
jednostek. - Jedno zapytanie kosztuje
100
jednostki. - Koszt przesłania filmu wynosi
1600
jednostki.
Tabela Koszty żądań dla interfejsu API pokazuje koszt każdej metody interfejsu API. Biorąc pod uwagę te reguły, możesz oszacować liczbę żądań, które Twoja aplikacja może wysyłać dziennie bez przekraczania limitu.
Częściowe zasoby
Interfejs API umożliwia pobieranie informacji o częściach zasobów, a właściwie wymaga, aby aplikacje mogły przenosić, analizować i przechowywać niepotrzebne dane. Takie podejście zapewnia też wydajniejsze korzystanie z interfejsu API, CPU i zasobów pamięci.
Interfejs API obsługuje 2 parametry żądania, które zostały objaśnione w kolejnych sekcjach. Dzięki nim możesz zidentyfikować właściwości zasobów, które powinny być dołączane do odpowiedzi interfejsu API.
- Parametr
part
określa grupy właściwości, które powinny być zwracane dla zasobu. - Parametr
fields
filtruje odpowiedź interfejsu API, by wyświetlać tylko określone właściwości w żądanych częściach zasobów.
Jak używać parametru part
Parametr part
jest wymagany w przypadku każdego żądania interfejsu API, które pobiera lub zwraca zasób. Ten parametr określa jedną lub więcej właściwości zasobów najwyższego poziomu (niezagnieżdżonych), które powinny być uwzględnione w odpowiedzi interfejsu API. Na przykład zasób video
składa się z następujących elementów:
snippet
contentDetails
fileDetails
player
processingDetails
recordingDetails
statistics
status
suggestions
topicDetails
Wszystkie te części to obiekty zawierające właściwości zagnieżdżone. Możesz traktować je jako grupy pól metadanych, które serwer interfejsu API może pobrać (lub nie). W związku z tym parametr part
wymaga wybrania komponentów zasobów, których aplikacja faktycznie używa. To wymaganie ma 2 główne cele:
- Zmniejsza to opóźnienie, ponieważ nie pozwala czasowi serwera API na pobieranie pól metadanych, których nie używa Twoja aplikacja.
- Zmniejsza użycie przepustowości, zmniejszając (lub eliminując) niepotrzebne dane, które aplikacja może pobrać.
W miarę dodawania kolejnych zasobów liczba korzyści będzie rosnąć, ponieważ aplikacja nie będzie prosić o wprowadzenie nowych właściwości, których nie obsługuje.
Jak używać parametru fields
Parametr fields
filtruje odpowiedź interfejsu API, która zawiera tylko części zasobów wskazane w wartości parametru part
, tak by w odpowiedzi zawierała tylko określony zestaw pól. Parametr fields
umożliwia usuwanie właściwości zagnieżdżonych z odpowiedzi interfejsu API i tym samym zmniejsza wykorzystanie przepustowości. (Parametru part
nie można użyć do filtrowania zagnieżdżonych właściwości z odpowiedzi).
Te reguły wyjaśniają obsługiwaną składnię wartości parametru fields
, która jest luźno oparta na składni XPath:
- Aby wybrać wiele pól, użyj listy rozdzielonej przecinkami (
fields=a,b
). - Aby oznaczyć wszystkie pola, użyj symbolu wieloznacznego (
fields=*
) jako symbolu wieloznacznego. - Użyj nawiasów (
fields=a(b,c)
), aby określić grupę zagnieżdżonych właściwości, które zostaną uwzględnione w odpowiedzi interfejsu API. - Aby zidentyfikować zagnieżdżoną właściwość, użyj ukośnika (
fields=a/b
).
W praktyce te reguły umożliwiają zwykle pobieranie kilku różnych wartości parametru fields
w celu pobrania tej samej odpowiedzi interfejsu API. Jeśli chcesz na przykład pobrać identyfikator, tytuł i pozycję każdego elementu playlisty, możesz użyć dowolnej z tych wartości:
fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
fields=items(id,snippet/title,snippet/position)
fields=items(id,snippet(title,position))
Uwaga: tak jak każda wartość parametru zapytania, wartość parametru fields
musi być zakodowana na potrzeby adresu URL. W przykładach w tym dokumencie kodowanie zostało pominięte, aby łatwiej je odczytać.
Przykładowe żądania częściowe
W przykładach poniżej pokazujemy, jak używać parametrów part
i fields
, aby mieć pewność, że odpowiedzi API zawierają tylko dane używane przez aplikację:
- Przykład 1 zwraca zasób wideo zawierający 4 części oraz właściwości
kind
ietag
. - Przykład 2 zwraca zasób wideo zawierający 2 części oraz właściwości
kind
ietag
. - W przykładzie 3 zwracany jest zasób wideo zawierający 2 części, ale z wyłączeniem właściwości
kind
ietag
. - Przykład 4 zwraca zasób wideo zawierający 2 części, ale z wyjątkiem
kind
ietag
, a także niektóre właściwości zagnieżdżone w obiekciesnippet
zasobu.
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status Description: This example retrieves avideo
resource and identifies several resource parts that should be included in the API response. API response:{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "contentDetails": { "duration": "PT15M51S", "aspectRatio": "RATIO_16_9" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" }, "status": { "uploadStatus": "STATUS_PROCESSED", "privacyStatus": "PRIVACY_PUBLIC" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics Description: This example modifies thepart
parameter value so that thecontentDetails
andstatus
properties are not included in the response. API response:{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics&fields=items(id,snippet,statistics) Description: This example adds thefields
parameter to remove allkind
andetag
properties from the API response. API response:{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics Description: This example modifies thefields
parameter from example 3 so that in the API response, each video resource'ssnippet
object only includes thechannelId
,title
, andcategoryId
properties. API response:{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
Optymalizacja skuteczności
Korzystanie z tagów ETag
ETags, standardowa część protokołu HTTP, umożliwia aplikacjom odwoływanie się do konkretnej wersji konkretnego zasobu interfejsu API. Może to być cały kanał lub element z tego pliku. Ta funkcja obsługuje te przypadki użycia:
-
Pamięć podręczna i pobieranie warunkowe – aplikacja może buforować zasoby interfejsu API i ich tagi ETag. Gdy aplikacja ponownie poprosi o zapisany zasób, określa ETag powiązany z tym zasobem. Jeśli zasób się zmieni, interfejs API zwróci zmodyfikowany zasób i tag ETag powiązany z tą wersją zasobu. Jeśli zasób nie został zmieniony, interfejs API zwraca odpowiedź HTTP 304 (
Not Modified
), co oznacza, że zasób się nie zmienił. Twoja aplikacja może zmniejszyć czas oczekiwania i wykorzystywać przepustowość, konfigurując w ten sposób zasoby z pamięci podręcznej.Biblioteki klienta do interfejsów API Google różnią się obsługą tagów ETag. Na przykład biblioteka klienta JavaScript obsługuje tagi ETag za pomocą białej listy dozwolonych nagłówków żądań zawierających
If-Match
iIf-None-Match
. Biała lista umożliwia normalne zapisywanie w przeglądarce, tak aby w przypadku, gdy tag ETag zasobu się nie zmienił, może on być wyświetlany z pamięci podręcznej przeglądarki. Z kolei klient Obj-C nie obsługuje tagów ETag. -
Ochrona przed przypadkowymi zastąpieniami zmian – znaczniki ETag pomagają uniknąć przypadkowego zastępowania zmian przez wielu klientów interfejsu API. Podczas aktualizowania lub usuwania zasobu aplikacja może określić jego tag ETag. Jeśli ETag nie pasuje do najnowszej wersji tego zasobu, żądanie API się nie powiedzie.
Stosowanie znaczników ETag w aplikacji przynosi kilka korzyści:
- Interfejs API szybciej reaguje na żądania dotyczące pamięci podręcznej, ale niezmienionych zasobów, co pozwala skrócić czas oczekiwania i zmniejszyć wykorzystanie przepustowości.
- Aplikacja nie przypadkiem nie zastąpi zmian w zasobie utworzonym za pomocą innego klienta API.
Google APIs Client Library for JavaScript obsługuje nagłówki żądań If-Match
i If-None-Match
, dzięki czemu tagi ETag działają w kontekście normalnej pamięci podręcznej przeglądarki.
Korzystanie z gzip
Możesz też zmniejszyć przepustowość potrzebną do każdej odpowiedzi interfejsu API, włączając kompresję gzip. Choć aplikacja potrzebuje więcej czasu na skompresowanie odpowiedzi interfejsu API, korzyści zużywania mniejszej liczby zasobów sieciowych zwykle przewyższają ten koszt.
Aby odebrać odpowiedź zakodowaną w formacie gzip, musisz wykonać 2 czynności:
- Ustaw nagłówek żądania HTTP
Accept-Encoding
nagzip
. - Zmodyfikuj klienta użytkownika, aby zawierała ciąg
gzip
.
Przykładowe nagłówki HTTP pokazują te wymagania dotyczące kompresji gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)