YouTube Data API'ye Genel Bakış

Giriş

Bu doküman, YouTube ile etkileşime giren uygulamalar yazmak isteyen geliştiriciler için hazırlanmıştır. Burada YouTube ve API ile ilgili temel kavramlar açıklanmaktadır. Ayrıca, API'nin desteklediği farklı işlevlere genel bir bakış da sunulur.

Başlamadan önce

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

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

  3. Projenizi oluşturduktan sonra, YouTube Data API'nin uygulamanızın kullanmak üzere kaydettirildiğ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'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 - JavaScript Object Notation) veri biçimiyle ilgili temel kavramlar hakkında bilgi edinin. JSON, rastgele veri yapılarının basit metin temsilini sağlayan yaygın, 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'yı 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. Videoya oy verme, video paylaşma, videoyu favori olarak işaretleme ve kanal bülteni yayınlama gibi etkinlikler, etkinlik feed'lerinde raporlanan kullanıcı işlemleri arasındadı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 Kanalın öne çıkarmayı seçtiği bir grup videoyla ilgili bilgileri içerir. Örneğin, bir bölümde kanalın en son yüklemeleri, en popüler yüklemeleri ya da bir veya daha fazla oynatma listesindeki videolar öne çıkarılabilir.
guideCategory İçeriklerine veya popülerlik gibi diğer göstergelere dayanarak YouTube'un kanallarla ilişkilendirdiği bir kategori belirtir. Rehber kategorileri, kanalları YouTube kullanıcılarının aradıkları içeriği bulmasını kolaylaştıracak şekilde düzenlemeyi amaçlar. Kanallar bir veya daha fazla rehber kategorisiyle ilişkilendirilebilse de herhangi bir rehber kategorisinde olmaları 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ılarının tercih edilen içerik bölgesi olarak seçebileceği bir 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 görüntülenebilen ve diğer kullanıcılarla paylaşılabilen bir video koleksiyonudur.
playlistItem Oynatma listesinin parçası olan video gibi bir kaynağı 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 bir YouTube videosu, kanalı veya oynatma listesi hakkında bilgi içerir. Bir arama sonucu, video gibi benzersiz bir şekilde tanımlanabilir bir kaynağı işaret etse de kendine ait kalıcı verileri yoktur.
subscription YouTube kullanıcı aboneliği hakkında bilgiler içerir. Abonelik, kanala yeni videolar eklendiğinde veya başka bir kullanıcı YouTube'da video yükleme, videoyu derecelendirme ya da video hakkında yorum yapma gibi çeşitli işlemlerden birini gerçekleştirdiğinde kullanıcıyı bilgilendirir.
thumbnail Bir kaynakla ilişkili küçük resimleri tanımlar.
video Tek bir YouTube videosunu temsil eder.
videoCategory Yüklenmiş videolarla ilişkili olan veya olabilecek kategorileri tanımlar.
watermark Belirtilen kanalın videoları oynatılırken gösterilen görüntüyü tanımlar. Kanal sahibi, filigranın video oynatma sırasında ne zaman görüneceğini ve daha sonra ne kadar süre boyunca görüneceğini belirleyen zamanlama ayrıntılarının yanı sıra resmin bağlandığı bir hedef kanal da belirleyebilir.

Çoğu durumda, bir kaynağın diğer kaynaklara referanslar içerdiğini unutmayın. Örneğin, playlistItem kaynağının snippet.resourceId.videoId özelliği, video hakkında tüm bilgileri içeren video kaynağını tanımlar. Başka bir örnek olarak, bir arama sonucu belirli bir videoyu, oynatma listesini veya kanal kaynağını tanımlayan bir videoId, playlistId veya 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 diğer yöntemleri de desteklemektedir. Örneğin, videos.rate yöntemi bir kullanıcı derecelendirmesini videoyla ilişkilendirirken thumbnails.set yöntemi, YouTube'a bir video küçük resmi yükler ve bunu 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 Mevcut 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. Ayrıca, birçok kaynak için yazma işlemlerini de destekler.

Aşağıdaki tabloda, farklı kaynak türleri için desteklenen işlemler tanımlanmaktadır. Kaynakları ekleyen, güncelleyen veya silen işlemler her zaman kullanıcı yetkilendirmesi gerektirir. Bazı durumlarda, list yöntemleri hem yetkili hem de yetkisiz istekleri destekler. Yetkilendirilmiş istekler, kimliği doğrulanmış kullanıcı hakkında veya ona özel bilgileri de alırken, yetkisiz isteklerin yalnızca herkese açık verileri aldığı durumlarda.

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 kullanmalarını sağlamak ve hizmet kalitesini adil olmayan bir şekilde azaltan veya başkalarının erişimini sınırlandıran uygulamalar oluşturmamak için bir kota kullanır. Geçersiz istekler dahil olmak üzere tüm API istekleri, en az bir puanlık kota maliyetine tabidir. Uygulamanız için geçerli olan kotayı API Console sayfasında bulabilirsiniz.

YouTube Data API'nin etkinleştirildiği projelerde,varsayılan kota tahsisi günde 10.000 birimdir. Bu, 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ı ş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 ile ilgili Kota uzantısı istek formunu doldurarak ek kota isteyebilirsiniz.

Kota kullanımını hesaplama

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

  • Kaynakların listesini (kanallar, videolar, oynatma listeleri) alan okuma işleminin maliyeti genellikle 1 birimdir.
  • Bir kaynağı oluşturan, güncelleyen veya silen yazma işleminin maliyeti genellikle 50 birimdir.
  • Bir arama isteğinin maliyeti 100 birimdir.
  • Bir video yüklemesinin maliyeti 1600 birimdir.

API istekleri için kota maliyetleri tablosunda her API yönteminin kota maliyeti gösterilir. Bu kuralları göz önünde bulundurarak, kotanızı aşmadan uygulamanızın günlük olarak 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, ancak bunu gerektirir. Bu yaklaşım aynı zamanda API'nin ağ, CPU ve bellek kaynaklarını daha verimli kullanmasını da sağlar.

API, aşağıdaki bölümlerde açıklanan iki istek parametresini destekler. Bu parametreler, API yanıtlarına eklenmesi gereken kaynak özelliklerini tanımlamanızı sağlar.

  • 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 kaynak alan veya döndüren tüm API istekleri için zorunlu bir parametredir. Parametre, API yanıtına eklenmesi gereken bir veya daha fazla üst düzey (iç içe yerleştirilmiş) kaynak özelliğini tanımlar. Örneğin, bir video kaynağı aşağıdaki parçalardan oluşur:

  • 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 ve 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 şartın iki temel amacı vardır:

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

Kaynaklar zamanla daha fazla parça ekledikçe bu avantajlar sadece uygulamanız desteklemediği yeni özellikleri istemeyeceğinden artacaktır.

fields parametresi nasıl kullanılır?

fields parametresi, yalnızca part parametre değerinde tanımlanan kaynak parçalarını içeren API yanıtını filtreleyerek yanıtın yalnızca belirli bir alan grubunu içermesini sağlar. 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 fields parametre değeri için desteklenen söz dizimi, XPath söz dizimine dayalı olarak genel olarak 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şaretini (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ş mülkleri belirtmek için düz eğik çizgi (fields=a/b) kullanın.

Pratikte bu kurallar genellikle birkaç farklı fields parametre değerinin aynı API yanıtını almasına izin verir. Örneğin, bir oynatma listesindeki her öğe için oynatma listesi öğe kimliği, başlık 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. Daha kolay okunabilirlik için bu belgedeki örneklerde kodlama kullanılmamaktadı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, kind ve etag özelliklerinin yanı sıra dört bölümden oluşan 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 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, özet akışının tamamı veya o feed'de bulunan 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 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ınan kaynakları bu şekilde sunarak gecikmeyi ve bant genişliği kullanımını azaltabilir.

    Google API'lerinin istemci kitaplıkları, ETag'leri destekleme açısından 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 beyaz liste aracılığıyla ETag'leri destekler. Beyaz liste, tarayıcı önbelleğine normal şekilde alınmasını sağlar. Böylece, kaynağın ETag'i değişmediyse kaynak, tarayıcı önbelleğinden sunulabilir. Öte 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 birbirinin değişikliklerinin üzerine 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ş kaynak isteklerine daha hızlı yanıt vererek gecikmenin azalmasını ve bant genişliği kullanımını azaltır.
  • Uygulamanız, başka bir API istemcisinden bir kaynakta yapılan değişikliklerin üzerine yanlışlıkla yazmaz.

Google APIs Client Library for JavaScript, If-Match ve If-None-Match HTTP istek başlıklarını desteklediğinden 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 API yanıtlarının sıkıştırmasını açmak için ek CPU zamanı gerektirse de daha az ağ kaynağı tüketmenin faydası genellikle bu maliyetten daha ağır basar.

gzip kodlamalı 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österir:

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