Omówienie interfejsu YouTube Data API

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

  1. Musisz mieć konto Google, aby uzyskać dostęp do konsoli interfejsu Google API, zażądać klucza API i zarejestrować swoją aplikację.

  2. Utwórz projekt w Google Developers Console i uzyskaj dane uwierzytelniające, aby Twoja aplikacja mogła przesyłać żądania do interfejsu API.

  3. Po utworzeniu projektu upewnij się, że YouTube Data API jest jedną z usług, w których rejestrujesz aplikację:

    1. Otwórz Konsolę interfejsów API i wybierz zarejestrowany przed chwilą projekt.
    2. Wejdź na stronę Włączone interfejsy API. Na liście interfejsów API sprawdź, czy YouTube Data API v3 ma stan WŁ.

  4. 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.

  5. Wybierz bibliotekę klienta, aby ułatwić sobie implementację interfejsu API.

  6. 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ę:

  1. Przykład 1 zwraca zasób wideo zawierający 4 części oraz właściwości kind i etag.
  2. Przykład 2 zwraca zasób wideo zawierający 2 części oraz właściwości kind i etag.
  3. W przykładzie 3 zwracany jest zasób wideo zawierający 2 części, ale z wyłączeniem właściwości kind i etag.
  4. Przykład 4 zwraca zasób wideo zawierający 2 części, ale z wyjątkiem kind i etag, a także niektóre właściwości zagnieżdżone w obiekcie snippet zasobu.
Przykład 1
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status
Description: This example retrieves a video 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" } } ] }
Przykład 2
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics
Description: This example modifies the part parameter value so that the contentDetails and status 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" } } ] }
Przykład 3
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 the fields parameter to remove all kind and etag 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" } } ] }
Przykład 4
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 the fields parameter from example 3 so that in the API response, each video resource's snippet object only includes the channelId, title, and categoryId 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 i If-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 na gzip.
  • 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)