Wprowadzenie
Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje współpracujące z YouTube. Wyjaśniamy w nim podstawowe pojęcia związane z YouTube i samym interfejsem API. Omówiono w nim też różne funkcje obsługiwane przez interfejs API.
Zanim zaczniesz
-
Aby uzyskać dostęp do konsoli interfejsów API Google, poprosić o klucz interfejsu API i zarejestrować aplikację, musisz mieć konto Google.
-
Utwórz projekt w Google Developers Console i uzyskaj dane logowania, aby aplikacja mogła przesyłać żądania do interfejsu API.
-
Po utworzeniu projektu sprawdź, czy YouTube Data API należy do usług, w których Twoja aplikacja jest zarejestrowana:
- Otwórz Konsolę interfejsów API i wybierz zarejestrowany przed chwilą projekt.
- Wejdź na stronę Włączone interfejsy API. Sprawdź, czy na liście interfejsów API 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.
-
zapoznać się z podstawowymi pojęciami dotyczącymi formatu danych JSON (JavaScript Object Notation), JSON to popularny, niezależny od języka format danych, który w prosty sposób przedstawia dowolne struktury danych w formie tekstowej. Więcej informacji znajdziesz na stronie json.org.
Zasoby i typy zasobów
Zasób to pojedyncza jednostka danych o unikalnym identyfikatorze. Tabela poniżej zawiera opis różnych typów zasobów, z których można korzystać przy użyciu interfejsu API.
Zasoby | |
---|---|
activity |
Zawiera informacje o działaniach podejmowanych przez danego użytkownika w YouTube. Działania użytkowników zgłaszane w kanałach aktywności obejmują między innymi ocenianie filmów, udostępnianie filmów, oznaczanie filmów jako ulubionych i publikowanie biuletynów na kanale. |
channel |
Zawiera informacje na temat pojedynczego kanału YouTube. |
channelBanner |
Określa adres URL, który ma być używany do ustawienia nowo przesłanego obrazu jako obrazu banera kanału. |
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 jednej playlisty. |
guideCategory |
Identyfikuje kategorię, którą YouTube wiąże z kanałami na podstawie ich treści lub innych wskaźników, takich jak popularność. Kategorie przewodników porządkują kanały w taki sposób, aby użytkownicy YouTube mogli łatwiej znajdować interesujące ich treści. Kanały mogą być powiązane z co najmniej 1 kategorią przewodnika, ale nie ma gwarancji, że będą należeć do żadnej z nich. |
i18nLanguage |
Identyfikuje język aplikacji obsługiwany przez witrynę YouTube. Język aplikacji może być też określany jako język interfejsu użytkownika. |
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 pojedynczą playlistę 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 |
Identyfikuje zasób (np. film), który jest częścią playlisty. Zasób playlistItem zawiera też szczegółowe informacje o sposobie wykorzystania uwzględnionego zasobu w playliście. |
search result |
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. |
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. |
thumbnail |
Identyfikuje miniatury obrazów powiązanych z zasobem. |
video |
Reprezentuje pojedynczy film w YouTube. |
videoCategory |
Identyfikuje kategorię, która była lub może być powiązana z przesyłanymi filmami. |
watermark |
Identyfikuje obraz, który wyświetla się podczas odtwarzania filmów z określonego kanału. Właściciel kanału może też określić kanał docelowy, do którego będzie link obrazu, oraz szczegółowe informacje o czasie wyświetlania znaku wodnego podczas odtwarzania filmu oraz czas, przez jaki obraz jest 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: wynik wyszukiwania zawiera właściwość videoId
, playlistId
lub channelId
, która wskazuje zasób filmu, playlisty lub kanału.
Obsługiwane operacje
W tabeli poniżej znajdziesz najczęściej używane metody obsługiwane przez interfejs API. Niektóre zasoby obsługują również inne metody, które wykonują funkcje bardziej specyficzne dla tych zasobów. Na przykład metoda videos.rate
wiąże ocenę użytkownika z filmem, a metoda thumbnails.set
przesyła do YouTube obraz miniatury filmu i wiąże go z filmem.
Operacje | |
---|---|
list |
Pobiera (GET ) listę zero lub więcej zasobów. |
insert |
Powoduje utworzenie (POST ) nowego zasobu. |
update |
Modyfikuje (PUT ) istniejący zasób, aby odzwierciedlał dane z Twojego żądania. |
delete |
Usuwa (DELETE ) określony zasób. |
Obecnie ten interfejs API obsługuje metody wyświetlania listy wszystkich obsługiwanych typów zasobów, a także obsługuje operacje zapisu w przypadku wielu zasobów.
Poniższa tabela przedstawia operacje, które są obsługiwane w przypadku różnych typów zasobów. Operacje wstawiania, aktualizowania i usuwania zasobów zawsze wymagają autoryzacji użytkownika. W niektórych przypadkach metody list
obsługują zarówno żądania autoryzowane, jak i nieautoryzowane. Nieuprawnione żądania pobierają tylko dane publiczne, natomiast autoryzowane żądania mogą pobrać informacje o obecnie uwierzytelnionym użytkowniku lub 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 wykorzystuje limit, aby mieć pewność, że deweloperzy będą korzystać z usługi zgodnie z oczekiwaniami i nie tworzą aplikacji, które nieuczciwie obniżają jakość usług lub ograniczają dostęp do nich innym użytkownikom. Wszystkie żądania do interfejsu API, w tym żądania nieprawidłowe, skutkują kosztem co najmniej jednego punktu. Limit dostępny dla Twojej aplikacji znajdziesz w API Console.
Projekty, w których można korzystać z interfejsu YouTube Data API, mają domyślny limit 10 000 jednostek dziennie, co jest wystarczające dla zdecydowanej większości użytkowników tego interfejsu. Domyślny limit, który może ulec zmianie, pomaga nam optymalizować przydziały limitów i skalować naszą infrastrukturę w bardziej odpowiedni sposób dla użytkowników interfejsu API. Wykorzystanie limitu możesz sprawdzić na stronie Limity w konsoli interfejsów API.
Uwaga: gdy osiągniesz limit, możesz poprosić o zwiększenie limitu, wypełniając formularz prośby o zwiększenie limitu dla usług YouTube API.
Obliczam wykorzystanie limitu
Google oblicza wykorzystanie limitu, przypisując koszt do każdego żądania. Różne typy operacji mają różne koszty limitów. Na przykład:
- Operacja odczytu, która pobiera listę zasobów – kanałów, filmów i playlist – zwykle kosztuje 1 jednostkę.
- Operacja zapisu, która tworzy, aktualizuje lub usuwa zasób, zwykle kosztuje
50
jednostek. - Żądanie wyszukiwania kosztuje tyle jednostek:
100
. - Przesłanie filmu kosztuje
1600
jednostek.
Tabela Koszty limitów żądań do interfejsu API zawiera koszt limitu dla każdej metody interfejsu API. Biorąc pod uwagę te reguły, możesz oszacować liczbę żądań, które Twoja aplikacja może wysłać dziennie bez przekraczania limitu.
Częściowe zasoby
Interfejs API umożliwia (a nawet wymaga) pobierania częściowych zasobów, dzięki czemu aplikacje unikają przesyłania, analizowania i przechowywania niepotrzebnych danych. Takie podejście zapewnia też, że interfejs API efektywniej korzysta z zasobów sieci, CPU i pamięci.
Interfejs API obsługuje 2 parametry żądania. Zostały one omówione w kolejnych sekcjach. Pozwalają one identyfikować właściwości zasobów, które powinny być uwzględnione w odpowiedziach interfejsu API.
- Parametr
part
identyfikuje grupy właściwości, które powinny zostać zwrócone dla zasobu. - Parametr
fields
filtruje odpowiedź interfejsu API, aby zwracała tylko określone właściwości w żądanych częściach zasobów.
Jak używać parametru part
Parametr part
jest parametrem wymaganym w przypadku każdego żądania do interfejsu API, które pobiera lub zwraca zasób. Parametr określa co najmniej jedną (niezagnieżdżoną) właściwość zasobu najwyższego poziomu, która powinna zostać uwzględniona w odpowiedzi interfejsu API. Na przykład zasób video
składa się z tych części:
snippet
contentDetails
fileDetails
player
processingDetails
recordingDetails
statistics
status
suggestions
topicDetails
Wszystkie te części są obiektami zawierającymi właściwości zagnieżdżone. Można je sobie wyobrazić jako grupy pól metadanych, które serwer API może (lub nie) pobrać. W związku z tym parametr part
wymaga wyboru komponentów zasobów, których aplikacja faktycznie używa. Ten wymóg ma 2 główne cele:
- Pozwala to skrócić czas oczekiwania, ponieważ serwer interfejsu API nie potrzebuje czasu na pobieranie pól metadanych, które nie są używane przez aplikację.
- Ogranicza to obciążenie łącza, zmniejszając (lub eliminując) ilość niepotrzebnych danych, które aplikacja może pobierać.
W miarę dodawania kolejnych elementów w zasobach korzyści będą się zwiększać, ponieważ Twoja aplikacja nie będzie żądać nowo wprowadzonych usług, których nie obsługuje.
Jak używać parametru fields
Parametr fields
filtruje odpowiedź interfejsu API, która zawiera tylko części zasobów określone w wartości parametru part
. Dzięki temu odpowiedź zawiera tylko określony zbiór pól. Parametr fields
umożliwia usuwanie właściwości zagnieżdżonych z odpowiedzi interfejsu API, co pozwala jeszcze bardziej ograniczyć wykorzystanie przepustowości. (Parametru part
nie można używać do filtrowania właściwości zagnieżdżonych na podstawie odpowiedzi).
W tych regułach wyjaśniamy obsługiwaną składnię wartości parametru fields
, która opiera się luźno na składni XPath:
- Aby wybrać wiele pól, użyj listy oddzielonej przecinkami (
fields=a,b
). - Aby zidentyfikować wszystkie pola, użyj gwiazdki (
fields=*
) jako symbolu wieloznacznego. - Aby określić grupę zagnieżdżonych właściwości, które zostaną uwzględnione w odpowiedzi interfejsu API, użyj nawiasów (
fields=a(b,c)
). - Aby wskazać właściwość zagnieżdżoną, użyj ukośnika (
fields=a/b
).
W praktyce reguły te często pozwalają na pobieranie tej samej odpowiedzi interfejsu API za pomocą kilku różnych wartości parametru fields
. Jeśli na przykład chcesz pobrać identyfikator, tytuł i pozycję każdego elementu na playliście, 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. Aby zwiększyć czytelność, w przykładach w tym dokumencie kodowanie zostało pominięte.
Przykładowe częściowe żądania
Poniższe przykłady pokazują, jak korzystać z parametrów part
i fields
, by mieć pewność, że odpowiedzi interfejsu API zawierają tylko dane używane przez aplikację:
- W przykładzie 1 zwracany jest zasób wideo zawierający 4 części oraz właściwości
kind
ietag
. - W przykładzie 2 zwracany jest zasób wideo zawierający 2 części oraz właściwości
kind
ietag
. - Przykład 3 zwraca zasób wideo, który zawiera 2 części, ale wyklucza właściwości
kind
ietag
. - Przykład 4 zwraca zasób wideo, który zawiera 2 części, ale wyklucza właściwości
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" } } ] }
Optymalizowanie skuteczności
Korzystanie z znaczników ETag
ETags, standardowa część protokołu HTTP, pozwala aplikacjom na odwoływanie się do konkretnej wersji konkretnego zasobu interfejsu API. Zasobem może być cały plik danych lub element w tym pliku danych. Ta funkcja jest przydatna w następujących przypadkach:
-
Pamięć podręczna i pobieranie warunkowe – aplikacja może buforować zasoby interfejsu API i ich tagi ETag. Kiedy aplikacja ponownie zażąda zapisanego zasobu, zostanie określony identyfikator 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 się nie zmienił, interfejs API zwraca odpowiedź HTTP 304 (
Not Modified
), co oznacza, że zasób się nie zmienił. Aplikacja może zmniejszyć czas oczekiwania i wykorzystanie przepustowości, udostępniając w ten sposób zasoby z pamięci podręcznej.Biblioteki klienta dla interfejsów API Google różnią się pod względem obsługi znaczników ETag. Na przykład biblioteka klienta JavaScriptu obsługuje tagi ETag za pomocą białej listy dozwolonych nagłówków żądań, które obejmują
If-Match
iIf-None-Match
. Biała lista umożliwia normalne buforowanie przeglądarki, więc jeśli ETag zasobu się nie zmienił, zasób może być udostępniany z pamięci podręcznej przeglądarki. Z kolei klient Obj-C nie obsługuje znaczników ETag. -
Ochrona przed niezamierzonym nadpisaniem zmian – tagi ETag pomagają zapewnić, że wiele klientów interfejsu API nie będzie przypadkiem nadpisywać sobie nawzajem zmian. Podczas aktualizowania lub usuwania zasobu aplikacja może określić jego ETag. Jeśli ETag nie pasuje do najnowszej wersji tego zasobu, żądanie do interfejsu API się nie powiedzie.
Używanie znaczników ETag w aplikacji przynosi kilka korzyści:
- Interfejs API odpowiada szybciej na żądania dotyczące niezmienionych zasobów w pamięci podręcznej, dzięki czemu czas oczekiwania i przepustowość są mniejsze.
- Twoja aplikacja nie zastąpi przypadkiem zmian w zasobie wprowadzonych za pomocą innego klienta interfejsu API.
Google APIs Client Library for JavaScript obsługuje nagłówki żądań HTTP If-Match
i If-None-Match
, dzięki czemu tagi ETag działają w kontekście normalnego zapisywania w pamięci podręcznej przeglądarki.
Korzystanie z gzip
Możesz też zmniejszyć przepustowość potrzebną dla każdej odpowiedzi interfejsu API, włączając kompresję gzip. Dekompresja odpowiedzi interfejsu API wymaga od aplikacji więcej czasu procesora, ale korzyści płynące z ograniczenia zużycia zasobów sieciowych przeważają ten koszt.
Aby otrzymać odpowiedź zakodowaną w formacie gzip, musisz wykonać 2 czynności:
- Ustaw nagłówek żądania HTTP
Accept-Encoding
nagzip
. - Zmodyfikuj klienta użytkownika, aby zawierał ciąg
gzip
.
W przykładowych nagłówkach HTTP poniżej pokazano, jakie wymagania należy spełnić, aby włączyć kompresję gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)