Omówienie interfejsu YouTube Data API

Wprowadzenie

Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje wchodzące w interakcje z YouTube. Wyjaśnia podstawowe pojęcia związane z YouTube i samym interfejsem API. Zawiera też omówienie różnych funkcji obsługiwanych przez interfejs API.

Zanim rozpoczniesz

1. Aby uzyskać dostęp do konsoli Google Cloud, poprosić o klucz interfejsu API i zarejestrować aplikację, musisz mieć konto Google.

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

3. Po utworzeniu projektu upewnij się, że YouTube Data API jest jedną z usług, do których zarejestrowana jest Twoja aplikacja:

   1. Otwórz konsolę Google Cloud i wybierz projekt, który został właśnie zarejestrowany.
   2. Otwórz stronę włączonych interfejsów API. Sprawdź, czy interfejs YouTube Data API znajduje się na liście włączonych interfejsów API. Jeśli nie, otwórz bibliotekę interfejsów API i włącz interfejs API.

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 zapewnia prostą tekstową reprezentację dowolnych struktur danych. Więcej informacji znajdziesz na stronie json.org.

Zasoby i typy zasobów

Zasób to pojedyncza jednostka danych z unikalnym identyfikatorem. W tabeli poniżej opisujemy różne typy zasobów, z którymi możesz wchodzić w interakcje 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 identyfikuje 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 identyfikuje konkretny zasób filmu, playlisty lub kanału.

Obsługiwane operacje

Poniższa tabela zawiera najpopularniejsze 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.

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

W tabeli poniżej znajdziesz operacje 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. Żądania nieautoryzowane pobierają tylko dane publiczne, natomiast żądania autoryzowane mogą też pobierać informacje o aktualnie uwierzytelnionym użytkowniku lub jego prywatne dane.

Wykorzystanie limitu

YouTube Data API korzysta z limitów, aby zapewnić, że deweloperzy używają usługi zgodnie z przeznaczeniem i nie tworzą aplikacji, które nieuczciwie obniżają jakość usługi lub ograniczają dostęp do niej innym użytkownikom. Wszystkie żądania do interfejsu API, w tym nieprawidłowe, kosztują co najmniej 1 punkt limitu. Limit dostępny dla aplikacji znajdziesz w API Console.

Projekty, które umożliwiają korzystanie z interfejsu YouTube Data API, mają domyślny limit 100 wywołań search.list,100 wywołań videos.insert i 10 tys. jednostek dziennie łącznie dla wszystkich pozostałych punktów końcowych. Domyślny limit, który może ulec zmianie, pomaga nam optymalizować przydzielanie limitów i skalować infrastrukturę w sposób, który jest 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 jego zwiększenie, wypełniając formularz prośby o zwiększenie limitu dla usług YouTube API.

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.
• Zapytanie kosztuje 1 jednostkę.
• Przesłanie filmu kosztuje 1 jednostkę.

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

Zasoby częściowe

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 zostały opisane w następnych sekcjach. Umożliwiają one identyfikowanie właściwości zasobów, które powinny 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 każdym żądaniu do 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 części:

• 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ć te obiekty jako grupy pól metadanych, które serwer interfejsu API może (lub nie) pobrać. Dlatego parametr part wymaga wybrania komponentów zasobów, których aplikacja faktycznie używa. To wymaganie ma 2 główne cele:

• Zmniejsza to czas oczekiwania, ponieważ serwer interfejsu API nie musi poświęcać czasu na pobieranie pól metadanych, których aplikacja nie używa.
• Zmniejsza wykorzystanie przepustowości, ograniczając (lub eliminując) ilość niepotrzebnych danych, które aplikacja może pobierać.

Z czasem, gdy do zasobów będą dodawane kolejne części, korzyści będą tylko rosły, ponieważ aplikacja nie będzie wysyłać żądań o nowo wprowadzone 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 określone 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 jeszcze bardziej zmniejszyć 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 oparta na składni XPath:

• Użyj listy oddzielonej przecinkami (fields=a,b), aby wybrać wiele pól.
• Użyj gwiazdki (fields=*) jako symbolu wieloznacznego, aby zidentyfikować wszystkie pola.
• 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 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 interfejsu API za pomocą kilku różnych wartości parametru fields. Jeśli na przykład chcesz pobrać identyfikator, tytuł i pozycję elementu playlisty dla 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 za pomocą parametrów part i fields możesz zadbać o to, aby odpowiedzi interfejsu API zawierały tylko dane używane przez Twoją aplikację:

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 filmu, 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 obejmuje właściwości kind i etag.
4. Przykład 4 zwraca zasób filmu, który zawiera 2 części, ale nie zawiera właściwości kind i etag ani niektórych właściwości zagnieżdżonych 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)