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.

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.

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.

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.

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

Optymalizacja skuteczności

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