Omówienie interfejsu YouTube Data API

Wprowadzenie

Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje umożliwiające interakcję z YouTube. Wyjaśnia podstawowe pojęcia dotyczące YouTube i samego interfejsu API. Znajdziesz tu też omówienie różnych funkcji obsługiwanych przez ten interfejs API.

Zanim rozpoczniesz

  1. Aby uzyskać dostęp do Konsoli interfejsów API Google, poprosić o klucz interfejsu API i zarejestrować aplikację, musisz mieć konto Google.

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

  3. Po utworzeniu projektu sprawdź, czy interfejs YouTube Data API jest jedną z usług, z których może korzystać Twoja aplikacja:

    1. Otwórz Konsolę interfejsów API i wybierz przed chwilą zarejestrowany projekt.
    2. Otwórz stronę Włączone interfejsy API. Na liście interfejsów API sprawdź, czy dla interfejsu YouTube Data API w wersji 3 stan to WŁĄCZONE.

  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 związanymi z formatem danych JSON (JavaScript Object Notation). JSON to popularny format danych niezależny od języka, który oferuje prostą tekstową prezentację dowolnych struktur danych. Więcej informacji znajdziesz na stronie json.org.

Zasoby i typy zasobów

Zasób to pojedynczy element 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 działaniu, które dany użytkownik wykonał w witrynie YouTube. Działania użytkowników raportowane w strumieniach aktywności obejmują m.in. ocenianie filmów, udostępnianie filmów, oznaczanie ich jako ulubionych i publikowanie biuletynów na kanale.
channel Zawiera informacje o jednym kanale YouTube.
channelBanner Określa adres URL, który ma służyć do ustawienia nowo przesłanego obrazu jako obrazu banera kanału.
channelSection Zawiera informacje o zbiorze filmów polecanych przez kanał. Na przykład sekcja może zawierać najnowsze filmy z kanału, najpopularniejsze materiały czy filmy z jednej lub kilku playlist.
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 pomagają uporządkować kanały w taki sposób, by użytkownicy YouTube mogli łatwiej znaleźć treści, których szukają. Kanały mogą być powiązane z jedną lub większą liczbą kategorii przewodników, ale nie gwarantujemy, że będą się one pojawiać w żadnej z nich.
i18nLanguage Określa język aplikacji obsługiwany przez witrynę 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 Identyfikuje zasób, np. film, który jest częścią playlisty. Zasób playlistItem zawiera też szczegółowe informacje o sposobie wykorzystywania zawartych w nim zasobów.
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. Choć wynik wyszukiwania wskazuje na zasób, który można jednoznacznie zidentyfikować, np. film, nie ma on trwałych danych.
subscription Zawiera informacje o subskrypcji użytkownika YouTube. Subskrypcja powiadamia użytkownika, gdy na jego kanale pojawią się nowe filmy lub gdy inny użytkownik wykona jedno z kilku działań w YouTube, takie jak przesłanie filmu, ocena 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ć skojarzona z przesłanymi filmami.
watermark Identyfikuje obraz wyświetlany podczas odtwarzania filmów z określonego kanału. Właściciel kanału może też określić kanał docelowy, do którego prowadzi obraz, a także określić czas wyświetlania znaku wodnego podczas odtwarzania filmu oraz czas jego widoczności.

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. Innym przykładem jest to, że wynik wyszukiwania zawiera właściwość videoId, playlistId lub channelId identyfikującą konkretny film, playlistę lub zasób kanału.

Obsługiwane operacje

W tabeli poniżej znajdziesz najpopularniejsze metody obsługiwane przez interfejs API. Niektóre zasoby obsługują również inne metody, które dają funkcje lepiej dostosowane do 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 Tworzy (POST) nowy zasób.
update Modyfikuje (PUT) istniejący zasób, aby odzwierciedlić dane z Twojego żądania.
delete Usuwa (DELETE) konkretny zasób.

Interfejs API obecnie obsługuje metody wyświetlania listy wszystkich obsługiwanych typów zasobów oraz obsługuje operacje zapisu dla wielu zasobów.

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 żądania autoryzowane, jak i nieautoryzowane. Nieautoryzowane żądania pobierają jedynie dane publiczne, podczas gdy autoryzowane żądania mogą również pobierać informacje dotyczące obecnie uwierzytelnionego użytkownika lub informacje 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 stosuje limit, aby mieć pewność, że deweloperzy korzystają z usługi zgodnie z przeznaczeniem i nie tworzą aplikacji, które w nieuczciwy sposób obniżają jakość usług lub ograniczają dostęp innym użytkownikom. Wszystkie żądania do interfejsu API, w tym żądania nieprawidłowe, wiążą się z co najmniej jednopunktowym limitem kosztu. Limit dostępny dla Twojej aplikacji znajdziesz w API Console.

Projekty, w których włączono interfejs YouTube Data API, mają domyślnie przypisany limit 10 tys. jednostek dziennie, co jest wystarczające dla zdecydowanej większości użytkowników naszych interfejsów API. Limit domyślny, który może ulec zmianie, pomaga nam optymalizować przydziały i skalować naszą infrastrukturę w sposób bardziej zrozumiały dla użytkowników interfejsów API. Wykorzystanie limitu możesz sprawdzić na stronie Limity w konsoli interfejsów API.

Uwaga: po osiągnięciu limitu możesz poprosić o zwiększenie limitu do ukończenie rozszerzenia limitu miejsca formularza dotyczącego usług YouTube API.

Obliczam wykorzystanie limitu

Google oblicza wykorzystanie limitu, przypisując koszt do każdego żądania. Różne typy mają różne koszty limitów. Na przykład:

  • Operacja odczytu pobierająca listę zasobów – kanałów, filmów, playlist – zwykle kosztuje 1 jednostkę.
  • Operacja zapisu, która tworzy, aktualizuje lub usuwa zasób, zwykle wiąże się z kosztami 50 szt.
  • Żądanie wyszukiwania kosztuje 100 jednostek.
  • Przesyłanie filmu kosztuje 1600 jednostek.

Tabela Koszty limitu żądań interfejsu API pokazuje dla każdej metody interfejsu API. Mając na uwadze te reguły, możesz oszacować liczbę żądań które aplikacja może wysyłać dziennie bez przekraczania limitu.

Zasoby częściowe

Interfejs API umożliwia i w rzeczywistości wymaga pobierania częściowych zasobów, tak aby aplikacje nie przesyłały, nie analizowały i nie przechowują niepotrzebnych danych. Takie podejście gwarantuje też, że interfejs API wydajniej wykorzystuje zasoby sieci, CPU i pamięci.

Interfejs API obsługuje 2 parametry żądań, które zostały objaśnione w kolejnych sekcjach. Umożliwiają one wskazanie właściwości zasobów, które powinny być uwzględnione w odpowiedziach interfejsu API.

  • Parametr part określa grupy właściwości, które powinny zostać zwrócone dla zasobu.
  • Parametr fields filtruje odpowiedź interfejsu API tak, aby zwracała tylko określone właściwości w obrębie żądanych części zasobów.

Jak używać parametru part

Parametr part jest wymagany w przypadku każdego żądania do interfejsu API, które pobiera lub zwraca zasób. Parametr identyfikuje co najmniej jedną właściwość zasobu najwyższego poziomu (niezagnieżdżoną), która powinna być uwzględniona w odpowiedzi interfejsu API. Na przykład zasób video składa się z tych elementów:

  • 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 traktować jako grupy pól metadanych, które serwer API może (lub nie) pobrać. W związku z tym parametr part wymaga wybrania komponentów zasobów, których rzeczywiście używa Twoja aplikacja. To wymaganie ma 2 główne cele:

  • Pozwala to zmniejszyć czas oczekiwania, ponieważ serwer API nie musi tracić czasu na pobieranie pól metadanych, których nie używa Twoja aplikacja.
  • Zmniejsza ono wykorzystanie przepustowości przez ograniczenie (lub eliminację) ilości niepotrzebnych danych, które może pobrać aplikacja.

Z czasem, w miarę jak zasoby będą dodawane do coraz większej liczby zasobów, korzyści te będą tylko zwiększać, ponieważ 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 zestaw pól. Parametr fields umożliwia usuwanie z odpowiedzi interfejsu API właściwości zagnieżdżonych, co jeszcze bardziej zmniejsza wykorzystanie przepustowości. Parametru part nie można używać do filtrowania właściwości zagnieżdżonych 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 rozdzielanej przecinkami (fields=a,b).
  • Użyj gwiazdki (fields=*) jako symbolu wieloznacznego do identyfikacji wszystkich pól.
  • Użyj nawiasów (fields=a(b,c)), aby określić grupę właściwości zagnieżdżonych, które zostaną uwzględnione w odpowiedzi interfejsu API.
  • Aby wskazać właściwość zagnieżdżoną, użyj ukośnika (fields=a/b).

W praktyce te reguły często pozwalają kilka różnych wartości parametrów fields na pobranie tej samej odpowiedzi interfejsu API. Jeśli na przykład chcesz pobrać identyfikator, tytuł i pozycję 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. Aby ułatwić czytanie, w przykładach w tym dokumencie pominięto kodowanie.

Przykładowe żądania częściowe

Poniższe przykłady pokazują, jak używać parametrów part i fields, aby odpowiedzi interfejsu API zawierały tylko te dane, których używa Twoja aplikacja:

  1. Przykład 1 zwraca zasób wideo, który zawiera 4 części oraz właściwości kind i etag.
  2. Przykład 2 zwraca zasób wideo, który zawiera 2 części oraz właściwości kind i etag.
  3. Przykład 3 zwraca zasób wideo, który zawiera 2 części, ale wyklucza właściwości kind i etag.
  4. Przykład 4 zwraca zasób wideo, który zawiera 2 części, ale wyklucza 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"
   }
  }
 ]
}

Optymalizowanie skuteczności

Korzystanie z ETagów

ETags, standardowa część protokołu HTTP, pozwala aplikacjom odwoływać się do konkretnej wersji określonego zasobu interfejsu API. Zasóbem może być cały plik danych lub element w tym pliku. Ta funkcja działa w tych przypadkach użycia:

  • Pamięć podręczna i pobieranie warunkowe – aplikacja może buforować zasoby interfejsu API i ich tagi ETag. Następnie, gdy aplikacja ponownie zażąda zapisanego zasobu, określa tag ETag powiązany z tym zasobem. Jeśli zasób się zmienił, interfejs API zwraca 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 nie uległ zmianie. Aplikacja może zmniejszyć czas oczekiwania i wykorzystanie przepustowości dzięki udostępnianiu zasobów z pamięci podręcznej w ten sposób.

    Biblioteki klienta interfejsów API Google różnią się pod względem obsługi znaczników ETag. Na przykład biblioteka klienta JavaScript obsługuje tagi ETag poprzez umieszczenie na białej liście dozwolonych nagłówków żądań obejmujących If-Match i If-None-Match. Biała lista umożliwia normalne buforowanie przeglądarki, dzięki czemu zasób może być wyświetlany z pamięci podręcznej przeglądarki, nawet jeśli jego tag ETag nie uległ zmianie. Klient Obj-C nie obsługuje natomiast tagów ETag.

  • Ochrona przed przypadkowym zastąpieniem zmian – tagi ETag pomagają zapobiegać przypadkowemu nadpisywaniu zmian przez wielu klientów interfejsu API. Podczas aktualizowania lub usuwania zasobu aplikacja może określić jego wartość ETag. Jeśli ETag nie jest zgodny z najnowszą wersją tego zasobu, żądanie do interfejsu API się nie powiedzie.

Stosowanie tagów ETag w aplikacji przynosi liczne korzyści:

  • Interfejs API szybciej reaguje na żądania dotyczące buforowanych, ale niezmienionych zasobów, co przekłada się na mniejsze opóźnienia i mniejsze wykorzystanie przepustowości.
  • Twoja aplikacja nie spowoduje przypadkowego zastąpienia zmian w zasobie wprowadzonych przez innego klienta interfejsu API.

Google APIs Client Library for JavaScript obsługuje nagłówki żądań HTTP If-Match i If-None-Match, co umożliwia działanie tagów ETag w kontekście normalnego buforowania przeglądarki.

Korzystanie z gzip

Możesz też zmniejszyć przepustowość wymaganą dla każdej odpowiedzi interfejsu API, włączając kompresję gzip. Aplikacja będzie potrzebować więcej czasu pracy procesora, aby zdekompresować odpowiedzi interfejsu API, jednak korzyści z używania mniejszej liczby zasobów sieciowych zwykle przewyższają ten koszt.

Aby otrzymać odpowiedź zakodowaną w formacie gzip, musisz wykonać 2 czynności:

  • Ustaw nagłówek żądania HTTP Accept-Encoding na gzip.
  • Zmodyfikuj klienta użytkownika, tak aby zawierał ciąg znaków gzip.

Poniższe przykładowe nagłówki HTTP ilustrują wymagania dotyczące włączenia kompresji gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)