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
-
Google API Konsolu'na erişmek, bir API anahtarı istemek ve uygulamanızı kaydetmek için bir Google Hesabınız olmalıdır.
-
Uygulamanızın API istekleri gönderebilmesi için Google Developers Console'da bir proje oluşturun ve yetkilendirme kimlik bilgilerini edinin.
-
Projenizi oluşturduktan sonra, YouTube Data API'nin uygulamanızın kullanmak üzere kaydettirildiği hizmetlerden biri olduğundan emin olun:
- API Konsolu'na gidin ve yeni kaydettiğiniz projeyi seçin.
- Etkin API'ler sayfasını ziyaret edin. API'ler listesinde, YouTube Data API v3 için durumun AÇIK olduğundan emin olun.
-
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 müşteri kitaplığı seçin.
-
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. örnek,
kind
veetag
özelliklerinin yanı sıra dört bölümden oluşan bir video kaynağı döndürür. - 2. örnek,
kind
veetag
özelliklerinin yanı sıra iki bölüm içeren bir video kaynağı döndürür. - 3. Örnek, iki bölüm içeren ancak
kind
veetag
özelliklerini hariç tutan bir video kaynağı döndürür. - 4. Örnek, iki bölüm içeren ancak
kind
veetag
öğelerinin yanı sıra kaynağınsnippet
nesnesindeki bazı iç içe yerleştirilmiş özellikleri hariç tutan bir video kaynağı döndürür.
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status Description: This example retrieves avideo
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" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics Description: This example modifies thepart
parameter value so that thecontentDetails
andstatus
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" } } ] }
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 thefields
parameter to remove allkind
andetag
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" } } ] }
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 thefields
parameter from example 3 so that in the API response, each video resource'ssnippet
object only includes thechannelId
,title
, andcategoryId
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
veIf-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)