Na tej stronie znajdziesz przykładowe żądania do interfejsu YouTube Data API. Za pomocą interfejsu YouTube Data API możesz pobierać zasoby YouTube, takie jak filmy, kanały i playlisty, oraz nimi zarządzać. Każdy przykład zawiera link do Google APIs Explorer i wypełnia go, dzięki czemu możesz uruchomić przykład i zobaczyć odpowiedź.
Informacje o przesyłaniu treści za pomocą interfejsu YouTube Data API znajdziesz w artykule Przesyłanie z możliwością wznowienia.
Przegląd
W celu uniknięcia wątpliwości, w przykładach na tej stronie pokazujemy charakterystyczne elementy każdego żądania i skracamy podstawowy adres URL hosta, który przetwarza żądania do interfejsu API danych (https://www.googleapis.com/youtube/v3). Aby wysłać żądanie poza kontekstem przykładów, musisz podać pełny adres URL.
Oto przykładowe żądanie, które pojawia się na tej stronie:
GET {base-URL}/channels?part=contentDetails &mine=true
Pełny adres URL tego żądania to:
GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails &mine=true
Kilka żądań pobiera dane, do których dostęp ma tylko właściciel kanału YouTube, np. listę subskrybentów. Te żądania wymagają, aby właściciel kanału przyznał Google APIs Explorer prawo do wykonywania żądań do interfejsu YouTube Data API w jego imieniu. (Szczegółowe informacje o autoryzowaniu dostępu do prywatnych danych kanału znajdziesz w artykule Implementowanie uwierzytelniania OAuth 2.0). Po połączeniu z APIs Explorer kliknij przycisk Authorize requests using OAuth 2.0 (Autoryzuj żądania za pomocą OAuth 2.0). Ten krok autoryzuje APIs Explorer do wysyłania żądań w imieniu właściciela. Wybierasz też zakres autoryzacji, który określa typy żądań, jakie może wykonywać APIs Explorer.
Odpowiedź na każde żądanie to reprezentacja zasobu YouTube w formacie JSON. Parametr part w żądaniu określa, które części zasobu mają być uwzględnione w odpowiedzi. Parametr identyfikuje co najmniej 1 właściwość zasobu najwyższego poziomu (niezagnieżdżoną), która powinna być uwzględniona w odpowiedzi. Oto niektóre części zasobu wideo:
- snippet
- contentDetails
- player
- statistics
- status
Wszystkie te części są obiektami zawierającymi zagnieżdżone właściwości. Możesz je traktować jako grupy pól metadanych, które serwer API może (ale nie musi) pobierać. Dlatego parametr part wymaga wybrania komponentów zasobu, których Twoja aplikacja faktycznie używa.Więcej informacji znajdziesz w artykule Pierwsze kroki z interfejsem YouTube Data API.
Pobieranie informacji o kanale
To żądanie używa metody channels.list do pobierania szczegółów kanałów należących do uwierzytelnionego użytkownika.
GET {base_URL}/channels?part=contentDetails &mine=true
Odpowiedź na to żądanie zawiera identyfikator kanału i contentDetails kanału uwierzytelnionego użytkownika. Element contentDetails zawiera kilka wygenerowanych przez system playlist powiązanych z kanałem. Wiele kolejnych żądań wymaga identyfikatora kanału lub jednego z identyfikatorów playlist, dlatego ważne jest, aby je zapisać.
{
"id": {CHANNEL_ID},
"kind": "youtube#channel",
"etag": etag,
"contentDetails": {
"relatedPlaylists": {
"likes": {LIKES_PLAYLIST_ID},
"favorites": {FAVORITES_PLAYLIST_ID},
"uploads": {UPLOADS_PLAYLIST_ID},
"watchHistory": {WATCHHISTORY_PLAYLIST_ID},
"watchLater": {WATCHLATER_PLAYLIST_ID}
},
"googlePlusUserId": string
},
}Przesłane filmy i wygenerowane przez system playlisty
YouTube dodaje wszystkie przesłane filmy do playlisty powiązanej z kanałem. Aby uzyskać listę przesłanych filmów, wyślij zapytanie do playlisty "uploads" zwróconej w odpowiedzi pokazanej powyżej w przypadku informacji o kanale. Użyj metody playlistItems.list, aby pobrać filmy z tej playlisty.
Zanim wykonasz to przykładowe żądanie w Google APIs Explorer, zastąp {UPLOADS_PLAYLIST_ID} identyfikatorem playlisty z poprzedniego żądania.
GET {base_URL}/playlistItems?part=contentDetails &playlistId={UPLOADS_PLAYLIST_ID}
Pamiętaj, że wartość "id" każdego zwróconego elementu to jego identyfikator playlistItem. Identyfikator filmu w przypadku elementu playlisty to videoId w części contentDetails.
Za pomocą powyższego żądania możesz pobrać ulubione, polubione, historię oglądania lub listę „Do obejrzenia” użytkownika, zastępując odpowiedni identyfikator playlisty z odpowiedzi na żądanie informacji o kanale.
Playlisty utworzone przez użytkownika
To żądanie używa metody playlists.list do pobierania playlist powiązanych z uwierzytelnionym kanałem. Pamiętaj, że to żądanie nie pobiera wygenerowanych przez system playlist uwzględnionych w informacjach o kanale (przesłane, historia oglądania itp.). Pobiera tylko playlisty utworzone przez użytkownika.
GET {base_URL}/playlists?part=snippet &mine=true
Gdy masz identyfikator playlisty, możesz pobrać elementy z playlisty za pomocą żądania pokazanego w poprzedniej sekcji.
Możesz poprosić o informacje o publicznych playlistach kanału bez uwierzytelniania. Gdy przesyłasz nieuwierzytelnione żądanie, musisz podać argument key, który określa unikalny klucz interfejsu API aplikacji wysyłającej żądanie. Na przykład to żądanie pobiera playlisty powiązane z kanałem GoogleDevelopers.
GET {base_URL}/playlists?part=snippet &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw &key={YOUR_API_KEY}
Pobieranie subskrypcji
Zasób subscription określa relację między użytkownikiem YouTube (subskrybentem) a kanałem. Metoda subscriptions.list pobiera subskrybentów konkretnego kanału lub subskrypcje konkretnego użytkownika w zależności od tego, które parametry uwzględnisz w żądaniu.
Subskrypcje kanału
To żądanie pobiera listę subskrybentów uwierzytelnionego kanału.
GET {base_URL}/subscriptions?part=snippet &mySubscribers=true
Subskrypcje użytkownika
Tej samej metody, która wyświetla listę subskrybentów (subscriptions.list), można użyć do wyświetlenia listy kanałów, które subskrybuje użytkownik. To żądanie używa parametru mine do pobierania listy kanałów YouTube, które subskrybuje uwierzytelniony użytkownik.
GET {base_URL}/subscriptions?part=snippet &mine=true
Pobieranie aktywności użytkownika
Zasób activity zawiera informacje o działaniu, które konkretny kanał lub użytkownik wykonał w YouTube – przesłanie filmu, subskrybowanie kanału itp. Metoda activities.list pobiera działania powiązane z kanałem lub użytkownikiem, które pasują do kryteriów żądania. Możesz na przykład pobrać działania powiązane z konkretnym kanałem, subskrypcjami użytkownika lub niestandardową stroną główną YouTube użytkownika.
Aktywność w danym okresie
To żądanie pobiera wszystkie działania, które uwierzytelniony użytkownik wykonał w kwietniu 2013 r.
GET {base_URL}/activities?part=snippet,contentDetails &mine=true &publishedAfter=2013-04-01T00%3A00%3A00Z &publishedBefore=2013-05-01T00%3A00%3A00Z
Aktywność na stronie głównej
To żądanie pobiera niestandardowy kanał aktywności, który wyświetla się na stronie głównej YouTube uwierzytelnionego użytkownika.
GET {base_URL}/activities?part=snippet,contentDetails &home=true
Aby pobrać statystyki oglądania, dane o popularności i dane demograficzne dotyczące filmów na YouTube i kanałów, użyj interfejsu YouTube Analytics API. Na stronie Przykładowe żądania do interfejsu API znajdziesz informacje o tym, jak pobierać typowe raporty ze Statystyk YouTube.
Szukaj
Metoda search.list umożliwia wyszukiwanie filmów na YouTube, kanałów lub playlist, które pasują do określonych kryteriów. Możesz wyszukiwać na podstawie właściwości filmu, słów kluczowych lub tematów (albo ich kombinacji) oraz sortować wyniki według takich czynników jak data utworzenia, liczba wyświetleń lub ocena.
Podobnie jak inne żądania do interfejsu YouTube Data API, metoda search.list zwraca reprezentację zasobu YouTube w formacie JSON. W przeciwieństwie jednak do innych zasobów YouTube wynik wyszukiwania nie jest trwałym obiektem z unikalnym identyfikatorem.
Wiele żądań wyszukuje treści dostępne publicznie i dlatego nie wymaga uwierzytelniania. Spośród przykładów poniżej tylko pierwszy wymaga uwierzytelnienia, ponieważ dotyczy konkretnie „moich” filmów. Gdy przesyłasz nieuwierzytelnione żądanie, musisz podać argument key, który określa unikalny klucz interfejsu API Twojej aplikacji.
Moje najczęściej oglądane filmy
To żądanie pobiera wszystkie filmy uwierzytelnionego użytkownika i wyświetla je w kolejności malejącej według liczby wyświetleń.
GET {base_URL}/search?part=snippet &forMine=true &order=viewCount &type=video
Filmy w wysokiej rozdzielczości, które można umieszczać na innych stronach
To żądanie wyszukuje filmy, które mają określone właściwości, czyli filmy w wysokiej rozdzielczości, które można umieszczać na innych stronach. Wyniki są wyświetlane w kolejności malejącej według oceny.
GET {base_URL}/search?part=snippet &order=rating &type=video &videoDefinition=high &videoEmbeddable=true &key={YOUR_API_KEY}
Filmy na określony temat
To żądanie wykonuje wyszukiwanie słów kluczowych w przypadku filmów o interfejsie YouTube Data API, które zawierają napisy.
GET {base_URL}/search?part=snippet &q=YouTube+Data+API &type=video &videoCaption=closedCaption &key={YOUR_API_KEY}
Wyszukiwanie na podstawie tematu
Bardziej zaawansowanym sposobem wyszukiwania filmów na określony temat jest używanie tematów Freebase zamiast słów kluczowych. Zasoby kanału i filmu w YouTube zawierają obiekt topicDetails, który zawiera listę identyfikatorów tematów Freebase powiązanych z zasobem. Wyszukiwanie na podstawie tematu jest bardziej inteligentne niż wyszukiwanie słów kluczowych, ponieważ temat Freebase reprezentuje wszystkie aspekty rzeczywistego pojęcia lub rzeczy.
Aby wyszukiwać za pomocą tematu Freebase, musisz najpierw pobrać identyfikator tematu za pomocą interfejsu Freebase API. To żądanie zwraca filmy powiązane z tematem Freebase dotyczącym języka Python, którego identyfikator to /m/05z1_.
GET {base_URL}/search?part=snippet &topicId=/m/05z1_ &type=video &key={YOUR_API_KEY}
Wyszukiwanie playlist lub kanałów
Wyszukiwanie nie ogranicza się do filmów. Możesz też wyszukiwać playlisty lub kanały. To żądanie pobiera playlisty pasujące do słowa kluczowego „soccer”.
GET {base_URL}/search?part=snippet &q=soccer &type=playlist &key={YOUR_API_KEY}
Jeśli wolisz znaleźć kanały o piłce nożnej, po prostu zmień parametr type.
GET {base_URL}/search?part=snippet &q=soccer &type=channel &key={YOUR_API_KEY}
Jeśli chcesz znaleźć wszystkie treści związane z piłką nożną (kanały, playlisty i filmy), możesz przeprowadzić wyszukiwanie uniwersalne. Jeśli pominiesz parametr type, żądanie pobierze treści wszystkich typów.
GET {base_URL}/search?part=snippet &q=soccer &key={YOUR_API_KEY}
Tworzenie i aktualizowanie zasobów
Wszystkie żądania, które dotychczas omawialiśmy, używają metody GET HTTP do pobierania danych z YouTube. Interfejs YouTube Data API oferuje też metody, które używają metody HTTP POST do tworzenia lub aktualizowania zasobów YouTube, takich jak filmy, playlisty czy kanały. Przykłady znajdziesz w tych żądaniach.
Metody POST zawierają Request body (Treść żądania), czyli reprezentację JSON tworzonego lub aktualizowanego zasobu. Reprezentacje JSON możesz tworzyć w Google APIs Explorer za pomocą interaktywnego narzędzia.
Tworzenie subskrypcji
To żądanie subskrybuje uwierzytelnionego użytkownika na kanale GoogleDevelopers. Innymi słowy, tworzy zasób subskrypcji.
POST {base_URL}/subscriptions?part=snippet
Request body: { 'snippet': { 'resourceId': { 'kind': 'youtube#channel', 'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' } } }
Utwórz playlistę
To żądanie tworzy nową publiczną playlistę.
POST {base_URL}/playlists?part=snippet
Request body: { 'snippet': { 'title': 'New playlist', 'description': 'Sample playlist for Data API', } }
Dodanie filmu do playlisty
Mamy już playlistę, więc dodajmy do niej film. To żądanie dodaje film na początek playlisty ('position': 0).
POST {base_URL}/playlistItems?part=snippet Request body: { 'snippet': { 'playlistId': '{PLAYLIST_ID}', 'resourceId': { 'kind': 'youtube#video', 'videoId': '{VIDEO_ID}' } 'position': 0 } }