API isteğinde belirtilen sorgu parametreleriyle eşleşen arama sonuçları koleksiyonunu döndürür. Varsayılan olarak bir arama sonucu grubu eşleşen video
, channel
ve playlist
kaynaklarını tanımlar, ancak sorguları yalnızca belirli bir kaynak türünü alacak şekilde de yapılandırabilirsiniz.
Kota etkisi: Bu yönteme yapılan bir aramanın 100 birim kota maliyeti vardır.
Yaygın kullanım alanları
İstek
HTTP isteği
GET https://www.googleapis.com/youtube/v3/search
Parametreler
Aşağıdaki tabloda, bu sorgunun desteklediği parametreler listelenmiştir. Listelenen parametrelerin tümü sorgu parametreleridir.
Parametreler | ||
---|---|---|
Gerekli parametreler | ||
part |
string part parametresi, API yanıtının içereceği bir veya daha fazla search kaynak özelliğinin virgülle ayrılmış listesini belirtir. Parametre değerini snippet olarak ayarlayın.
|
|
Filtreler (aşağıdaki parametrelerden 0 veya 1 tanesini belirtin) | ||
forContentOwner |
boolean Bu parametre yalnızca uygun bir yetkili istekte kullanılabilir ve yalnızca YouTube içerik iş ortaklarına yöneliktir. forContentOwner parametresi, aramayı yalnızca onBehalfOfContentOwner parametresi tarafından tanımlanan içerik sahibine ait videoları almak için kısıtlar. forContentOwner doğru değerine ayarlanırsa isteğin şu şartları da karşılaması gerekir:
|
|
forDeveloper |
boolean Bu parametre yalnızca uygun bir yetkili istekte kullanılabilir. forDeveloper parametresi, yalnızca geliştiricinin uygulaması veya web sitesi üzerinden yüklenen videoları almak için aramayı kısıtlar. API sunucusu, geliştiriciyi tanımlamak için isteğin yetkilendirme kimlik bilgilerini kullanır. forDeveloper parametresi, q parametresi gibi isteğe bağlı arama parametreleriyle birlikte kullanılabilir.Bu özellik için yüklenen her video, Google Developers Console'da geliştiricinin uygulamasıyla ilişkilendirilen proje numarasıyla otomatik olarak etiketlenir. Arama isteği, daha sonra forDeveloper parametresini true olarak ayarladığında API sunucusu, geliştiriciyi tanımlamak için isteğin yetkilendirme kimlik bilgilerini kullanır. Bu nedenle, geliştiriciler sonuçları kendi uygulamaları veya web siteleri aracılığıyla yüklenen videolarla sınırlandırabilir, ancak diğer uygulamalar veya siteler üzerinden yüklenen videolarla sınırlandıramaz. |
|
forMine |
boolean Bu parametre yalnızca uygun bir yetkili istekte kullanılabilir. forMine parametresi, aramayı yalnızca kimliği doğrulanmış kullanıcının sahip olduğu videoları alacak şekilde kısıtlar. Bu parametreyi true olarak ayarlarsanız type parametresinin değeri de video olarak ayarlanmalıdır. Ayrıca, şu parametrelerden hiçbiri aynı istekte ayarlanamaz: videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoPaidProductPlacement , videoSyndicated , videoType . |
|
İsteğe bağlı parametreler | ||
channelId |
string channelId parametresi, API yanıtının yalnızca kanal tarafından oluşturulan kaynakları içermesi gerektiğini belirtir. Not: İsteğiniz channelId parametresi için bir değer belirtiyor ve type parametre değerini video olarak ayarlıyorsa arama sonuçları en fazla 500 videoyla sınırlıdır. Ancak forContentOwner , forDeveloper veya forMine filtrelerinden birini de ayarlamaz. |
|
channelType |
string channelType parametresi, aramayı belirli bir kanal türüyle kısıtlamanıza olanak tanır.Kabul edilen değerler şunlardır:
|
|
eventType |
string eventType parametresi, aramaları yayın etkinlikleriyle kısıtlar. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
|
location |
string location parametresi, locationRadius parametresiyle birlikte dairesel bir coğrafi alan tanımlar ve aramayı meta verilerinde o bölge içinde yer alan bir coğrafi konum belirten videolarla sınırlandırır. Parametre değeri, enlem/boylam koordinatlarını belirten bir dizedir (ör. 37.42307,-122.08427 ).
location parametresi için bir değer belirtiyor ancak locationRadius parametresi için de bir değer belirtmiyorsa API bir hata döndürür.Not: Bu parametre için bir değer belirtirseniz type parametresinin değerini video olarak da ayarlamanız gerekir.
| |
locationRadius |
string locationRadius parametresi, location parametresiyle birlikte dairesel bir coğrafi alanı tanımlar.Parametre değeri, kayan nokta sayısı ve ardından ölçüm birimi olmalıdır. Geçerli ölçüm birimleri: m , km , ft ve mi . Örneğin, geçerli parametre değerleri 1500m , 5km , 10000ft ve 0.75mi değerini içerir. API, 1.000 kilometreden büyük locationRadius parametre değerlerini desteklemiyor.Not: Daha fazla bilgi için location parametresinin tanımına bakın. |
|
maxResults |
unsigned integer maxResults parametresi, sonuç grubunda döndürülmesi gereken maksimum öğe sayısını belirtir. Kabul edilebilir değerler 0 ile 50 arasındadır (dahil). Varsayılan değer: 5 |
|
onBehalfOfContentOwner |
string Bu parametre yalnızca uygun bir yetkili istekte kullanılabilir. Not: Bu parametre yalnızca YouTube içerik iş ortakları içindir. onBehalfOfContentOwner parametresi, isteğin yetkilendirme kimlik bilgilerinin, parametre değerinde belirtilen içerik sahibi adına hareket eden bir YouTube İYS kullanıcısını tanımladığını gösterir. Bu parametre, birçok farklı YouTube kanalına sahip olan ve bunları yöneten YouTube içerik iş ortakları için tasarlanmıştır. Bu sayede içerik sahipleri, her kanal için kimlik doğrulama bilgileri sağlamak zorunda kalmadan tüm kimlik doğrulamasından yararlanarak video ve kanal verilerine erişebilir. Kullanıcının kimlik doğrulaması yaptığı İYS hesabı, belirtilen YouTube içerik sahibine bağlı olmalıdır. |
|
order |
string order parametresi, API yanıtında kaynakları sıralamak için kullanılacak yöntemi belirtir. Varsayılan değer: relevance .Kabul edilen değerler şunlardır:
|
|
pageToken |
string pageToken parametresi, sonuç kümesinde döndürülmesi gereken belirli bir sayfayı tanımlar. Bir API yanıtında, nextPageToken ve prevPageToken özellikleri, alınabilecek diğer sayfaları tanımlar. |
|
publishedAfter |
datetime publishedAfter parametresi, API yanıtının yalnızca belirtilen zamanda veya sonrasında oluşturulan kaynakları içermesi gerektiğini belirtir. Değer, RFC 3339 biçiminde bir tarih ve saat değeridir (1970-01-01T00:00:00Z). |
|
publishedBefore |
datetime publishedBefore parametresi, API yanıtının yalnızca belirtilen zamanda veya öncesinde oluşturulan kaynakları içermesi gerektiğini belirtir. Değer, RFC 3339 biçiminde bir tarih ve saat değeridir (1970-01-01T00:00:00Z). |
|
q |
string q parametresi, aranacak sorgu terimini belirtir.İsteğiniz, videoları hariç tutmak veya birkaç arama teriminden biriyle ilişkili videoları bulmak için NOT (Boole) ( - ) ve OR (| ) operatörlerini de kullanabilir. Örneğin, "tekne" veya "yelkencilik" terimleriyle eşleşen videoları aramak için q parametre değerini boating|sailing olarak ayarlayın. Benzer şekilde, "tekne" veya "yelkencilik" terimleriyle eşleşen fakat "balıkçılık" ile eşleşmeyen videoları aramak için q parametre değerini boating|sailing -fishing olarak ayarlayın. Dikey çizgi karakterinin, API isteğinizde URL çıkışlı olarak gönderilmesi gerektiğini unutmayın. Dikey çizgi karakterinin URL çıkışlı değeri: %7C . |
|
regionCode |
string regionCode parametresi, API'ye belirtilen ülkede görüntülenebilecek videolar için arama sonuçları döndürmesi talimatı verir. Parametre değeri, ISO 3166-1 alpha-2 ülke kodudur. |
|
relevanceLanguage |
string relevanceLanguage parametresi, API'ye belirtilen dille en alakalı arama sonuçlarını döndürmesini bildirir. Parametre değeri genellikle ISO 639-1 iki harfli dil kodudur. Ancak basitleştirilmiş Çince için zh-Hans ve geleneksel Çince için zh-Hant değerlerini kullanmanız gerekir. Diğer dillerdeki sonuçların, arama sorgusu terimiyle alaka düzeyi yüksek olduğunda yine döndürüleceğini lütfen unutmayın. |
|
safeSearch |
string safeSearch parametresi, arama sonuçlarının standart içeriğin yanı sıra kısıtlanmış içeriği de içermesi gerekip gerekmediğini ifade eder.Kabul edilen değerler şunlardır:
|
|
topicId |
string topicId parametresi, API yanıtının yalnızca belirtilen konuyla ilişkili kaynakları içermesi gerektiğini belirtir. Değer, Freebase konu kimliğini tanımlar.Önemli: Freebase ve Freebase API'nin kullanımdan kaldırılması nedeniyle topicId parametresi 27 Şubat 2017'den itibaren farklı şekilde çalışmaya başladı. O dönemde, YouTube bu özel konu kimliklerinden oluşan küçük bir grubu desteklemeye başladı. Bu parametre grubunu yalnızca küçük parametre grupları için kullanabilirsiniz. |
|
type |
string type parametresi, bir arama sorgusunu yalnızca belirli bir kaynak türünü alacak şekilde kısıtlar. Değer, kaynak türlerinin virgülle ayrılmış listesidir. Varsayılan değer: video,channel,playlist .Kabul edilen değerler şunlardır:
|
|
videoCaption |
string videoCaption parametresi, API'nin altyazılı olup olmadığına göre video arama sonuçlarını filtreleyip filtrelemeyeceğini gösterir. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
|
videoCategoryId |
string videoCategoryId parametresi, video arama sonuçlarını kategorisine göre filtreler. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir. |
|
videoDefinition |
string videoDefinition parametresi, bir aramayı yalnızca yüksek çözünürlüklü (HD) veya standart çözünürlüklü (SD) videoları içerecek şekilde kısıtlamanıza olanak tanır. HD videolar en az 720p çözünürlükte oynatılabilir ancak 1080p gibi yüksek çözünürlükler de kullanılabilir. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
|
videoDimension |
string videoDimension parametresi, bir aramayı yalnızca 2D veya 3D videoları alacak şekilde kısıtlamanıza olanak tanır. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
|
videoDuration |
string videoDuration parametresi, video arama sonuçlarını sürelerine göre filtreler. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
|
videoEmbeddable |
string videoEmbeddable parametresi, bir aramayı yalnızca bir web sayfasına yerleştirilebilecek videolarla kısıtlamanızı sağlar. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
|
videoLicense |
string videoLicense parametresi, arama sonuçlarını yalnızca belirli bir lisansa sahip videoları içerecek şekilde filtreler. YouTube, video yükleyicilerin her bir videoya Creative Commons lisansı veya standart YouTube lisansı eklemeyi seçebilmesini sağlar. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
|
videoPaidProductPlacement |
string videoPaidProductPlacement parametresi, arama sonuçlarını yalnızca içerik üreticinin ücretli tanıtım barındırdığını belirttiği videoları içerecek şekilde filtreler. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
|
videoSyndicated |
string videoSyndicated parametresi, bir aramayı yalnızca youtube.com dışında oynatılabilecek videolarla kısıtlamanızı sağlar. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
|
videoType |
string videoType parametresi, aramayı belirli bir video türüyle kısıtlamanıza olanak tanır. Bu parametre için bir değer belirtirseniz type parametresinin değerini de video olarak ayarlamanız gerekir.Kabul edilen değerler şunlardır:
|
İstek içeriği
Bu yöntemi çağırırken istek gövdesi sağlama.
Yanıt
Başarılı olursa bu yöntem aşağıdaki yapıya sahip bir yanıt gövdesi döndürür:
{ "kind": "youtube#searchListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "regionCode": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ search Resource ] }
Özellikler
Aşağıdaki tabloda, arama sonucunda görünen özellikler tanımlanmaktadır:
Özellikler | |
---|---|
kind |
string API kaynağının türünü tanımlar. Değer youtube#searchListResponse olacak. |
etag |
etag Bu kaynağın Etag'i. |
nextPageToken |
string Sonuç grubunda sonraki sayfayı almak için pageToken parametresinin değeri olarak kullanılabilecek jeton. |
prevPageToken |
string Sonuç kümesinde önceki sayfayı almak için pageToken parametresinin değeri olarak kullanılabilecek jeton. |
regionCode |
string Arama sorgusu için kullanılan bölge kodu. Özellik değeri, bölgeyi tanımlayan iki harfli ISO ülke kodudur. i18nRegions.list yöntemi, desteklenen bölgelerin listesini döndürür. Varsayılan değer: US Desteklenmeyen bir bölge belirtilirse YouTube, sorguyu işlemek için varsayılan değer yerine başka bir bölge seçebilir. |
pageInfo |
object pageInfo nesnesi, sonuç grubunun sayfalama bilgilerini içerir. |
pageInfo.totalResults |
integer Sonuç kümesindeki toplam sonuç sayısı.Değerin yaklaşık bir değer olduğunu ve tam değeri yansıtmayabileceğini lütfen unutmayın. Ayrıca, maksimum değer 1.000.000'dır. Sayfalara ayırma bağlantıları oluşturmak için bu değeri kullanmamalısınız. Bunun yerine, sayfalara ayırma bağlantılarının gösterilip gösterilmeyeceğini belirlemek için nextPageToken ve prevPageToken özellik değerlerini kullanın. |
pageInfo.resultsPerPage |
integer API yanıtına dahil edilen sonuçların sayısı. |
items[] |
list Arama ölçütleriyle eşleşen sonuçların listesi. |
Örnekler
Not: Aşağıdaki kod örnekleri, desteklenen tüm programlama dillerini temsil etmeyebilir. Desteklenen dillerin listesi için istemci kitaplıkları dokümanlarına bakın.
Apps Komut Dosyası
Bu işlev, "köpekler" anahtar kelimesiyle ilgili videoları arar. Arama sonuçlarının video kimlikleri ve başlıkları Apps Komut Dosyası'nın günlüğüne kaydedilir.Bu örneğin, sonuçları 25 ile sınırlandırdığını unutmayın. Daha fazla sonuç döndürmek için şu sayfada açıklanan şekilde ek parametreleri iletin: 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
Bu kod örneği, belirli bir anahtar kelimeyle ilişkili arama sonuçlarını almak için API'ninsearch.list
yöntemini çağırır.
Bu örnekte Go istemci kitaplığı kullanılmaktadır.
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
Aşağıdaki kod örneği, belirli bir anahtar kelimeyle ilişkili arama sonuçlarını almak için API'ninsearch.list
yöntemini çağırır.
Bu örnekte .NET istemci kitaplığı kullanılmaktadır.
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
Bu örnek, belirli bir anahtar kelimeyle ilişkili arama sonuçlarını almak için API'ninsearch.list
yöntemini çağırır.
Bu örnekte Ruby istemci kitaplığı kullanılmaktadır.
#!/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
Hatalar
Aşağıdaki tabloda, API'nin bu yönteme yapılan bir çağrıya yanıt olarak döndürebileceği hata mesajları tanımlanmaktadır. Daha fazla bilgi için lütfen hata mesajı belgelerini inceleyin.
Hata türü | Hata ayrıntısı | Açıklama |
---|---|---|
badRequest (400) |
invalidChannelId |
channelId parametresi geçersiz bir kanal kimliği belirtiyor. |
badRequest (400) |
invalidLocation |
location ve/veya locationRadius parametre değeri yanlış biçimlendirilmiş. |
badRequest (400) |
invalidRelevanceLanguage |
relevanceLanguage parametre değeri yanlış biçimlendirilmiş. |
badRequest (400) |
invalidSearchFilter |
İstek, geçersiz bir arama filtresi ve/veya kısıtlama kombinasyonu içeriyor. forContentOwner veya forMine parametrelerini true olarak ayarlarsanız type parametresini video olarak ayarlamanız gerektiğini unutmayın. eventType , videoCaption , videoCategoryId , videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoSyndicated veya videoType parametreleri için değer belirlediyseniz type parametresini video olarak da ayarlamanız gerekir. |
Deneyin.
Bu API'yi çağırmak ve API isteği ile yanıtını görmek için APIs Explorer kullanın.