TV ve Sınırlı Girişli Cihaz Uygulamaları için OAuth 2.0

Bu belgede, TV, oyun konsolu ve yazıcı gibi cihazlarda çalışan uygulamalar aracılığıyla YouTube Data API'ye erişmek için OAuth 2.0 yetkilendirmesinin nasıl uygulanacağı açıklanmaktadır. Daha spesifik olarak bu akış, tarayıcıya erişimi olmayan veya sınırlı giriş özelliklerine sahip cihazlar için tasarlanmıştır.

OAuth 2.0 sayesinde kullanıcılar, bir uygulamayla belirli verileri paylaşırken kullanıcı adlarını, şifrelerini ve diğer bilgilerini gizli tutabilir. Örneğin, bir TV uygulaması Google Drive'da depolanan bir dosyayı seçme izni almak için OAuth 2.0'ı kullanabilir.

Bu akışı kullanan uygulamalar tek tek cihazlara dağıtıldığından, uygulamaların sır tutamayacağı varsayılır. Kullanıcı uygulamada bulunurken veya uygulama arka planda çalışırken Google API'lerine erişebilirler.

Alternatifler

Tarayıcıya ve tam giriş özelliklerine erişimi olan Android, iOS, macOS, Linux veya Windows gibi bir platform için uygulama yazıyorsanız (Evrensel Windows Platformu dahil) Mobil ve masaüstü uygulamaları için OAuth 2.0 akışını kullanın. (Uygulamanız grafik arayüzü olmayan bir komut satırı aracı olsa bile bu akışı kullanmanız gerekir.)

Kullanıcıların yalnızca Google Hesaplarıyla oturum açmasını ve temel kullanıcı profili bilgilerini almak için JWT kimlik jetonunu kullanmak istiyorsanız TV'lerde ve Sınırlı Giriş Cihazlarında Oturum Açma başlıklı makaleyi inceleyin.

Ön koşullar

Projeniz için API'leri etkinleştirme

Google API'lerini çağıran tüm uygulamaların bu API'leri API Console'de etkinleştirmesi gerekir.

Projenizde bir API'yi etkinleştirmek için:

1. Open the API Library in the Google API Console.
2. If prompted, select a project, or create a new one.
3. YouTube Data API'yi bulup etkinleştirmek için Kitaplık sayfasını kullanın. Uygulamanızın kullanacağı diğer API'leri bulun ve bunları da etkinleştirin.

Yetkilendirme kimlik bilgileri oluşturma

Google API'lerine erişmek için OAuth 2.0'ı kullanan tüm uygulamaların, uygulamayı Google'ın OAuth 2.0 sunucusuna tanıtan yetkilendirme kimlik bilgilerine sahip olması gerekir. Aşağıdaki adımlarda, projeniz için nasıl kimlik bilgisi oluşturacağınız açıklanmaktadır. Uygulamalarınız daha sonra bu kimlik bilgilerini kullanarak söz konusu proje için etkinleştirdiğiniz API'lere erişebilir.

1. Go to the Credentials page.
2. Create Client'ı (İstemci Oluştur) tıklayın.
3. TV'ler ve Sınırlı Giriş cihazları uygulama türünü seçin.
4. OAuth 2.0 istemcinizi adlandırın ve Oluştur'u tıklayın.

Erişim kapsamlarını belirleme

Kapsamlar, uygulamanızın yalnızca ihtiyaç duyduğu kaynaklara erişim isteğinde bulunmasını sağlar. Ayrıca, kullanıcıların uygulamanıza verdiği erişim miktarını kontrol etmesine de olanak tanır. Bu nedenle, istenen kapsam sayısı ile kullanıcı izni alma olasılığı arasında ters bir ilişki olabilir.

OAuth 2.0 yetkilendirmesini uygulamaya başlamadan önce, uygulamanızın erişim izni gerektireceği kapsamları belirlemenizi öneririz.

YouTube Data API v3 aşağıdaki kapsamları kullanır:

Yüklü uygulamalar veya cihazlar için İzin verilen kapsamlar listesine bakın.

OAuth 2.0 erişim jetonlarını edinme

Uygulamanız sınırlı giriş özelliklerine sahip bir cihazda çalışsa bile kullanıcıların bu yetkilendirme akışını tamamlamak için daha zengin giriş özelliklerine sahip bir cihaza ayrı erişimi olması gerekir. Akış aşağıdaki adımlardan oluşur:

1. Uygulamanız, Google'ın yetkilendirme sunucusuna, uygulamanızın erişim izni isteyeceği kapsamları tanımlayan bir istek gönderir.
2. Sunucu, sonraki adımlarda kullanılan çeşitli bilgilerle (ör. cihaz kodu ve kullanıcı kodu) yanıt verir.
3. Kullanıcının uygulamanızı yetkilendirmek için ayrı bir cihaza girebileceği bilgileri gösterirsiniz.
4. Uygulamanız, kullanıcının uygulamanızı yetkilendirip yetkilendirmediğini belirlemek için Google'ın yetkilendirme sunucusunu yoklamaya başlar.
5. Kullanıcı, daha zengin giriş özelliklerine sahip bir cihaza geçer, bir web tarayıcısı başlatır, 3. adımda gösterilen URL'ye gider ve 3. adımda da gösterilen kodu girer. Kullanıcı daha sonra uygulamanıza erişim izni verebilir (veya erişimi reddedebilir).
6. Yoklama isteğinize verilen bir sonraki yanıtta, uygulamanızın kullanıcı adına istekleri yetkilendirmek için ihtiyaç duyduğu jetonlar bulunur. (Kullanıcı, uygulamanıza erişimi reddettiyse yanıtta jeton bulunmaz.)

Aşağıdaki resimde bu işlem gösterilmektedir:

Bu adımlar aşağıdaki bölümlerde ayrıntılı olarak açıklanmıştır. Cihazların sahip olabileceği özellikler ve çalışma zamanı ortamları göz önüne alındığında, bu belgede gösterilen örneklerde curl komut satırı yardımcı programı kullanılır. Bu örnekler, çeşitli dillere ve çalışma zamanlarına kolayca taşınabilmelidir.

1. adım: Cihaz ve kullanıcı kodlarını isteyin

Bu adımda cihazınız, Google'ın yetkilendirme sunucusuna (https://oauth2.googleapis.com/device/code) bir HTTP POST isteği gönderir. Bu istek, uygulamanızı ve uygulamanızın kullanıcı adına erişmek istediği erişim kapsamlarını tanımlar. Bu URL'yi, device_authorization_endpoint meta veri değerini kullanarak Discovery belgesinden almanız gerekir. Aşağıdaki HTTP isteği parametrelerini ekleyin:

Örnekler

Aşağıdaki snippet'te örnek bir istek gösterilmektedir:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=https%3A%2F%2F2.zoppoz.workers.dev%3A443%2Fhttps%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly

Bu örnekte, aynı isteği göndermek için kullanılan curl komutu gösterilmektedir:

curl -d "client_id=client_id&scope=https%3A%2F%2F2.zoppoz.workers.dev%3A443%2Fhttps%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly" \
     https://oauth2.googleapis.com/device/code

2. adım: Yetkilendirme sunucusu yanıtını işleyin

Yetkilendirme sunucusu aşağıdaki yanıtlardan birini döndürür:

Başarı yanıtı

İstek geçerliyse yanıtınız aşağıdaki özellikleri içeren bir JSON nesnesi olur:

Aşağıdaki snippet'te örnek bir yanıt gösterilmektedir:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

Kota aşıldı yanıtı

Cihaz kodu istekleriniz, istemci kimliğinizle ilişkili kotayı aşarsa aşağıdaki hatayı içeren bir 403 yanıtı alırsınız:

{
  "error_code": "rate_limit_exceeded"
}

Bu durumda, istek hızını azaltmak için geri çekilme stratejisi kullanın.

3. adım: Kullanıcı kodunu gösterin

2. adımda elde edilen verification_url ve user_code değerlerini kullanıcıya gösterin. Her iki değer de US-ASCII karakter kümesindeki yazdırılabilir karakterleri içerebilir. Kullanıcıya gösterdiğiniz içerik, kullanıcıyı ayrı bir cihazda verification_url simgesine gidip user_code girmeye yönlendirmelidir.

Kullanıcı arayüzünüzü (UI) aşağıdaki kuralları göz önünde bulundurarak tasarlayın:

• user_code
  • user_code, 15 "W" boyutlu karakteri işleyebilen bir alanda gösterilmelidir. Başka bir deyişle, WWWWWWWWWWWWWWW kodunu doğru şekilde gösterebiliyorsanız kullanıcı arayüzünüz geçerlidir ve user_code öğesinin kullanıcı arayüzünüzde nasıl göründüğünü test ederken bu dize değerini kullanmanızı öneririz.
  • user_code büyük/küçük harfe duyarlıdır ve büyük/küçük harf durumunu değiştirme veya başka biçimlendirme karakterleri ekleme gibi herhangi bir şekilde değiştirilmemelidir.
• verification_url
  • verification_url öğesini gösterdiğiniz alan, 40 karakter uzunluğundaki bir URL dizesini işleyecek kadar geniş olmalıdır.
  • verification_url, isteğe bağlı olarak görüntüleme şemasını kaldırmak dışında hiçbir şekilde değiştirilmemelidir. Görüntüleme nedenleriyle URL'den şemayı (ör. https://) kaldırmayı planlıyorsanız uygulamanızın hem http hem de https varyantlarını işleyebildiğinden emin olun.

4. adım: Google'ın yetkilendirme sunucusunu yoklayın

Kullanıcı, verification_url sayfasına gitmek ve erişim izni vermek (veya erişimi reddetmek) için ayrı bir cihaz kullanacağından, kullanıcı erişim isteğine yanıt verdiğinde istekte bulunan cihaza otomatik olarak bildirim gönderilmez. Bu nedenle, kullanıcının isteğe ne zaman yanıt verdiğini belirlemek için istekte bulunan cihazın Google'ın yetkilendirme sunucusunu yoklaması gerekir.

İstekte bulunan cihaz, kullanıcının erişim isteğine yanıt verdiğini belirten bir yanıt alana veya 2. adımda elde edilen device_code ve user_code değerlerinin süresi dolana kadar yoklama istekleri göndermeye devam etmelidir. 2. adımda döndürülen interval değeri, istekler arasında beklenecek süreyi saniye cinsinden belirtir.

Yoklanacak uç noktanın URL'si https://oauth2.googleapis.com/token. Yoklama isteği aşağıdaki parametreleri içerir:

Örnekler

Aşağıdaki snippet'te örnek bir istek gösterilmektedir:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

Bu örnekte, aynı isteği göndermek için kullanılan curl komutu gösterilmektedir:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

5. adım: Kullanıcı, erişim isteğine yanıt verir

Aşağıdaki resimde, kullanıcıların 3. adımda gösterdiğiniz verification_url sayfasına gittiğinde gördüklerine benzer bir sayfa gösterilmektedir:

user_code girildikten ve henüz oturum açılmadıysa Google'da oturum açıldıktan sonra kullanıcı, aşağıda gösterilene benzer bir izin ekranı görür:

6. adım: Anket isteklerine verilen yanıtları ele alın

Google'ın yetkilendirme sunucusu, her yoklama isteğine aşağıdaki yanıtlardan biriyle yanıt verir:

Erişim izni verildi

Kullanıcı cihaza erişim izni verdiyse (izin ekranında Allow simgesini tıklayarak) yanıt, erişim jetonu ve yenileme jetonu içerir. Bu jetonlar, cihazınızın kullanıcı adına Google API'lerine erişmesini sağlar. (Yanıtın scope özelliği, cihazın hangi API'lere erişebileceğini belirler.)

Bu durumda, API yanıtında aşağıdaki alanlar bulunur:

Aşağıdaki snippet'te örnek bir yanıt gösterilmektedir:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Erişim jetonlarının kullanım ömrü sınırlıdır. Uygulamanızın uzun bir süre boyunca bir API'ye erişmesi gerekiyorsa yeni bir erişim jetonu almak için yenileme jetonunu kullanabilir. Uygulamanızın bu tür bir erişime ihtiyacı varsa yenileme jetonunu daha sonra kullanmak üzere saklaması gerekir.

Erişim reddedildi

Kullanıcı cihaza erişim izni vermeyi reddederse sunucu yanıtında 403 HTTP yanıt durum kodu (Forbidden) bulunur. Yanıtta şu hata yer alır:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Yetkilendirme bekleniyor

Kullanıcı henüz yetkilendirme akışını tamamlamadıysa sunucu 428 HTTP yanıt durum kodunu (Precondition Required) döndürür. Yanıtta şu hata bulunur:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Çok sık anket yapma

Cihaz çok sık yoklama isteği gönderirse sunucu 403 HTTP yanıt durum kodunu (Forbidden) döndürür. Yanıtta şu hata yer alır:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Diğer hatalar

Yetkilendirme sunucusu, yoklama isteğinde gerekli parametreler eksikse veya parametre değeri yanlışsa da hata döndürür. Bu istekler genellikle 400 (Bad Request) veya 401 (Unauthorized) HTTP yanıt durum koduna sahiptir. Bu hatalar şunlardır:

Google API'lerini çağırma

Uygulamanız bir erişim jetonu aldıktan sonra, API'nin gerektirdiği erişim kapsamları verilmişse jetonu kullanarak belirli bir kullanıcı hesabı adına Google API'sine çağrı yapabilirsiniz. Bunu yapmak için API'ye yapılan bir isteğe erişim jetonunu ekleyin. Bunun için access_token sorgu parametresini veya Authorization HTTP üstbilgisi Bearer değerini ekleyebilirsiniz. Sorgu dizeleri sunucu günlüklerinde görünür olduğundan mümkün olduğunda HTTP üstbilgisi tercih edilir. Çoğu durumda, Google API'lerine yönelik çağrılarınızı ayarlamak için bir istemci kitaplığı kullanabilirsiniz (örneğin, YouTube Data API'yi çağırırken).

YouTube Data API'nin yalnızca plak şirketleri ve film stüdyoları gibi birden fazla YouTube kanalına sahip olan ve bu kanalları yöneten YouTube içerik sahipleri için hizmet hesaplarını desteklediğini unutmayın.

Tüm Google API'lerini deneyebilir ve kapsamlarını OAuth 2.0 Playground'da görüntüleyebilirsiniz.

HTTP GET örnekleri

Authorization: Bearer HTTP üstbilgisi kullanılarak youtube.channels uç noktasına (YouTube Data API) yapılan bir çağrı aşağıdaki gibi görünebilir. Kendi erişim jetonunuzu belirtmeniz gerektiğini unutmayın:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Aşağıda, access_token sorgu dizesi parametresi kullanılarak kimliği doğrulanmış kullanıcı için aynı API'ye yapılan bir çağrı verilmiştir:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl örnek

Bu komutları curl komut satırı uygulamasıyla test edebilirsiniz. HTTP üstbilgisi seçeneğinin (tercih edilen) kullanıldığı bir örneği aşağıda bulabilirsiniz:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Alternatif olarak sorgu dizesi parametresi seçeneğini de kullanabilirsiniz:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Erişim jetonunu yenileme

Erişim jetonlarının süresi düzenli olarak dolar ve ilgili API isteği için geçersiz kimlik bilgileri haline gelir. Jetonla ilişkili kapsamlar için çevrimdışı erişim isteğinde bulunduysanız kullanıcıdan izin istemeden (kullanıcı mevcut değilken de dahil olmak üzere) erişim jetonunu yenileyebilirsiniz.

Erişim jetonunu yenilemek için uygulamanız, Google'ın yetkilendirme sunucusuna (https://oauth2.googleapis.com/token) aşağıdaki parametreleri içeren bir HTTPS POST isteği gönderir:

Aşağıdaki snippet'te örnek bir istek gösterilmektedir:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Kullanıcı, uygulamaya verilen erişimi iptal etmediği sürece jeton sunucusu yeni bir erişim jetonu içeren bir JSON nesnesi döndürür. Aşağıdaki snippet'te örnek bir yanıt gösterilmektedir:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Yenileme jetonlarının sayısıyla ilgili sınırlamalar olduğunu unutmayın. Bir sınırlama, istemci/kullanıcı kombinasyonu başına, diğeri ise tüm istemcilerdeki kullanıcı başına uygulanır. Yenileme jetonlarını uzun süreli depolama alanına kaydetmeli ve geçerli oldukları sürece kullanmaya devam etmelisiniz. Uygulamanız çok fazla yenileme jetonu isterse bu sınırlara takılabilir. Bu durumda eski yenileme jetonları çalışmayı durdurur.

Jeton iptali

Bazı durumlarda kullanıcılar, bir uygulamaya verilen erişimi iptal etmek isteyebilir. Kullanıcı, Hesap Ayarları'nı ziyaret ederek erişimi iptal edebilir. Daha fazla bilgi için Hesabınıza erişimi olan üçüncü taraf site ve uygulamalar başlıklı destek belgesinin Site veya uygulama erişimini kaldırma bölümüne bakın.

Bir uygulamanın, kendisine verilen erişimi programatik olarak iptal etmesi de mümkündür. Kullanıcının e-posta listesinden çıktığı, bir uygulamayı kaldırdığı veya bir uygulamanın ihtiyaç duyduğu API kaynaklarının önemli ölçüde değiştiği durumlarda programatik iptal önemlidir. Diğer bir deyişle, kaldırma işleminin bir parçası olarak, daha önce uygulamaya verilen izinlerin kaldırıldığından emin olmak için bir API isteği gönderilebilir.

Bir jetonu programatik olarak iptal etmek için uygulamanız https://oauth2.googleapis.com/revoke adresine bir istek gönderir ve jetonu parametre olarak ekler:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Jeton, erişim jetonu veya yenileme jetonu olabilir. Jeton bir erişim jetonuysa ve karşılık gelen bir yenileme jetonu varsa yenileme jetonu da iptal edilir.

İptal işlemi başarıyla işlenirse yanıtın HTTP durum kodu 200 olur. Hata durumlarında, hata koduyla birlikte bir HTTP durum kodu 400 döndürülür.

İzin verilen kapsamlar

Cihazlar için OAuth 2.0 akışı yalnızca aşağıdaki kapsamlar için desteklenir:

Zamana dayalı erişim

Zamana dayalı erişim, kullanıcının bir işlemi tamamlamak için sınırlı bir süre boyunca uygulamanıza verilerine erişim izni vermesine olanak tanır. İzin verme akışı sırasında belirli Google ürünlerinde kullanılabilen zamana dayalı erişim, kullanıcılara sınırlı bir süre için erişim izni verme seçeneği sunar. Örneğin, Data Portability API, tek seferlik veri aktarımına olanak tanır.

Kullanıcı, uygulamanıza zamana dayalı erişim izni verdiğinde yenileme jetonunun süresi belirtilen süre sonunda dolar. Yenileme jetonlarının belirli durumlarda daha erken geçersiz kılınabileceğini unutmayın. Ayrıntılar için bu durumlara bakın. Yetkilendirme kodu değiştirme yanıtında döndürülen refresh_token_expires_in alanı, bu gibi durumlarda yenileme jetonunun süresinin dolmasına kadar kalan süreyi gösterir.