Przykładowe żądania do interfejsu API

Ta strona zawiera przykładowe żądania wysyłane do YouTube Data API. Za pomocą interfejsu YouTube Data API możesz pobierać zasoby w YouTube, takie jak filmy, kanały i playlisty, oraz nimi zarządzać. Każdy przykładowy link łączy się z interfejsem Google APIs Explorer i wypełnia go, aby umożliwić Ci wykonanie przykładowego kodu i wyświetlenie odpowiedzi.

Informacje o przesyłaniu treści za pomocą interfejsu YouTube Data API znajdziesz w artykule Przesyłanie wznowione.

Omówienie

Aby łatwiej było je zrozumieć, przykłady na tej stronie pokazują charakterystyczne elementy każdego żądania i skrócony podstawowy adres URL hosta, który przetwarza żądania do interfejsu Data API (https://www.googleapis.com/youtube/v3). Aby przesłać żądanie poza kontekstem przykładów, musisz podać pełny adres URL.

Oto przykładowe żądanie widoczne 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ń pobrania danych, takich jak lista subskrybentów, pozwala uzyskać dostęp tylko do właściciela kanału YouTube. Te żądania wymagają, aby właściciel kanału udzielił Eksploratorowi interfejsów API Google prawa do wykonywania żądań dotyczących interfejsu YouTube Data API w jego imieniu. Szczegółowe informacje o autoryzowaniu dostępu do danych kanału prywatnego znajdziesz w artykule Wdrażanie uwierzytelniania OAuth 2.0. Po połączeniu z eksploratorem interfejsów API kliknij przycisk Autoryzuj żądania za pomocą protokołu OAuth 2.0. Ten etap upoważnia Eksploratora interfejsów API do wysyłania żądań w imieniu właściciela. Wybierasz również zakres autoryzacji, który określa typy żądań, jakie może wykonywać eksplorator API.

Odpowiedź na każde żądanie to reprezentacja zasobu YouTube w formacie JSON. Parametr part w żądaniu określa, które części zasobu są uwzględnione w odpowiedzi. Ten parametr określa co najmniej 1 właściwości najwyższego poziomu (niezagnieżdżone), które powinny być uwzględnione w odpowiedzi. Oto niektóre z zasobów wideo:

  • krótki opis | fragment
  • Szczegóły treści
  • zawodnik
  • statystyka
  • stan

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 używanych przez aplikację.Więcej informacji znajdziesz w artykule Pierwsze kroki z YouTube Data API.

Pobieranie informacji o kanale

Ta prośba wykorzystuje metodę channels.list do pobierania informacji o kanałach 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 kanału uwierzytelnionego użytkownika. contentDetails zawiera kilka playlist wygenerowanych przez system powiązanych z kanałem. Wiele z nich wymaga teraz identyfikatora kanału lub playlisty, dlatego ich rejestracja jest bardzo ważna.

{
  "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 playlisty wygenerowane przez system

YouTube dodaje wszystkie przesłane filmy do playlisty powiązanej z kanałem. Aby wyświetlić listę przesłanych filmów, możesz utworzyć zapytanie dotyczące playlisty „Przesłane” zwróconej w odpowiedzi na powyższe informacje o kanale, korzystając z metody playlistItems.list do pobrania filmów z tej playlisty.

Przed wykonaniem tego przykładowego żądania w eksploratorze interfejsów API Google 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 produktu to jego identyfikator playlistyItemItem. Identyfikatorem elementu wideo na playliście jest videoId w części contentDetails.

Korzystając z powyższej prośby, możesz pobrać odpowiedni identyfikator playlisty z informacji o kanale, aby pobierać ulubione, polubienia, historię oglądania i listy Do obejrzenia.

Playlisty utworzone przez użytkowników

To żądanie używa metody playlists.list do pobierania playlist powiązanych z uwierzytelnionym kanałem. Pamiętaj, że to żądanie nie pobiera playlist systemowych wygenerowanych w ramach informacji o kanale (przesłanych filmów, historii oglądania itp.). Pobiera tylko playlisty utworzone przez użytkowników.

GET {base_URL}/playlists?part=snippet
                        &mine=true

Gdy masz już identyfikator playlisty, możesz pobrać z niej elementy, korzystając z żądania pokazanego w poprzedniej sekcji.

Możesz poprosić o informacje o publicznych playlistach kanału bez uwierzytelniania. Przesyłając nieuwierzytelnione żądanie, musisz dołączyć argument key określający unikalny klucz interfejsu API dla aplikacji. Na przykład żądanie to pobiera playlisty z kanału GoogleDevelopers.

GET {base_URL}/playlists?part=snippet
                        &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw
                        &key={YOUR_API_KEY}

Pobierz subskrypcje

Zasób subscription określa relację między użytkownikiem YouTube (subskrybentem) a kanałem. Metoda subscriptions.list pobiera subskrybentów do konkretnego kanału lub subskrypcji konkretnego użytkownika w zależności od parametrów uwzględnionych w żądaniu.

Subskrypcje kanału

Pobiera ona listę subskrybentów kanału uwierzytelnionego.

GET {base_URL}/subscriptions?part=snippet
                            &mySubscribers=true

Subskrypcje użytkownika

W przypadku kanałów subskrybowanych przez użytkownika można użyć tej samej metody, która zawiera listę subskrybentów (subscriptions.list). W tym żądaniu parametr mine służy do pobierania listy kanałów w YouTube, które uwierzytelnił użytkownik.

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

Pobieranie aktywności użytkowników

Zasób activity zawiera informacje o czynnościach wykonanych przez użytkownika lub kanał w YouTube, takich jak przesłanie filmu, zasubskrybowanie kanału itp. Metoda activities.list pobiera działania powiązane z kanałem lub użytkownikiem, które spełniają kryteria żądania. Możesz na przykład pobierać działania związane z konkretnym kanałem, subskrypcjami użytkownika lub jego niestandardową stroną główną w YouTube.

Aktywność w danym okresie

To żądanie pobiera wszystkie działania wykonane przez uwierzytelnionego użytkownika 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

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 wyświetlania, dane o popularności oraz informacje demograficzne dotyczące filmów i kanałów w YouTube, skorzystaj z interfejsu YouTube Analytics API. Na stronie Przykładowe żądania do interfejsu API znajdziesz informacje o pobieraniu typowych raportów z YouTube Analytics.

Metoda search.list pozwala wyszukiwać filmy, kanały lub playlisty w YouTube, które spełniają określone kryteria. Możesz wyszukiwać na podstawie właściwości filmu, słów kluczowych lub tematów (albo ich kombinacji) oraz sortować wyniki na podstawie takich czynników jak data utworzenia, liczba wyświetleń lub ocena.

Tak jak w przypadku innych żądań do interfejsu YouTube Data API, metoda search.list zwraca kod JSON zasobu YouTube. W przeciwieństwie do innych zasobów YouTube wynik wyszukiwania nie jest więc trwałym obiektem z unikalnym identyfikatorem.

Wiele żądań wyszukiwania obejmuje treści dostępne publicznie, dlatego nie wymagają uwierzytelniania. Spośród poniższych przykładów tylko pierwsze z nich wymaga uwierzytelnienia, ponieważ dotyczy konkretnie „moich” filmów. Przesyłając żądanie nieuwierzytelnionego żądania, musisz uwzględnić argument key określający unikalny klucz interfejsu API dla 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 HD

To żądanie szuka filmów o określonych właściwościach, czyli filmów w wysokiej rozdzielczości, które można umieścić w innych witrynach. Wyniki są wyświetlane w porządku malejącym.

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 wyszukuje słowa kluczowe w filmach dotyczących interfejsu 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 tematyczne

Bardziej zaawansowanym sposobem wyszukiwania filmów na dany temat jest użycie tematów Freebase zamiast słów kluczowych. Wszystkie zasoby na kanale i w filmach w YouTube zawierają obiekt topicDetails zawierający listę identyfikatorów tematów Freebase powiązanych z danym zasobem. Wyszukiwanie tematyczne jest bardziej inteligentne niż wyszukiwanie słów kluczowych, ponieważ temat Freebase reprezentuje wszystkie aspekty koncepcji lub przedmiotu, który istnieje w świecie rzeczywistym.

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 dla Pythona, którego identyfikator tematu 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 „piłka nożna”.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

Jeśli wolisz znaleźć kanały piłkarskie, zmień parametr type.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=channel
                     &key={YOUR_API_KEY}

Jeśli szukasz wszystkich treści związanych z piłką nożną (kanałów, playlist i filmów), możesz użyć wyszukiwania uniwersalnego. Jeśli pominiesz parametr type, żądanie pobierze treść każdego typu.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &key={YOUR_API_KEY}

Tworzenie i aktualizowanie zasobów

Żądania, które jak dotąd sprawdzaliśmy, korzystają z metody HTTP GET do pobierania danych z YouTube. Interfejs YouTube Data API udostępnia również metody wykorzystujące żądanie HTTP POST do tworzenia oraz aktualizowania zasobów YouTube, takich jak filmy, playlisty czy kanały. Poniżej znajdziesz przykłady żądań.

Metody POST obejmują Request body, który jest reprezentacją tworzonego lub aktualizowanego zasobu w formacie JSON. W narzędziu Google APIs Explorer możesz tworzyć reprezentacje JSON za pomocą interaktywnego narzędzia.

Tworzenie subskrypcji

Spowoduje to zarejestrowanie uwierzytelnionego użytkownika w 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'     }   } }

Tworzenie playlisty

Ta prośba 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

Skoro już utworzyliśmy playlistę, dodajmy do niej film. To żądanie dodaje film na początku playlisty ('position': 0).

POST {base_URL}/playlistItems?part=snippet
  Request body:
  {
    'snippet': {
      'playlistId': '{PLAYLIST_ID}', 
      'resourceId': {
          'kind': 'youtube#video',
          'videoId': '{VIDEO_ID}'
        }
     'position': 0
      }
   }