Zwraca zbiór wyników wyszukiwania pasujących do parametrów zapytania określonych w żądaniu do interfejsu API. Domyślnie zestaw wyników wyszukiwania identyfikuje pasujące zasoby video
, channel
i playlist
, ale możesz skonfigurować zapytania pod kątem pobierania tylko określonego typu zasobów.
Wpływ na limit: wywołanie tej metody ma koszt limitu wynoszący 100 jednostek.
Typowe przypadki użycia
Prośba
Żądanie HTTP
GET https://www.googleapis.com/youtube/v3/search
Parametry
W tabeli poniżej znajdziesz parametry obsługiwane przez to zapytanie. Wszystkie wymienione parametry są parametrami zapytania.
Parametry | ||
---|---|---|
Parametry wymagane | ||
part |
string Parametr part określa rozdzieloną przecinkami listę właściwości zasobu search , która będzie zawarta w odpowiedzi interfejsu API. Ustaw wartość parametru na snippet .
|
|
Filtry (podaj 0 lub 1 z poniższych parametrów) | ||
forContentOwner |
boolean Ten parametr może być używany tylko w prawidłowo autoryzowanym żądaniu. Jest on przeznaczony wyłącznie dla dostawców treści w YouTube. Parametr forContentOwner ogranicza wyszukiwanie tylko do filmów należących do właściciela treści określonego przez parametr onBehalfOfContentOwner . Jeśli forContentOwner ma wartość Prawda, żądanie musi też spełniać te wymagania:
|
|
forDeveloper |
boolean Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Parametr forDeveloper ogranicza wyszukiwanie tylko do filmów przesłanych za pomocą aplikacji lub witryny dewelopera. Serwer API identyfikuje dewelopera na podstawie danych uwierzytelniających autoryzacji żądania. Parametr forDeveloper może być używany w połączeniu z opcjonalnymi parametrami wyszukiwania, np. q .W przypadku tej funkcji każdy przesłany film jest automatycznie oznaczany numerem projektu powiązanym z aplikacją dewelopera w Google Developers Console. Gdy żądanie wyszukiwania ustawi parametr forDeveloper na true , serwer API używa danych uwierzytelniających żądania do identyfikacji programisty. Dlatego deweloper może ograniczyć wyniki do filmów przesłanych za pomocą swojej aplikacji lub witryny, ale nie do filmów przesyłanych za pomocą innych aplikacji lub witryn. |
|
forMine |
boolean Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Parametr forMine ogranicza wyszukiwanie tylko do filmów należących do uwierzytelnionego użytkownika. Jeśli ustawisz ten parametr na true , wartość parametru type również musi być ustawiona na video . W jednym żądaniu nie można też ustawić żadnego z tych parametrów: videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoPaidProductPlacement , videoSyndicated oraz videoType . |
|
Parametry opcjonalne | ||
channelId |
string Parametr channelId wskazuje, że odpowiedź interfejsu API powinna zawierać tylko zasoby utworzone przez kanał. Uwaga: w wynikach wyszukiwania może pojawić się maksymalnie 500 filmów, jeśli w żądaniu określisz wartość parametru channelId i ustawisz wartość parametru type na video , ale nie zostanie ustawiony jeden z filtrów forContentOwner , forDeveloper lub forMine . |
|
channelType |
string Parametr channelType pozwala ograniczyć wyszukiwanie do konkretnego typu kanału.Akceptowane wartości:
|
|
eventType |
string Parametr eventType ogranicza wyszukiwanie do transmitowanych zdarzeń. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video .Akceptowane wartości:
|
|
location |
string Parametr location w połączeniu z parametrem locationRadius określa okrągły obszar geograficzny i ogranicza wyszukiwanie do filmów, które w metadanych określają lokalizację geograficzną znajdującą się na tym obszarze. Wartością parametru jest ciąg znaków określający współrzędne szerokości i długości geograficznej, np. (37.42307,-122.08427 ).
location , ale nie podaje wartości parametru locationRadius .Uwaga: jeśli określisz wartość tego parametru, musisz też ustawić wartość video parametru type .
| |
locationRadius |
string Parametr locationRadius w połączeniu z parametrem location określa okrągły obszar geograficzny.Wartość parametru musi być liczbą zmiennoprzecinkową, po której następuje jednostka miary. Prawidłowe jednostki miary to m , km , ft i mi . Prawidłowe wartości parametrów to np. 1500m , 5km , 10000ft i 0.75mi . Interfejs API nie obsługuje wartości parametrów locationRadius większych niż 1000 kilometrów.Uwaga: więcej informacji znajdziesz w definicji parametru location . |
|
maxResults |
unsigned integer Parametr maxResults określa maksymalną liczbę elementów, które powinny zostać zwrócone w zbiorze wyników. Akceptowane wartości to od 0 do 50 (włącznie). Wartością domyślną jest 5 . |
|
onBehalfOfContentOwner |
string Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Uwaga: ten parametr jest przeznaczony wyłącznie dla dostawców treści w YouTube. Parametr onBehalfOfContentOwner wskazuje, że dane uwierzytelniające żądanie identyfikują użytkownika YouTube CMS działającego w imieniu właściciela treści określonego w wartości parametru. Jest on przeznaczony dla dostawców treści w YouTube, którzy mają wiele różnych kanałów w YouTube i nimi zarządzają. Dzięki niej właściciele treści mogą jednorazowo uwierzytelnić się i uzyskiwać dostęp do wszystkich swoich filmów oraz danych dotyczących kanałów bez konieczności podawania danych uwierzytelniających dla każdego kanału z osobna. Konto CMS, za pomocą którego użytkownik uwierzytelnia się, musi być powiązane z określonym właścicielem treści YouTube. |
|
order |
string Parametr order określa metodę, która będzie używana do porządkowania zasobów w odpowiedzi interfejsu API. Wartość domyślna to relevance .Akceptowane wartości:
|
|
pageToken |
string Parametr pageToken wskazuje w zestawie wyników konkretną stronę, która ma zostać zwrócona. W odpowiedzi interfejsu API właściwości nextPageToken i prevPageToken identyfikują inne strony, które można pobrać. |
|
publishedAfter |
datetime Parametr publishedAfter wskazuje, że odpowiedź interfejsu API powinna zawierać tylko zasoby utworzone w określonym czasie lub później. Wartość jest sformatowaną w formacie RFC 3339 (1970-01-01T00:00:00Z). |
|
publishedBefore |
datetime Parametr publishedBefore wskazuje, że odpowiedź interfejsu API powinna zawierać tylko zasoby utworzone przed podanym czasem lub w określonym czasie. Wartość jest sformatowaną w formacie RFC 3339 (1970-01-01T00:00:00Z). |
|
q |
string Parametr q określa wyszukiwane hasło.W żądaniu możesz też użyć operatorów logicznych NOT ( - ) i LUB (| ), aby wykluczyć filmy lub znaleźć te, które są powiązane z jednym z kilku wyszukiwanych haseł. Aby np. wyszukiwać filmy pasujące do słów „łodzie” lub „żeglarstwo”, ustaw wartość parametru q na boating|sailing . Podobnie, aby wyszukiwać filmy pasujące do słowa „żeglarstwo”, ale nie „wędkarstwo”, ustaw wartość parametru q na boating|sailing -fishing . Pamiętaj, że pionowa kreska w żądaniu wysłanym w żądaniu do interfejsu API musi zawierać zmienione znaczenie w adresie URL. Zakodowana w adresie URL wartość znaku pionowej kreski to %7C . |
|
regionCode |
string Parametr regionCode informuje interfejs API, aby zwracał wyniki wyszukiwania filmów, które można wyświetlić w wybranym kraju. Jego wartością jest kod kraju zgodny ze standardem ISO 3166-1 alfa-2. |
|
relevanceLanguage |
string Parametr relevanceLanguage informuje interfejs API, aby zwracał wyniki wyszukiwania, które są najtrafniejsze dla określonego języka. Wartością tego parametru jest zwykle dwuliterowy kod języka w standardzie ISO 639-1. Należy jednak stosować wartości zh-Hans dla chińskiego uproszczonego i zh-Hant dla chińskiego tradycyjnego. Wyniki w innych językach będą nadal zwracane, jeśli będą ściśle związane z wyszukiwanym hasłem. |
|
safeSearch |
string Parametr safeSearch wskazuje, czy wyniki wyszukiwania powinny zawierać zarówno treści podlegające ograniczeniom, jak i treści standardowe.Akceptowane wartości to:
|
|
topicId |
string Parametr topicId wskazuje, że odpowiedź interfejsu API powinna zawierać tylko zasoby powiązane z określonym tematem. Ta wartość określa identyfikator tematu Freebase.Ważne: ze względu na wycofanie interfejsów Freebase i Freebase API od 27 lutego 2017 r. parametr topicId zaczął działać inaczej. W tym czasie YouTube zaczął obsługiwać niewielki zestaw wybranych identyfikatorów tematów, a jako wartości tego parametru możesz używać tylko tego mniejszego zestawu identyfikatorów. |
|
type |
string Parametr type ogranicza wyszukiwane hasło do pobrania tylko określonego typu zasobu. Wartość jest listą typów zasobów rozdzielonych przecinkami. Wartość domyślna to video,channel,playlist .Akceptowane wartości:
|
|
videoCaption |
string Parametr videoCaption wskazuje, czy interfejs API ma filtrować wyniki wyszukiwania filmów na podstawie tego, czy zawierają one napisy. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video .Akceptowane wartości:
|
|
videoCategoryId |
string Parametr videoCategoryId filtruje wyniki wyszukiwania filmów na podstawie ich kategorii. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video . |
|
videoDefinition |
string Parametr videoDefinition pozwala zawęzić wyszukiwanie tylko do filmów w wysokiej (HD) lub standardowej (SD). Filmy HD można odtwarzać w rozdzielczości co najmniej 720p, ale wyższe rozdzielczości, takie jak 1080p, również mogą być dostępne. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video .Akceptowane wartości:
|
|
videoDimension |
string Parametr videoDimension pozwala ograniczyć wyszukiwanie tylko do filmów 2D lub 3D. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video .Akceptowane wartości:
|
|
videoDuration |
string Parametr videoDuration filtruje wyniki wyszukiwania filmów na podstawie ich czasu trwania. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video .Akceptowane wartości:
|
|
videoEmbeddable |
string Parametr videoEmbeddable pozwala ograniczyć wyszukiwanie tylko do tych filmów, które można umieścić na stronie internetowej. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video .Akceptowane wartości:
|
|
videoLicense |
string Parametr videoLicense filtruje wyniki wyszukiwania, tak aby zawierały tylko filmy z konkretną licencją. YouTube pozwala osobom przesyłającym filmy dołączyć licencję Creative Commons lub standardową licencję YouTube do każdego filmu. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video .Akceptowane wartości:
|
|
videoPaidProductPlacement |
string Parametr videoPaidProductPlacement filtruje wyniki wyszukiwania tak, aby uwzględniać tylko te filmy, które twórca oznaczył jako płatną promocję. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video .Akceptowane wartości:
|
|
videoSyndicated |
string Parametr videoSyndicated pozwala ograniczyć wyszukiwanie tylko do filmów, które można odtwarzać poza youtube.com. Po określeniu wartości parametru type musisz też ustawić jego wartość na video .Akceptowane wartości:
|
|
videoType |
string Parametr videoType pozwala ograniczyć wyszukiwanie do konkretnego typu filmów. Jeśli określisz wartość tego parametru, musisz też ustawić wartość parametru type na video .Akceptowane wartości:
|
Treść żądania
Nie podawaj treści żądania podczas wywoływania tej metody.
Odpowiedź
Jeśli operacja się uda, metoda zwróci odpowiedź o następującej strukturze:
{ "kind": "youtube#searchListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "regionCode": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ search Resource ] }
Właściwości
Poniższa tabela przedstawia właściwości, które pojawiają się w wynikach wyszukiwania:
Właściwości | |
---|---|
kind |
string Określa typ zasobu interfejsu API. Wartością będzie youtube#searchListResponse . |
etag |
etag ETag tego zasobu. |
nextPageToken |
string Token, który może być używany jako wartość parametru pageToken w celu pobrania następnej strony w zestawie wyników. |
prevPageToken |
string Token, który może być używany jako wartość parametru pageToken do pobierania poprzedniej strony w zestawie wyników. |
regionCode |
string Kod regionu użyty w zapytaniu. Wartość właściwości to dwuliterowy kod ISO kraju, który identyfikuje region. Metoda i18nRegions.list zwraca listę obsługiwanych regionów. Wartością domyślną jest US . Jeśli określisz nieobsługiwany region, YouTube może wybrać do obsługi zapytania inny region zamiast wartości domyślnej. |
pageInfo |
object Obiekt pageInfo zawiera informacje o stronicowaniu zbioru wyników. |
pageInfo.totalResults |
integer Łączna liczba wyników w zestawie wyników.Pamiętaj, że jest to wartość przybliżona i może nie być dokładną. Dodatkowo maksymalna wartość to 1 000 000. Nie należy używać tej wartości do tworzenia linków do podziału na strony. Zamiast tego użyj wartości właściwości nextPageToken i prevPageToken , aby określić, czy wyświetlić linki do podziału na strony. |
pageInfo.resultsPerPage |
integer Liczba wyników uwzględnionych w odpowiedzi interfejsu API. |
items[] |
list Lista wyników pasujących do kryteriów wyszukiwania. |
Przykłady
Uwaga: poniższe przykłady kodu mogą nie obejmować wszystkich obsługiwanych języków programowania. Listę obsługiwanych języków znajdziesz w dokumentacji bibliotek klienta.
Google Apps Script
Ta funkcja wyszukuje filmy wideo związane ze słowem kluczowym „psy”. Identyfikatory filmów i tytuły wyników wyszukiwania są rejestrowane w dzienniku Apps Script.Pamiętaj, że ta próbka ogranicza wyniki do 25. Aby wyświetlić więcej wyników, przekaż dodatkowe parametry zgodnie z opisem tutaj: https://developers.google.com/youtube/v3/docs/search/list
function searchByKeyword() { var results = YouTube.Search.list('id,snippet', {q: 'dogs', maxResults: 25}); for(var i in results.items) { var item = results.items[i]; Logger.log('[%s] Title: %s', item.id.videoId, item.snippet.title); } }
Go
Ten przykładowy kod wywołuje metodęsearch.list
interfejsu API, aby pobrać wyniki wyszukiwania powiązane z określonym słowem kluczowym.
W tym przykładzie korzystamy z biblioteki klienta w Go.
package main import ( "flag" "fmt" "log" "net/http" "google.golang.org/api/googleapi/transport" "google.golang.org/api/youtube/v3" ) var ( query = flag.String("query", "Google", "Search term") maxResults = flag.Int64("max-results", 25, "Max YouTube results") ) const developerKey = "YOUR DEVELOPER KEY" func main() { flag.Parse() client := &http.Client{ Transport: &transport.APIKey{Key: developerKey}, } service, err := youtube.New(client) if err != nil { log.Fatalf("Error creating new YouTube client: %v", err) } // Make the API call to YouTube. call := service.Search.List("id,snippet"). Q(*query). MaxResults(*maxResults) response, err := call.Do() handleError(err, "") // Group video, channel, and playlist results in separate lists. videos := make(map[string]string) channels := make(map[string]string) playlists := make(map[string]string) // Iterate through each item and add it to the correct list. for _, item := range response.Items { switch item.Id.Kind { case "youtube#video": videos[item.Id.VideoId] = item.Snippet.Title case "youtube#channel": channels[item.Id.ChannelId] = item.Snippet.Title case "youtube#playlist": playlists[item.Id.PlaylistId] = item.Snippet.Title } } printIDs("Videos", videos) printIDs("Channels", channels) printIDs("Playlists", playlists) } // Print the ID and title of each result in a list as well as a name that // identifies the list. For example, print the word section name "Videos" // above a list of video search results, followed by the video ID and title // of each matching video. func printIDs(sectionName string, matches map[string]string) { fmt.Printf("%v:\n", sectionName) for id, title := range matches { fmt.Printf("[%v] %v\n", id, title) } fmt.Printf("\n\n") }
.NET
Poniższy przykładowy kod wywołuje metodęsearch.list
interfejsu API, aby pobrać wyniki wyszukiwania powiązane z konkretnym słowem kluczowym.
W tym przykładzie korzystamy z biblioteki klienta.NET.
using System; using System.Collections.Generic; using System.IO; using System.Reflection; using System.Threading; using System.Threading.Tasks; using Google.Apis.Auth.OAuth2; using Google.Apis.Services; using Google.Apis.Upload; using Google.Apis.Util.Store; using Google.Apis.YouTube.v3; using Google.Apis.YouTube.v3.Data; namespace Google.Apis.YouTube.Samples { /// <summary> /// YouTube Data API v3 sample: search by keyword. /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher. /// See https://developers.google.com/api-client-library/dotnet/get_started /// /// Set ApiKey to the API key value from the APIs & auth > Registered apps tab of /// https://cloud.google.com/console /// Please ensure that you have enabled the YouTube Data API for your project. /// </summary> internal class Search { [STAThread] static void Main(string[] args) { Console.WriteLine("YouTube Data API: Search"); Console.WriteLine("========================"); try { new Search().Run().Wait(); } catch (AggregateException ex) { foreach (var e in ex.InnerExceptions) { Console.WriteLine("Error: " + e.Message); } } Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } private async Task Run() { var youtubeService = new YouTubeService(new BaseClientService.Initializer() { ApiKey = "REPLACE_ME", ApplicationName = this.GetType().ToString() }); var searchListRequest = youtubeService.Search.List("snippet"); searchListRequest.Q = "Google"; // Replace with your search term. searchListRequest.MaxResults = 50; // Call the search.list method to retrieve results matching the specified query term. var searchListResponse = await searchListRequest.ExecuteAsync(); List<string> videos = new List<string>(); List<string> channels = new List<string>(); List<string> playlists = new List<string>(); // Add each result to the appropriate list, and then display the lists of // matching videos, channels, and playlists. foreach (var searchResult in searchListResponse.Items) { switch (searchResult.Id.Kind) { case "youtube#video": videos.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.VideoId)); break; case "youtube#channel": channels.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.ChannelId)); break; case "youtube#playlist": playlists.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.PlaylistId)); break; } } Console.WriteLine(String.Format("Videos:\n{0}\n", string.Join("\n", videos))); Console.WriteLine(String.Format("Channels:\n{0}\n", string.Join("\n", channels))); Console.WriteLine(String.Format("Playlists:\n{0}\n", string.Join("\n", playlists))); } } }
Ruby
Ten przykład wywołuje metodęsearch.list
interfejsu API, aby pobrać wyniki wyszukiwania powiązane z konkretnym słowem kluczowym.
W tym przykładzie korzystamy z biblioteki klienta Ruby.
#!/usr/bin/ruby require 'rubygems' gem 'google-api-client', '>0.7' require 'google/api_client' require 'trollop' # Set DEVELOPER_KEY to the API key value from the APIs & auth > Credentials # tab of # {{ Google Cloud Console }} <{{ https://cloud.google.com/console }}> # Please ensure that you have enabled the YouTube Data API for your project. DEVELOPER_KEY = 'REPLACE_ME' YOUTUBE_API_SERVICE_NAME = 'youtube' YOUTUBE_API_VERSION = 'v3' def get_service client = Google::APIClient.new( :key => DEVELOPER_KEY, :authorization => nil, :application_name => $PROGRAM_NAME, :application_version => '1.0.0' ) youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION) return client, youtube end def main opts = Trollop::options do opt :q, 'Search term', :type => String, :default => 'Google' opt :max_results, 'Max results', :type => :int, :default => 25 end client, youtube = get_service begin # Call the search.list method to retrieve results matching the specified # query term. search_response = client.execute!( :api_method => youtube.search.list, :parameters => { :part => 'snippet', :q => opts[:q], :maxResults => opts[:max_results] } ) videos = [] channels = [] playlists = [] # Add each result to the appropriate list, and then display the lists of # matching videos, channels, and playlists. search_response.data.items.each do |search_result| case search_result.id.kind when 'youtube#video' videos << "#{search_result.snippet.title} (#{search_result.id.videoId})" when 'youtube#channel' channels << "#{search_result.snippet.title} (#{search_result.id.channelId})" when 'youtube#playlist' playlists << "#{search_result.snippet.title} (#{search_result.id.playlistId})" end end puts "Videos:\n", videos, "\n" puts "Channels:\n", channels, "\n" puts "Playlists:\n", playlists, "\n" rescue Google::APIClient::TransmissionError => e puts e.result.body end end main
Błędy
W tabeli poniżej znajdziesz komunikaty o błędach, które interfejs API może zwrócić w odpowiedzi na wywołanie tej metody. Więcej szczegółów znajdziesz w dokumentacji komunikatów o błędach.
Typ błędu | Szczegóły błędu | Opis |
---|---|---|
badRequest (400) |
invalidChannelId |
Parametr channelId zawiera nieprawidłowy identyfikator kanału. |
badRequest (400) |
invalidLocation |
Wartość parametru location lub locationRadius była nieprawidłowo sformatowana. |
badRequest (400) |
invalidRelevanceLanguage |
Wartość parametru relevanceLanguage była nieprawidłowo sformatowana. |
badRequest (400) |
invalidSearchFilter |
Żądanie zawiera nieprawidłową kombinację filtrów wyszukiwania lub ograniczeń. Pamiętaj, że jeśli ustawisz parametr forContentOwner lub forMine na true , musisz ustawić parametr type na video . Jeśli ustawisz wartość parametru type na video , musisz ustawić wartość parametrów eventType , videoCaption , videoCategoryId , videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoSyndicated lub videoType . |
Wypróbuj
Użyj interfejsu APIs Explorer, aby wywołać ten interfejs API i wyświetlić żądanie oraz odpowiedź interfejsu API.