Omówienie interfejsu YouTube Data API

Wprowadzenie

Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje współpracujące z YouTube. Wyjaśnia podstawowe koncepcje dotyczące YouTube i samego interfejsu API. Zawiera też omówienie różnych funkcji obsługiwanych przez 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 logowania, aby Twoja aplikacja mogła przesyłać żądania do interfejsu API.

  3. Po utworzeniu projektu sprawdź, czy interfejs YouTube Data API jest jedną z usług, do których używania zarejestrowana jest Twoja aplikacja:

    1. Otwórz Konsolę interfejsów API i wybierz projekt, który został zarejestrowany.
    2. Otwórz stronę włączonych interfejsów API. Na liście interfejsów API sprawdź, czy stan YouTube Data API v3 to WŁĄCZONY.

  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 popularny, niezależny od języka format danych, który zapewnia prostą tekstową reprezentację dowolnych struktur danych. Więcej informacji znajdziesz na stronie json.org.

Zasoby i typy zasobów

Zasób to pojedynczy obiekt danych z unikalnym identyfikatorem. W tabeli poniżej znajdziesz opis różnych typów zasobów, z którymi możesz wchodzić w interakcje 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, które są zgłaszane w strumieniach aktywności, to m.in. ocena filmu, udostępnienie filmu, oznaczenie filmu jako ulubionego i opublikowanie biuletynu kanału.
channel Zawiera informacje o pojedynczym kanale w YouTube.
channelBanner Określa adres URL, który ma być używany do ustawienia nowo przesłanego obrazu jako banera kanału.
channelSection Zawiera informacje o zestawie filmów, które kanał wybrał do wyróżnienia. Na przykład sekcja może zawierać najnowsze filmy, najpopularniejsze filmy lub filmy z co najmniej 1 playlisty.
guideCategory Określa kategorię, z którą YouTube kojarzy kanały na podstawie ich treści lub innych wskaźników, takich jak popularność. Kategorie w przewodniku mają na celu uporządkowanie kanałów w taki sposób, aby użytkownicy YouTube mogli łatwiej znaleźć interesujące ich treści. Kanały mogą być powiązane z co najmniej 1 kategorią przewodnika, ale nie ma gwarancji, że będą w jakiejkolwiek kategorii przewodnika.
i18nLanguage Określa język aplikacji obsługiwany przez witrynę YouTube. Język aplikacji jest też nazywany językiem interfejsu.
i18nRegion Określa obszar geograficzny, który użytkownik YouTube może wybrać jako preferowany region treści. Region treści może być też określany jako lokalizacja treści.
playlist Reprezentuje pojedynczą playlistę w YouTube. Playlista to zbiór filmów, które można oglądać po kolei i udostępniać innym użytkownikom.
playlistItem Określa zasób, taki jak film, który jest częścią playlisty. Zasób playlistItem zawiera też szczegóły wyjaśniające, jak dany zasób jest wykorzystywany 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 na unikalny zasób, 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 pojawią się nowe filmy lub gdy inny użytkownik wykona w YouTube jedno z kilku działań, np. prześle film, oceni go lub skomentuje.
thumbnail Określa miniatury powiązane z zasobem.
video Reprezentuje pojedynczy film w YouTube.
videoCategory Określa kategorię, która została lub może zostać powiązana z przesłanymi filmami.
watermark Określa 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 link z obrazu, oraz szczegóły dotyczące czasu, które określają, kiedy znak wodny pojawia się podczas odtwarzania filmów i jak długo 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 playlistItemzasobusnippet.resourceId.videoId identyfikuje zasób wideo, który z kolei zawiera pełne informacje o filmie. Na przykład wynik wyszukiwania zawiera właściwość videoId, playlistId lub channelId, która identyfikuje konkretny film, playlistę lub zasób kanału.

Obsługiwane operacje

Poniższa tabela zawiera najczęstsze metody obsługiwane przez interfejs API. Niektóre zasoby obsługują też 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 miniaturę filmu do YouTube i wiąże ją z filmem.

Operacje
list Pobiera (GET) listę zawierającą zero lub więcej zasobów.
insert Tworzy (POST) nowy zasób.
update Modyfikuje (PUT) istniejący zasób, aby odzwierciedlał dane w Twoim żądaniu.
delete Usuwa (DELETE) konkretny zasób.

API obsługuje obecnie metody wyświetlania każdego z obsługiwanych typów zasobów, a także operacje zapisu w przypadku wielu zasobów.

W tabeli poniżej znajdziesz informacje o operacjach obsługiwanych w przypadku różnych typów zasobów. Operacje wstawiania, aktualizowania lub usuwania zasobów zawsze wymagają autoryzacji użytkownika. W niektórych przypadkach list metody obsługują zarówno autoryzowane, jak i nieautoryzowane żądania. Nieautoryzowane żądania pobierają tylko dane publiczne, a autoryzowane żądania mogą też pobierać informacje o obecnie uwierzytelnionym użytkowniku lub jego dane 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 korzysta z limitu, aby mieć pewność, że deweloperzy używają usługi zgodnie z przeznaczeniem i nie tworzą aplikacji, które niesprawiedliwie obniżają jakość usługi lub ograniczają dostęp do niej innym użytkownikom. Wszystkie żądania do interfejsu API, w tym nieprawidłowe, wiążą się z kosztem limitu wynoszącym co najmniej 1 punkt. Limit dostępny dla Twojej aplikacji znajdziesz w API Console.

Projekty,w których włączony jest interfejs YouTube Data API, mają domyślną pulę 10 000 jednostek dziennie. Jest to ilość wystarczająca dla zdecydowanej większości użytkowników naszego interfejsu API. Domyślny limit, który może ulec zmianie, pomaga nam optymalizować przydzielanie limitów i skalować infrastrukturę w sposób bardziej przydatny dla użytkowników interfejsu API. Wykorzystanie limitu możesz sprawdzić na stronie Limity w Konsoli interfejsów API.

Uwaga: jeśli osiągniesz limit, możesz poprosić o dodatkowy limit, wypełniając formularz prośby o zwiększenie limitu w przypadku usług interfejsu API YouTube.

Obliczanie wykorzystania limitu

Google oblicza wykorzystanie limitu, przypisując koszt do każdego żądania. Różne typy operacji mają różne koszty limitu. Na 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.
  • Żądanie wyszukiwania kosztuje 100 jednostek.
  • Przesłanie filmu kosztuje 100 jednostek.

Tabela Kosz limitu dla żądań do interfejsu API zawiera koszt limitu każdej metody interfejsu API. Pamiętając o tych zasadach, możesz oszacować liczbę żądań, które Twoja aplikacja może wysyłać dziennie bez przekraczania przydziału.

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. Dzięki temu interfejs API wydajniej wykorzystuje zasoby sieciowe, CPU i pamięć.

Interfejs API obsługuje 2 parametry żądania, które opisujemy w kolejnych sekcjach. Umożliwiają one określenie właściwości zasobu, które mają być uwzględniane w odpowiedziach interfejsu API.

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

Jak używać parametru part

Parametr part jest wymagany w przypadku każdego żądania interfejsu API, które pobiera lub zwraca zasób. Parametr identyfikuje co najmniej 1 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 zagnieżdżone właściwości. Możesz traktować je jako grupy pól metadanych, które serwer API może (lub nie) pobrać. Dlatego parametr part wymaga wybrania komponentów zasobów, których aplikacja faktycznie używa. To wymaganie służy 2 głównym celom:

  • Zmniejsza to opóźnienie, ponieważ serwer interfejsu API nie musi pobierać pól metadanych, których aplikacja nie używa.
  • Zmniejsza zużycie przepustowości, ograniczając (lub eliminując) ilość niepotrzebnych danych, które może pobierać aplikacja.

Z czasem, gdy zasoby będą zawierać więcej części, korzyści te będą się zwiększać, ponieważ aplikacja nie będzie wysyłać żądań dotyczących nowo wprowadzonych 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 zasobu zidentyfikowane w wartości parametru part, dzięki czemu odpowiedź zawiera tylko określony zestaw pól. Parametr fields umożliwia usuwanie zagnieżdżonych właściwości z odpowiedzi interfejsu API, co pozwala dodatkowo zmniejszyć wykorzystanie przepustowości. (Parametru part nie można używać do filtrowania zagnieżdżonych usług w odpowiedzi).

Poniższe reguły wyjaśniają obsługiwaną składnię wartości parametru fields, która jest oparta na składni XPath:

  • Aby wybrać wiele pól, użyj listy rozdzielonej przecinkami (fields=a,b).
  • Użyj gwiazdki (fields=*) jako symbolu wieloznacznego, aby zidentyfikować wszystkie pola.
  • Używaj nawiasów (fields=a(b,c)), aby określić grupę zagnieżdżonych właściwości, które mają być uwzględnione w odpowiedzi interfejsu API.
  • Aby określić zagnieżdżoną właściwość, użyj ukośnika (fields=a/b).

W praktyce te reguły często umożliwiają pobranie tej samej odpowiedzi z 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. W przykładach w tym dokumencie kodowanie zostało pominięte, aby ułatwić ich czytanie.

Przykładowe żądania częściowe

Poniższe przykłady pokazują, jak używać parametrów part i fields, aby mieć pewność, że odpowiedzi interfejsu API zawierają tylko dane używane przez Twoją aplikację:

  1. Przykład 1 zwraca zasób wideo, który zawiera 4 części, a także 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 nie zawiera właściwości kind i etag.
  4. Przykład 4 zwraca zasób wideo, który zawiera 2 części, ale nie obejmuje kind i etag, a także niektórych zagnieżdżonych właściwości 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, które są standardową częścią protokołu HTTP, umożliwiają aplikacjom odwoływanie się do konkretnej wersji określonego zasobu interfejsu API. Zasobem może być cały plik danych lub element w tym pliku. Ta funkcja obsługuje te przypadki użycia:

  • Buforowanie i pobieranie warunkowe – aplikacja może buforować zasoby interfejsu API i ich tagi ETag. Gdy aplikacja ponownie zażąda zapisanego zasobu, określi tag ETag powiązany z tym zasobem. Jeśli zasób został zmieniony, interfejs API zwraca zmodyfikowany zasób i znacznik ETag powiązany z tą wersją zasobu. Jeśli zasób nie uległ zmianie, interfejs API zwraca odpowiedź HTTP 304 (Not Modified), która wskazuje, że zasób nie uległ zmianie. Dzięki temu aplikacja może zmniejszyć opóźnienia i obciążenie przepustowości, wyświetlając zasoby z pamięci podręcznej.

    Biblioteki klienta interfejsów API Google różnią się pod względem obsługi tagów ETag. Na przykład biblioteka klienta JavaScript obsługuje tagi ETag za pomocą białej listy dozwolonych nagłówków żądań, która zawiera If-Match i If-None-Match. Biała lista umożliwia normalne buforowanie w przeglądarce, dzięki czemu, jeśli tag ETag zasobu nie uległ zmianie, można go wyświetlić z pamięci podręcznej przeglądarki. Klient Obj-C nie obsługuje tagów ETag.

  • Ochrona przed przypadkowym zastąpieniem zmian – tagi ETag pomagają zapobiegać przypadkowemu zastępowaniu zmian wprowadzonych przez różne klienty API. Podczas aktualizowania lub usuwania zasobu aplikacja może określić jego tag ETag. Jeśli ETag nie pasuje do najnowszej wersji zasobu, żądanie interfejsu API się nie powiedzie.

Używanie tagów ETag w aplikacji przynosi kilka korzyści:

  • Interfejs API szybciej odpowiada na żądania dotyczące zasobów w pamięci podręcznej, które nie uległy zmianie, co zmniejsza opóźnienia i zużycie przepustowości.
  • Aplikacja nie nadpisze przypadkowo zmian w zasobie, które zostały wprowadzone przez 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 buforowania w przeglądarce.

Korzystanie z gzip

Możesz też zmniejszyć przepustowość potrzebną do obsługi każdej odpowiedzi interfejsu API, włączając kompresję gzip. Dekompresja odpowiedzi interfejsu API wymaga dodatkowego czasu pracy procesora, jednak korzyść w postaci mniejszego zużycia zasobów sieciowych zwykle przeważa nad tym kosztem.

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ł ciąg znaków gzip.

Poniższe przykładowe nagłówki HTTP pokazują, jak włączyć kompresję gzip:

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