Omówienie interfejsu YouTube Data API

Wprowadzenie

Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje współpracujące z YouTube. Wyjaśniamy w nim podstawowe pojęcia związane z YouTube i samym interfejsem API. Omówiono w nim też różne funkcje obsługiwane przez interfejs API.

Zanim zaczniesz

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 aplikacja mogła przesyłać żądania do interfejsu API.

3. Po utworzeniu projektu sprawdź, czy YouTube Data API należy do usług, w których Twoja aplikacja jest zarejestrowana:

   1. Otwórz Konsolę interfejsów API i wybierz zarejestrowany przed chwilą projekt.
   2. Wejdź na stronę Włączone interfejsy API. Sprawdź, czy na liście interfejsów API 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. zapoznać 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 w prosty sposób przedstawia dowolne struktury danych w formie tekstowej. Więcej informacji znajdziesz na stronie json.org.

Zasoby i typy zasobów

Zasób to pojedyncza jednostka danych o unikalnym identyfikatorze. Tabela poniżej zawiera opis różnych typów zasobów, z których można korzystać przy użyciu 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: wynik wyszukiwania zawiera właściwość videoId, playlistId lub channelId, która wskazuje zasób filmu, playlisty lub kanału.

Obsługiwane operacje

W tabeli poniżej znajdziesz najczęściej używane metody obsługiwane przez interfejs API. Niektóre zasoby obsługują również 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 do YouTube obraz miniatury filmu i wiąże go z filmem.

Obecnie ten interfejs API obsługuje metody wyświetlania listy wszystkich obsługiwanych typów zasobów, a także obsługuje operacje zapisu w przypadku wielu zasobów.

Poniższa tabela przedstawia operacje, które są obsługiwane w przypadku różnych typów zasobów. Operacje wstawiania, aktualizowania i usuwania zasobów zawsze wymagają autoryzacji użytkownika. W niektórych przypadkach metody list obsługują zarówno żądania autoryzowane, jak i nieautoryzowane. Nieuprawnione żądania pobierają tylko dane publiczne, natomiast autoryzowane żądania mogą pobrać informacje o obecnie uwierzytelnionym użytkowniku lub prywatne.

Wykorzystanie limitu

YouTube Data API wykorzystuje limit, aby mieć pewność, że deweloperzy będą korzystać z usługi zgodnie z oczekiwaniami i nie tworzą aplikacji, które nieuczciwie obniżają jakość usług lub ograniczają dostęp do nich innym użytkownikom. Wszystkie żądania do interfejsu API, w tym żądania nieprawidłowe, skutkują kosztem co najmniej jednego punktu. Limit dostępny dla Twojej aplikacji znajdziesz w API Console.

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

Uwaga: gdy osiągniesz limit, możesz poprosić o zwiększenie limitu, wypełniając formularz prośby o zwiększenie limitu dla usług YouTube API.

Obliczam wykorzystanie limitu

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

• Operacja odczytu, która pobiera listę zasobów – kanałów, filmów i playlist – zwykle kosztuje 1 jednostkę.
• Operacja zapisu, która tworzy, aktualizuje lub usuwa zasób, zwykle kosztuje 50 jednostek.
• Żądanie wyszukiwania kosztuje tyle jednostek: 100.
• Przesłanie filmu kosztuje 1600 jednostek.

Tabela Koszty limitów żądań do interfejsu API zawiera koszt limitu dla każdej metody interfejsu API. Biorąc pod uwagę te reguły, możesz oszacować liczbę żądań, które Twoja aplikacja może wysłać dziennie bez przekraczania limitu.

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. Takie podejście zapewnia też, że interfejs API efektywniej korzysta z zasobów sieci, CPU i pamięci.

Interfejs API obsługuje 2 parametry żądania. Zostały one omówione w kolejnych sekcjach. Pozwalają one identyfikować właściwości zasobów, które powinny być uwzględnione w odpowiedziach interfejsu API.

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

Jak używać parametru part

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

• 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 sobie wyobrazić jako grupy pól metadanych, które serwer API może (lub nie) pobrać. W związku z tym parametr part wymaga wyboru komponentów zasobów, których aplikacja faktycznie używa. Ten wymóg ma 2 główne cele:

• Pozwala to skrócić czas oczekiwania, ponieważ serwer interfejsu API nie potrzebuje czasu na pobieranie pól metadanych, które nie są używane przez aplikację.
• Ogranicza to obciążenie łącza, zmniejszając (lub eliminując) ilość niepotrzebnych danych, które aplikacja może pobierać.

W miarę dodawania kolejnych elementów w zasobach korzyści będą się zwiększać, ponieważ Twoja 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 zbiór pól. Parametr fields umożliwia usuwanie właściwości zagnieżdżonych z odpowiedzi interfejsu API, co pozwala jeszcze bardziej ograniczyć wykorzystanie przepustowości. (Parametru part nie można używać do filtrowania właściwości zagnieżdżonych na podstawie odpowiedzi).

W tych regułach wyjaśniamy obsługiwaną składnię wartości parametru fields, która opiera się luźno na składni XPath:

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

W praktyce reguły te często pozwalają na pobieranie tej samej odpowiedzi 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. Aby zwiększyć czytelność, w przykładach w tym dokumencie kodowanie zostało pominięte.

Przykładowe częściowe żądania

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

1. W przykładzie 1 zwracany jest zasób wideo zawierający 4 części oraz właściwości kind i etag.
2. W przykładzie 2 zwracany jest zasób wideo zawierający 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 właściwości 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)