Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

YouTube Data API'ye Genel Bakış

Giriş

Bu belge, YouTube ile etkileşimde bulunan uygulamalar yazmak isteyen geliştiriciler için hazırlanmıştır. YouTube'un ve API'nin temel kavramları açıklanır. Ayrıca API'nin desteklediği farklı işlevlere genel bir bakış sunar.

Başlamadan önce

Google Cloud Console'a erişmek, API anahtarı istemek ve uygulamanızı kaydetmek için Google Hesabı'na ihtiyacınız vardır.
Google Developers Console'da bir proje oluşturun ve uygulamanızın API istekleri gönderebilmesi için yetkilendirme kimlik bilgileri alın.
Projenizi oluşturduktan sonra YouTube Data API'nin, uygulamanızın kullanmak üzere kayıtlı olduğu hizmetlerden biri olduğundan emin olun:
1. Cloud Console'a gidip yeni kaydettiğiniz projeyi seçin.
2. Etkin API'ler sayfasını ziyaret edin. YouTube Data API'nin etkinleştirilmiş API'ler listesinde yer aldığından emin olun. Etkin değilse API kitaplığını açın ve API'yi etkinleştirin.
Uygulamanız kullanıcı yetkilendirmesi gerektiren herhangi bir API yöntemini kullanacaksa OAuth 2.0 yetkilendirmesini nasıl uygulayacağınızı öğrenmek için yetkilendirme rehberini okuyun.
API uygulamanızı basitleştirmek için bir istemci kitaplığı seçin.
JSON (JavaScript Nesnesi Gösterimi) veri biçiminin temel kavramlarını öğrenme JSON, rastgele veri yapılarını basit metin biçiminde sunan, yaygın şekilde kullanılan ve dilden bağımsız bir veri biçimidir. Daha fazla bilgi için json.org adresine bakın.

Kaynaklar ve kaynak türleri

Kaynak, benzersiz tanımlayıcısı olan bağımsız bir veri varlığıdır. Aşağıdaki tabloda, API'yi kullanarak etkileşim kurabileceğiniz farklı kaynak türleri açıklanmaktadır.

Kaynaklar
`activity`	Belirli bir kullanıcının YouTube sitesinde gerçekleştirdiği işlemle ilgili bilgileri içerir. Etkinlik feed'lerinde bildirilen kullanıcı işlemleri arasında videolara puan verme, video paylaşma, videoları favori olarak işaretleme ve kanal duyurusu yayınlama gibi işlemler yer alır.
`channel`	Tek bir YouTube kanalıyla ilgili bilgileri içerir.
`channelBanner`	Yeni yüklenen bir resmi kanalın banner resmi olarak ayarlamak için kullanılacak URL'yi tanımlar.
`channelSection`	Bir kanalın öne çıkarmayı seçtiği bir grup videoyla ilgili bilgiler içerir. Örneğin, bir bölümde kanalın en son yüklemeleri, en popüler yüklemeleri veya bir ya da daha fazla oynatma listesindeki videolar yer alabilir.
`guideCategory`	YouTube'un, içeriklerine veya popülerlik gibi diğer göstergelere göre kanallarla ilişkilendirdiği bir kategoriyi tanımlar. Rehber kategorileri, YouTube kullanıcılarının aradıkları içerikleri daha kolay bulabilmeleri için kanalları düzenlemeyi amaçlar. Kanallar bir veya daha fazla rehber kategorisiyle ilişkilendirilebilir ancak herhangi bir rehber kategorisinde yer almaları garanti edilmez.
`i18nLanguage`	YouTube web sitesinin desteklediği bir uygulama dilini tanımlar. Uygulama dili, kullanıcı arayüzü dili olarak da adlandırılabilir.
`i18nRegion`	YouTube kullanıcısının tercih edilen içerik bölgesi olarak seçebileceği coğrafi alanı tanımlar. İçerik bölgesi, içerik yerel ayarı olarak da adlandırılabilir.
`playlist`	Tek bir YouTube oynatma listesini temsil eder. Oynatma listesi, sırayla izlenebilen ve diğer kullanıcılarla paylaşılabilen videolardan oluşan bir koleksiyondur.
`playlistItem`	Oynatma listesinde yer alan bir kaynak (ör. video) tanımlar. playlistItem kaynağı, dahil edilen kaynağın oynatma listesinde nasıl kullanıldığını açıklayan ayrıntılar da içerir.
`search result`	Bir API isteğinde belirtilen arama parametreleriyle eşleşen YouTube videosu, kanalı veya oynatma listesi hakkında bilgiler içerir. Arama sonuçları, video gibi kimliği net bir şekilde tespit edilebilir bir kaynağa işaret etse de kendi kalıcı verilerine sahip değildir.
`subscription`	YouTube kullanıcı aboneliğiyle ilgili bilgileri içerir. Abonelik, bir kanala yeni videolar eklendiğinde veya başka bir kullanıcı YouTube'da video yükleme, video değerlendirme ya da videoya yorum yapma gibi işlemlerden birini gerçekleştirdiğinde kullanıcıya bildirim gönderir.
`thumbnail`	Bir kaynakla ilişkili küçük resimleri tanımlar.
`video`	Tek bir YouTube videosunu temsil eder.
`videoCategory`	Yüklenen videolarla ilişkilendirilmiş veya ilişkilendirilebilecek bir kategoriyi tanımlar.
`watermark`	Belirli bir kanalın videoları oynatılırken gösterilen resmi tanımlar. Kanal sahibi, resmin bağlantı vereceği hedef kanalı ve filigranın video oynatma sırasında ne zaman görüneceğini ve ne kadar süreyle görünür kalacağını belirleyen zamanlama ayrıntılarını da belirtebilir.

Çoğu durumda bir kaynağın diğer kaynaklara referanslar içerdiğini unutmayın. Örneğin, bir playlistItem kaynağının snippet.resourceId.videoId özelliği, video hakkında eksiksiz bilgiler içeren bir video kaynağını tanımlar. Başka bir örnek olarak, bir arama sonucu belirli bir video, oynatma listesi veya kanal kaynağını tanımlayan bir videoId, playlistId ya da channelId özelliği içerir.

Desteklenen işlemler

Aşağıdaki tabloda, API'nin desteklediği en yaygın yöntemler gösterilmektedir. Bazı kaynaklar, bu kaynaklara özgü işlevleri gerçekleştiren başka yöntemleri de destekler. Örneğin, videos.rate yöntemi bir kullanıcı puanını bir videoyla ilişkilendirirken thumbnails.set yöntemi bir video küçük resmi görüntüsünü YouTube'a yükleyip bir videoyla ilişkilendirir.

İşlemler
`list`	Sıfır veya daha fazla kaynak içeren bir liste alır (`GET`).
`insert`	Yeni bir kaynak oluşturur (`POST`).
`update`	İsteğinizdeki verileri yansıtmak için mevcut bir kaynağı değiştirir (`PUT`).
`delete`	Belirli bir kaynağı kaldırır (`DELETE`).

API şu anda desteklenen kaynak türlerinin her birini listeleyen yöntemleri ve birçok kaynak için yazma işlemlerini desteklemektedir.

Aşağıdaki tabloda, farklı kaynak türleri için desteklenen işlemler belirtilmektedir. Kaynakları ekleyen, güncelleyen veya silen işlemler için her zaman kullanıcı yetkilendirmesi gerekir. Bazı durumlarda list yöntemleri hem yetkili hem de yetkisiz istekleri destekler. Yetkisiz istekler yalnızca herkese açık verileri alırken yetkili istekler, kimliği doğrulanmış mevcut kullanıcıyla ilgili veya kullanıcıya özel bilgileri de alabilir.

Desteklenen işlemler
	list	insert	update	delete
`activity`
`caption`
`channel`
`channelBanner`
`channelSection`
`comment`
`commentThread`
`guideCategory`
`i18nLanguage`
`i18nRegion`
`playlist`
`playlistItem`
`search result`
`subscription`
`thumbnail`
`video`
`videoCategory`
`watermark`

Kota kullanımı

YouTube Data API, geliştiricilerin hizmeti amaçlandığı şekilde kullanmasını ve hizmet kalitesini haksız bir şekilde düşüren veya başkalarının erişimini sınırlayan uygulamalar oluşturmamasını sağlamak için bir kota kullanır. Geçersiz istekler de dahil olmak üzere tüm API istekleri en az bir puanlık kota maliyetine neden olur. Uygulamanızın kullanabileceği kotayı API Console bölümünde bulabilirsiniz.

YouTube Data API'yi etkinleştiren projelerin varsayılan kota tahsisi 100 search.list çağrı, 100 videos.insert çağrı ve diğer tüm uç noktalar için günlük toplam 10.000 birimdir. Değişikliğe tabi olan varsayılan kota, kota tahsislerini optimize etmemize ve altyapımızı API kullanıcılarımız için daha anlamlı olacak şekilde ölçeklendirmemize yardımcı olur. Kota kullanımınızı API Konsolu'ndaki Kotalar sayfasında görebilirsiniz.

Not: Kota sınırına ulaşırsanız YouTube API Hizmetleri için Kota artırma isteği formunu doldurarak ek kota isteğinde bulunabilirsiniz.

Kota kullanımını hesaplama

Google, her isteğe bir maliyet atayarak kota kullanımınızı hesaplar. Farklı işlem türlerinin farklı kota maliyetleri vardır. Örneğin:

Bir kaynak listesini (kanallar, videolar, oynatma listeleri) alan okuma işlemi genellikle 1 birim maliyetlidir.
Kaynak oluşturan, güncelleyen veya silen bir yazma işleminin maliyeti genellikle 50 birimdir.
Bir arama sorgusu 1 birim maliyetlidir.
Video yükleme işlemi 1 birim tutar.

API isteklerinin kota maliyetleri tablosunda her API yönteminin kota maliyeti gösterilir. Bu kuralları göz önünde bulundurarak uygulamanızın kotanızı aşmadan bir gün içinde gönderebileceği istek sayısını tahmin edebilirsiniz.

Kısmi kaynaklar

API, uygulamaların gereksiz verileri aktarmasını, ayrıştırmasını ve depolamasını önlemek için kısmi kaynakların alınmasına izin verir ve hatta bunu zorunlu kılar. Bu yaklaşım, API'nin ağ, CPU ve bellek kaynaklarını daha verimli kullanmasını da sağlar.

API, API yanıtlarına dahil edilmesi gereken kaynak özelliklerini tanımlamanıza olanak tanıyan iki istek parametresini destekler. Bu parametreler aşağıdaki bölümlerde açıklanmıştır.

part parametresi, bir kaynak için döndürülmesi gereken özellik gruplarını tanımlar.
fields parametresi, API yanıtını yalnızca istenen kaynak bölümlerindeki belirli özellikleri döndürecek şekilde filtreler.

`part` parametresini kullanma

part parametresi, bir kaynağı alan veya döndüren tüm API istekleri için zorunlu bir parametredir. Parametre, API yanıtına dahil edilmesi gereken bir veya daha fazla üst düzey (iç içe yerleştirilmemiş) kaynak özelliğini tanımlar. Örneğin, bir video kaynağı aşağıdaki bölümleri içerir:

snippet
contentDetails
fileDetails
player
processingDetails
recordingDetails
statistics
status
suggestions
topicDetails

Bu parçaların tümü, iç içe yerleştirilmiş özellikler içeren nesnelerdir. Bu nesneleri, API sunucusunun alabileceği (veya alamayacağı) meta veri alanları grupları olarak düşünebilirsiniz. Bu nedenle, part parametresi, uygulamanızın gerçekte kullandığı kaynak bileşenlerini seçmenizi gerektirir. Bu şartın iki temel amacı vardır:

API sunucusunun, uygulamanızın kullanmadığı meta veri alanlarını almak için zaman harcamasını önleyerek gecikmeyi azaltır.
Uygulamanızın alabileceği gereksiz veri miktarını azaltarak (veya ortadan kaldırarak) bant genişliği kullanımını azaltır.

Zaman içinde kaynaklar daha fazla bölüm ekledikçe uygulamanız desteklemediği yeni özellikleri istemeyeceği için bu avantajlar daha da artacaktır.

`fields` parametresi nasıl kullanılır?

fields parametresi, API yanıtını filtreler. Bu yanıt, yalnızca part parametre değerinde tanımlanan kaynak bölümlerini içerir. Böylece yanıt, yalnızca belirli bir alan grubunu içerir. fields parametresi, iç içe yerleştirilmiş özellikleri API yanıtından kaldırmanıza ve böylece bant genişliği kullanımınızı daha da azaltmanıza olanak tanır. (part parametresi, yanıttaki iç içe yerleştirilmiş özellikleri filtrelemek için kullanılamaz.)

Aşağıdaki kurallar, fields parametre değeri için desteklenen söz dizimini açıklar. Bu söz dizimi, temel olarak XPath söz dizimine benzer:

Birden fazla alan seçmek için virgülle ayrılmış liste (fields=a,b) kullanın.
Tüm alanları tanımlamak için joker karakter olarak yıldız (fields=*) kullanın.
API yanıtına dahil edilecek iç içe yerleştirilmiş özellikler grubunu belirtmek için parantez (fields=a(b,c)) kullanın.
İç içe yerleştirilmiş bir özelliği tanımlamak için eğik çizgi (fields=a/b) kullanın.

Uygulamada bu kurallar, genellikle birkaç farklı fields parametre değerinin aynı API yanıtını almasına olanak tanır. Örneğin, bir oynatma listesindeki her öğe için oynatma listesi öğesinin kimliğini, başlığını ve konumunu almak istiyorsanız aşağıdaki değerlerden herhangi birini kullanabilirsiniz:

fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
fields=items(id,snippet/title,snippet/position)
fields=items(id,snippet(title,position))

Not: Tüm sorgu parametresi değerlerinde olduğu gibi, fields parametre değeri de URL olarak kodlanmalıdır. Daha kolay anlaşılması için bu belgedeki örneklerde kodlama kısmı atlanmıştır.

Örnek kısmi istekler

Aşağıdaki örneklerde, API yanıtlarının yalnızca uygulamanızın kullandığı verileri içermesini sağlamak için part ve fields parametrelerini nasıl kullanabileceğiniz gösterilmektedir:

1. örnek, dört bölümün yanı sıra kind ve etag özelliklerini içeren bir video kaynağı döndürür.
2. örnek, iki bölümün yanı sıra kind ve etag özelliklerini içeren bir video kaynağı döndürür.
3. örnek, iki bölüm içeren ancak kind ve etag özelliklerini hariç tutan bir video kaynağı döndürür.
Örnek 4, iki bölüm içeren ancak kind ve etag'nin yanı sıra kaynağın snippet nesnesindeki bazı iç içe yerleştirilmiş özellikleri hariç tutan bir video kaynağı döndürür.

1. örnek

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"
   }
  }
 ]
}

2. örnek

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"
   }
  }
 ]
}

3. örnek

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"
   }
  }
 ]
}

4. örnek

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"
   }
  }
 ]
}

Performansı optimize etme

ETag'leri kullanma

HTTP protokolünün standart bir parçası olan ETags, uygulamaların belirli bir API kaynağının belirli bir sürümüne başvurmasına olanak tanır. Kaynak, feed'in tamamı veya feed'deki bir öğe olabilir. Bu işlev, aşağıdaki kullanım alanlarını destekler:

Önbelleğe alma ve koşullu alma: Uygulamanız, API kaynaklarını ve bunların ETag'lerini önbelleğe alabilir. Ardından, uygulamanız depolanmış bir kaynağı tekrar istediğinde bu kaynakla ilişkili ETag'i belirtir. Kaynak değiştiyse API, değiştirilen kaynağı ve kaynağın bu sürümüyle ilişkili ETag'i döndürür. Kaynak değişmemişse API, kaynağın değişmediğini belirten bir HTTP 304 yanıtı (Not Modified) döndürür. Uygulamanız, önbelleğe alınmış kaynakları bu şekilde sunarak gecikmeyi ve bant genişliği kullanımını azaltabilir.

Google API'lerinin istemci kitaplıkları, ETag'leri destekleme konusunda farklılık gösterir. Örneğin, JavaScript istemci kitaplığı, If-Match ve If-None-Match içeren izin verilen istek üstbilgileri için bir izin verilenler listesi aracılığıyla ETag'leri destekler. Beyaz liste, normal tarayıcı önbelleğe almanın gerçekleşmesine izin verir. Böylece, bir kaynağın ETag'i değişmemişse kaynak tarayıcı önbelleğinden sunulabilir. Diğer taraftan, Obj-C istemcisi ETag'leri desteklemez.
Değişikliklerin yanlışlıkla üzerine yazılmasını önleme: ETag'ler, birden fazla API istemcisinin yanlışlıkla birbirinin değişikliklerinin üzerine yazmamasını sağlar. Uygulamanız, bir kaynağı güncellerken veya silerken kaynağın ETag'ini belirtebilir. ETag, söz konusu kaynağın en son sürümüyle eşleşmezse API isteği başarısız olur.

Uygulamanızda ETag'leri kullanmanın çeşitli avantajları vardır:

API yanıtı, önbelleğe alınmış ancak değişmemiş kaynaklara yönelik isteklere daha hızlı yanıt vererek daha düşük gecikme süresi ve daha düşük bant genişliği kullanımı sağlar.
Uygulamanız, başka bir API istemcisinden yapılan kaynak değişikliklerinin üzerine yanlışlıkla yazmaz.

Google APIs Client Library for JavaScript, If-Match ve If-None-Match HTTP istek başlıklarını destekler. Böylece ETag'ler normal tarayıcı önbelleğe alma bağlamında çalışabilir.

gzip kullanma

Ayrıca gzip sıkıştırma yöntemini etkinleştirerek her API yanıtı için gereken bant genişliğini azaltabilirsiniz. Uygulamanızın API yanıtlarını açmak için ek CPU süresine ihtiyacı olsa da daha az ağ kaynağı kullanmanın avantajı genellikle bu maliyetten daha ağır basar.

gzip ile kodlanmış bir yanıt almak için iki şey yapmanız gerekir:

Accept-Encoding HTTP istek başlığını gzip olarak ayarlayın.
Kullanıcı aracınızı gzip dizesini içerecek şekilde değiştirin.

Aşağıdaki örnek HTTP üstbilgileri, gzip sıkıştırma yöntemini etkinleştirmek için gereken koşulları göstermektedir:

Accept-Encoding: gzip
User-Agent: my program (gzip)

YouTube Data API'ye Genel Bakış Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.