YouTube Data API'ye Genel Bakış

Giriş

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

Başlamadan önce

  1. Google API Konsolu'na erişmek, API anahtarı istemek ve uygulamanızı kaydetmek için Google Hesabı'na ihtiyacınız vardır.

  2. Google Developers Console'da bir proje oluşturun ve uygulamanızın API istekleri gönderebilmesi için yetkilendirme kimlik bilgileri edinin.

  3. Projenizi oluşturduktan sonra, YouTube Data API'nin uygulamanızın kullanmak üzere kaydedildiği hizmetlerden biri olduğundan emin olun:

    1. API Konsolu'na gidin ve yeni kaydettiğiniz projeyi seçin.
    2. Etkin API'ler sayfasını ziyaret edin. API listesinde, YouTube Data API v3'ün durumunun AÇIK olduğundan emin olun.

  4. 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.

  5. API uygulamanızı basitleştirmek için bir müşteri kitaplığı seçin.

  6. JSON (JavaScript Object Notation) veri biçiminin temel kavramlarını öğrenin. 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ıya sahip bağımsız bir veri öğesidir. Aşağıdaki tabloda, API'yi kullanarak etkileşimde bulunabileceğ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 akışlarında bildirilen kullanıcı işlemleri arasında videolara puan verme, video paylaşma, videoları favorilere ekleme 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 video hakkında bilgi 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, kanalları YouTube kullanıcılarının aradıkları içeriği daha kolay bulabilecekleri şekilde düzenlemeyi amaçlar. Kanallar bir veya daha fazla rehber kategorisiyle ilişkilendirilebilir ancak herhangi bir rehber kategorisinde yer alacağı 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 Bir 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ğı, eklenen kaynağın oynatma listesinde nasıl kullanıldığını açıklayan ayrıntıları da içerir.
search result Bir YouTube videosu, kanalı veya oynatma listesi hakkında, API isteğinde belirtilen arama parametreleriyle eşleşen bilgileri içerir. Arama sonucu, video gibi benzersiz şekilde tanımlanabilir bir kaynağa işaret etse de kendi kalıcı verileri yoktur.
subscription YouTube kullanıcı aboneliğiyle ilgili bilgiler içerir. Abonelik, bir kanala yeni videolar eklendiğinde veya başka bir kullanıcı YouTube'da video yükleme, videoyu 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ının oynatılması sırasında 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 referans içerdiğini unutmayın. Örneğin, bir playlistItem kaynağı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 yerine getiren başka yöntemleri de destekler. Örneğin, videos.rate yöntemi, kullanıcı derecelendirmesini bir videoyla ilişkilendirir. thumbnails.set yöntemi ise video küçük resmi yükleyip bir videoyla ilişkilendirir.

İşlemler
list Sıfır veya daha fazla kaynağın listesini (GET) alır.
insert Yeni bir kaynak oluşturur (POST).
update İsteğinizdeki verileri yansıtmak için mevcut bir kaynağı (PUT) değiştirir.
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 tanımlanmaktadır. 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ının özel bilgilerini 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 projeler için varsayılan kota tahsisi günlük 10.000 birimdir. Bu miktar, API kullanıcılarımızın büyük çoğunluğu için yeterlidir. Değişkenlik gösterebilen 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:

  • Kaynak listesini (kanallar, videolar, oynatma listeleri) alan bir okuma işlemi genellikle 1 birim maliyetlidir.
  • Bir kaynağı oluşturan, güncelleyen veya silen bir yazma işlemi genellikle 50 birim tutar.
  • Bir arama isteğinin maliyeti 100 birimdir.
  • Video yükleme işlemi 100 birime mal olur.

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 aslında 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 belirlemenizi sağlayan ve aşağıdaki bölümlerde açıklanan iki istek parametresini destekler.

  • 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 parametresi nasıl kullanılır?

part parametresi, bir kaynağı alan veya döndüren tüm API istekleri için zorunlu bir parametredir. Parametre, bir 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ümlere sahiptir:

  • 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 alamayabileceği) meta veri alanları grupları olarak düşünebilirsiniz. Bu nedenle, part parametresi, uygulamanızın gerçekten kullandığı kaynak bileşenlerini seçmenizi gerektirir. Bu koşul iki temel amaca hizmet eder:

  • 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 bu avantajlar artacaktır. Çünkü uygulamanız, desteklemediği yeni kullanıma sunulan özellikleri istemeyecektir.

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 bir 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, iç içe yerleştirilmiş mülkleri yanıttan filtrelemek için kullanılamaz.)

Aşağıdaki kurallar, XPath söz dizimine dayalı olan fields parametre değeri için desteklenen söz dizimini açıklar:

  • 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 işareti (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.

Bu kurallar, pratikte aynı API yanıtını almak için genellikle birkaç farklı fields parametre değerine izin verir. Ö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. 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. 2. örnek, iki bölümün yanı sıra kind ve etag özelliklerini içeren bir video kaynağı döndürür.
  3. 3. örnek, iki bölüm içeren ancak kind ve etag özelliklerini içermeyen bir video kaynağı döndürür.
  4. 4. örnek, iki bölüm içeren bir video kaynağı döndürür ancak kind ve etag ile kaynağın snippet nesnesindeki bazı iç içe yerleştirilmiş özellikler hariç tutulur.
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ştirilmiş kaynağı ve kaynağın bu sürümüyle ilişkili ETag'i döndürür. Kaynak değişmediyse 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 beyaz liste 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 birbirinin değişikliklerinin üzerine yanlışlıkla yazmasını önlemeye yardımcı olur. 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, önbelleğe alınmış ancak değiştirilmemiş 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'lerin normal tarayıcı önbelleğe alma bağlamında çalışmasını sağlar.

gzip kullanma

Gzip sıkıştırmayı etkinleştirerek her API yanıtı için gereken bant genişliğini de 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 fazladır.

Gzip ile kodlanmış bir yanıt almak için iki işlem 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ırmanın etkinleştirilmesiyle ilgili bu şartları gösterir:

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