YouTube Data API'ye Genel Bakış

Giriş

Bu doküman, YouTube ile etkileşim kuran uygulamalar yazmak isteyen geliştiricilere yöneliktir. YouTube ve API'nin temel kavramlarını açıklar. Ayrıca, API'nin desteklediği farklı işlevlere dair genel bir bakış da sunar.

Başlamadan önce

  1. Google API Konsolu'na erişmek, API anahtarı istemek ve uygulamanızı kaydetmek için bir Google Hesabınız olmalıdı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 az önce kaydettiğiniz projeyi seçin.
    2. Etkin API'ler sayfasını ziyaret edin. API'ler listesinde YouTube Data API v3 için durumun 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 - JSON) veri biçiminin temel kavramlarını öğrenin. JSON, rastgele veri yapılarının basit metin temsilini sağlayan, 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 bir tanımlayıcıya sahip bağımsız bir veri varlığıdır. 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 bir işlemle ilgili bilgileri içerir. Etkinlik feed'lerinde bildirilen kullanıcı işlemleri arasında video derecelendirme, video paylaşma, videoyu favori olarak işaretleme ve kanal bülteni yayınlama bulunur.
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 Kanalın öne çıkarmayı seçtiği bir video grubuyla ilgili bilgileri içerir. Örneğin, bir bölümde kanalın son yüklemeleri, en popüler yüklemeleri veya bir ya da daha fazla oynatma listesindeki videoları öne çıkarabilirsiniz.
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 bulmalarını kolaylaştıracak şekilde düzenlemeyi amaçlar. Kanallar bir veya daha fazla rehber kategorisiyle ilişkilendirilebilse de 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 bir coğrafi alanı belirtir. İçerik bölgesi, içerik yerel ayarı olarak da adlandırılabilir.
playlist Tek bir YouTube oynatma listesini temsil eder. Oynatma listesi, sırayla görüntülenebilen ve diğer kullanıcılarla paylaşılabilen bir video koleksiyonudur.
playlistItem Oynatma listesinde yer alan bir kaynağı (ör. video) tanımlar. listItem kaynağı, dahil edilen kaynağın oynatma listesinde nasıl kullanıldığını açıklayan ayrıntıları da içerir.
search result API isteğinde belirtilen arama parametreleriyle eşleşen YouTube videosu, kanalı veya oynatma listesi hakkında bilgiler içerir. Arama sonucu, video gibi benzersiz şekilde tanımlanabilir bir kaynağı 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, videoyu derecelendirme ya da videoya yorum yapma gibi çeşitli işlemlerden birini gerçekleştirdiğinde kullanıcıyı bilgilendirir.
thumbnail Bir kaynakla ilişkili küçük resim resimlerini tanımlar.
video Tek bir YouTube videosunu temsil eder.
videoCategory Yüklenen videolarla ilişkili olan veya olabilecek bir kategoriyi tanımlar.
watermark Belirli bir kanalın videoları oynatılırken gösterilen resmi tanımlar. Kanal sahibi ayrıca resmin bağlanacağı hedef kanalı ve filigranın video oynatmaları sırasında ne zaman görüneceğini ve ardından ne kadar süreyle görüneceğini 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 bilgi içeren bir video kaynağını tanımlar. Başka bir örnek olarak, arama sonucu belirli bir videoyu, oynatma listesini 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 daha özel işlevleri gerçekleştiren diğer yöntemleri de destekler. Örneğin, videos.rate yöntemi bir kullanıcı puanını bir videoyla ilişkilendirirken thumbnails.set yöntemi de YouTube'a bir video küçük resmi yükler ve bunu bir videoyla ilişkilendirir.

İşlemler
list Sıfır veya daha fazla kaynağın listesini alır (GET).
insert Yeni bir kaynak oluşturur (POST).
update Mevcut bir kaynağı isteğinizdeki verileri yansıtacak şekilde değiştirir (PUT).
delete Belirli bir kaynağı kaldırır (DELETE).

API şu anda desteklenen kaynak türlerinin her birini listeleme yöntemlerini desteklemektedir ve birçok kaynak için yazma işlemlerini de destekler.

Aşağıdaki tabloda, farklı kaynak türleri için desteklenen işlemler tanımlanmıştı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 de kimliği doğrulanmış kullanıcı hakkında veya bu kullanıcıya özel bilgi alabilir.

Desteklenen İş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 adil olmayan bir şekilde düşüren veya başkalarının erişimini sınırlandıran uygulamalar oluşturmamasını sağlamak için bir kota kullanır. Geçersiz istekler dahil tüm API istekleri, en az bir noktalı kota maliyetine tabidir. Uygulamanızın kullanabileceği kotayı API Console içinde bulabilirsiniz.

YouTube Data API'nin etkinleştirildiği projeler için varsayılan olarak günde 10.000 birimlik bir kota tahsis edilir. Bu miktar, API kullanıcılarımızın büyük çoğunluğu için yeterlidir. Değişime 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 şu tarihe kadar ek kota isteyebilirsiniz: Kota uzantısı talep formunu doldurun.

Kota kullanımını hesaplama

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

  • Genellikle kanallar, videolar, oynatma listeleri gibi kaynakların listesini alan bir okuma işlemidir. maliyeti 1 birimdir.
  • Bir kaynağı oluşturan, güncelleyen veya silen yazma işleminin genellikle maliyeti olur 50 birim.
  • Bir arama isteğinin maliyeti 100 birimdir.
  • Bir video yüklemesinin maliyeti 1600 birim.

API istekleri için kota maliyetleri tablosunda, kota maliyetidir. Bu kuralları göz önünde bulundurarak istek sayısını tahmin edebilirsiniz. günlük gönderebileceği bazı ek bilgiler bulabilirsiniz.

Kısmi kaynaklar

API, uygulamaların gereksiz verilerin aktarılmasından, ayrıştırılmasını ve depolanmasını önlemek için kısmi kaynakların alınmasını sağlar ve aslında bunu gerektirir. Bu yaklaşım ayrıca API'nin ağ, CPU ve bellek kaynaklarını daha verimli kullanmasını sağlar.

API, aşağıdaki bölümlerde açıklanan ve API yanıtlarına dahil edilmesi gereken kaynak özelliklerini tanımlamanızı sağlayan 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 API istekleri için gerekli 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ümlere sahiptir:

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

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

  • API sunucusunun uygulamanızın kullanmadığı meta veri alanlarını almaya 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.

Zamanla kaynaklar daha fazla parça ekledikçe bu avantajların artmasının nedeni, uygulamanızın desteklemediği yeni kullanıma sunulan mülkleri istememesidir.

fields parametresi nasıl kullanılır?

fields parametresi, yalnızca part parametre değerinde tanımlanan kaynak bölümlerini içeren API yanıtını filtreler. 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, bir yanıttaki iç içe yerleştirilmiş özellikleri filtrelemek için kullanılamaz.)

Aşağıdaki kurallarda, XPath söz dizimine genel olarak dayalı olarak fields parametre değeri için desteklenen söz dizimi açıklanmaktadır:

  • Birden çok 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ş özellik 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.

Pratikte bu kurallar genellikle aynı API yanıtını almak için birkaç farklı fields parametre değerinin kullanılmasına izin verir. Örneğin, oynatma listesindeki her öğe için oynatma listesi öğe 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 kodlamalı olmalıdır. Okunabilirliği artırmak için bu belgedeki örneklerde kodlamaya yer verilmemiştir.

Örnek kısmi talepler

Aşağıdaki örnekler, API yanıtlarının yalnızca uygulamanızın kullandığı verileri içerdiğinden emin olmak için part ve fields parametrelerini nasıl kullanabileceğinizi göstermektedir:

  1. 1. Örnek, kind ve etag özelliklerinin yanı sıra dört bölüm içeren bir video kaynağı döndürür.
  2. 2. Örnek, kind ve etag özelliklerinin yanı sıra iki bölüm içeren bir video kaynağı döndürür.
  3. 3. Örnek, iki bölüm içeren ancak kind ve etag özelliklerini hariç tutan bir video kaynağı döndürür.
  4. 4. Örnek, iki bölüm içeren ancak kind ve etag öğelerinin yanı sıra kaynağın snippet nesnesindeki iç içe yerleştirilmiş bazı özellikleri hariç tutan bir video kaynağı döndürür.
ziyaret edin.
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 bu 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 depolanan bir kaynağı tekrar istediğinde, bu kaynakla ilişkili ETag'i belirtir. Kaynak değiştiyse API, değiştirilen kaynağı ve kaynağın 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ınan kaynakları bu şekilde sunarak gecikmeyi ve bant genişliği kullanımını azaltabilir.

    Google API'lerinin istemci kitaplıkları, ETag desteği açısından farklılık gösterir. Örneğin, JavaScript istemci kitaplığı, If-Match ve If-None-Match öğelerini içeren izin verilen istek başlıkları için bir beyaz liste üzerinden ETag'leri destekler. Beyaz liste, bir kaynağın ETag'i değişmediğinde kaynağın, tarayıcı önbelleğinden sunulabilmesi için normal tarayıcı önbelleğine izin verilir. Diğer yandan, Obj-C istemcisi ETag'leri desteklemez.

  • Değişikliklerin yanlışlıkla üzerine yazılmasına karşı koruma: ETag'ler, birden fazla API istemcisinin yanlışlıkla birbirlerindeki değişikliklerin üzerine yazmamasını sağlar. Uygulamanız, bir kaynağı günceller 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 kullanmak çeşitli avantajlar sağlar:

  • API, önbelleğe alınan ancak değiştirilmeyen kaynaklar için yapılan 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, yanlışlıkla başka bir API istemcisinden kaynak üzerinde yapılan değişikliklerin üzerine 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ği bağlamında çalışmasını sağlar.

Gzip'i kullanma

Ayrıca, gzip sıkıştırmasını 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ı olacak olsa da daha az ağ kaynağı tüketmenin avantajı, genellikle bu maliyetten daha ağır basar.

gzip kodlu 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ırmasını etkinleştirmek için şu gereksinimleri göstermektedir:

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