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.

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.

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.

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.

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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

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