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 mevcutken veya uygulama arka planda çalışırken Google API'lerine erişebilirler.

Alternatifler

Tarayıcıya erişimi ve tam giriş yetenekleri olan Android, iOS, macOS, Linux veya Windows (Evrensel Windows Platformu dahil) gibi bir platform için uygulama yazıyorsanız, 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.)

Eğer sizsadece Kullanıcıların Google hesaplarıyla oturum açmalarını ve kullanmalarını istiyoruz.JWT Temel kullanıcı profili bilgilerini almak için kullanılan kimlik belirteci (ID token) hakkında daha fazla bilgi için bakınız.Televizyonlarda ve Sınırlı Girişli Cihazlarda Oturum Açma .

Ön koşullar

Projeniz için API'leri etkinleştirin.

Google API'lerini çağıran herhangi bir uygulamanın, bu API'leri API Consoleiçinde etkinleştirmesi gerekir.

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

1. Open the API Library içinde Google API Console.
2. If prompted, select a project, or create a new one.
3. YouTube Veri API'sini bulmak ve etkinleştirmek için Kütüphane sayfasını kullanın. Uygulamanızın kullanacağı diğer API'leri de bulun ve onları da etkinleştirin.

Yetkilendirme kimlik bilgileri oluşturma

Google API'lerine erişmek için OAuth 2.0'ı kullanan tüm uygulamalarda, uygulamayı Google'ın OAuth 2.0 sunucusuna tanıtan yetkilendirme kimlik bilgileri olmalıdır. Aşağıdaki adımlarda, projeniz için kimlik bilgilerinin nasıl oluşturulacağı 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 Clients page.
2. İstemci Oluştur'u tıklayın.
3. TV'ler ve Sınırlı Girişli Cihazlar uygulama türünü seçin.
4. OAuth 2.0 istemcinize bir ad verin ve Oluştur'e 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 yine 3. adımda gösterilen kodu girer. Kullanıcı daha sonra uygulamanıza erişim izni verebilir (veya erişimi reddedebilir).
6. Anket isteğinize verilen bir sonraki yanıtta, uygulamanızın kullanıcı adına istekleri yetkilendirmek için ihtiyaç duyduğu jetonlar yer alır. (Kullanıcı, uygulamanıza erişimi reddettiyse yanıtta jeton bulunmaz.)

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

Aşağıdaki bölümlerde bu adımlar ayrıntılı olarak açıklanmaktadır. Cihazların sahip olabileceği yetenekler ve çalışma ortamlarının çeşitliliği göz önüne alındığında, bu belgede gösterilen örnekler curl komut satırı yardımcı programını kullanmaktadır. Bu örneklerin çeşitli dillere ve çalışma ortamlarına kolayca uyarlanabilmesi gerekir.

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

Bu adımda, cihazınız Google'ın yetkilendirme sunucusuna (https://oauth2.googleapis.com/device/code adresine) uygulamanızı ve uygulamanızın kullanıcı adına erişmek istediği erişim kapsamlarını belirten bir HTTP POST isteği gönderir. Bu URL'yi, device_authorization_endpoint meta veri değerini kullanarak Discovery belgesinden almanız gerekir. Lütfen aşağıdaki HTTP istek 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%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

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%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

Adım 2: Yetkilendirme sunucusunun yanıtını işleyin

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

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 kodunu 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 simgesini gösterdiğiniz alan, 40 karakter uzunluğundaki bir URL dizesini işleyecek kadar geniş olmalıdır.
  • verification_url öğesini, isteğe bağlı olarak şemayı kaldırmak dışında hiçbir şekilde değiştirmemelisiniz. 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ğerleri sona erene kadar yoklama istekleri göndermeye devam etmelidir. 2. adımda döndürülen interval, istekler arasında beklenecek süreyi saniye cinsinden belirtir.

Yoklama yapılacak 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 girdikten ve henüz oturum açılmadıysa Google'da oturum açtı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'yı tıklayarak) yanıt, erişim jetonu ve yenileme jetonu içerir. Jetonlar, cihazınızın kullanıcı adına Google API'lerine erişmesini sağlar. (Yanıttaki 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 bir 428 HTTP yanıt durum kodu (Precondition Required) döndürür. Yanıtta şu hata bulunur:

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

Çok sık yoklama yapma

Cihaz, yoklama isteklerini çok sık 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 access_token sorgu parametresi veya Authorization HTTP üstbilgisi Bearer değeri ekleyerek API'ye yapılan bir isteğe erişim jetonunu dahil edin. 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 yaptığınız çağrıları ayarlamak için bir istemci kitaplığı kullanabilirsiniz (ör. YouTube Live Streaming API'yi çağırırken).

YouTube Canlı Yayın API'sinin hizmet hesabı akışını desteklemediğini unutmayın. Hizmet hesabı ile YouTube hesabı arasında bağlantı oluşturmanın bir yolu olmadığından, bu akışla istekleri yetkilendirme girişimleri NoLinkedYouTubeAccount hatası oluşturur.

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

HTTP GET örnekleri

Authorization: Bearer HTTP üst bilgisi kullanılarak liveBroadcasts.list uç noktasına (YouTube Live Streaming 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/liveBroadcasts?part=id%2Csnippet&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/liveBroadcasts?access_token=access_token&part=id%2Csnippet&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/liveBroadcasts?part=id%2Csnippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&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) 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&
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 https://www.googleapis.com/auth/calendar.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ılar 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 sürecinin bir parçası olarak, uygulamaya daha önce 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 koşulları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 desteklenmektedir:

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ızın verilerine erişmesine izin vermesini sağlar. İ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, verilerin tek seferlik aktarılması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.