Temel Hazırlık API'sı - Yetkilendirme

Bu kılavuzda, bir uygulamanın Temel Hazırlık API'sına yapılan istekleri nasıl yetkilendirdiği açıklanmaktadır.

İstekleri Yetkilendirme

Kullanıcıların Google Analytics web sitesinde hesap bilgilerini görüntüleyebilmeleri için önce Google Hesaplarına giriş yapmaları gerekir. Benzer şekilde, kullanıcılar uygulamanıza ilk kez eriştiğinde uygulamanıza, verilerine erişmesi için yetki vermeleri gerekir.

Uygulamanızın Analytics API'ye gönderdiği her istek bir yetkilendirme jetonu içermelidir. Bu jeton ayrıca uygulamanızı Google'a tanıtır.

Yetkilendirme protokolleri hakkında

Uygulamanız, istekleri yetkilendirmek için OAuth 2.0 kullanmalıdır. Başka hiçbir yetkilendirme protokolü desteklenmez. Uygulamanız Google ile Oturum Açma özelliğini kullanıyorsa yetkilendirme işleminin bazı kısımları sizin adınıza gerçekleştirilir.

OAuth 2.0 kullanarak istekleri yetkilendirme

Analytics API'ye yapılan tüm istekler, kimliği doğrulanmış bir kullanıcı tarafından yetkilendirilmelidir.

OAuth 2.0 ile yetkilendirme işleminin ("akış") ayrıntıları, yazdığınız uygulamanın türüne bağlı olarak değişiklik gösterir. Aşağıdaki genel işlem tüm uygulama türleri için geçerlidir:

  1. Uygulamanızı oluştururken Google API Konsolu'nu kullanarak kaydedersiniz. Ardından Google, daha sonra ihtiyaç duyacağınız bilgiler (ör. istemci kimliği ve istemci gizli anahtarı) sağlar.
  2. Google API Konsolu'nda Analytics API'yi etkinleştirin. (API, API Konsolu'nda listelenmemişse bu adımı atlayın.)
  3. Uygulamanız kullanıcı verilerine erişmesi gerektiğinde Google'dan belirli bir erişim kapsamı ister.
  4. Google, kullanıcıya uygulamanızı kullanıcının verilerinden bazılarını istemeye yetkilendirmesi için bir onay ekranı gösterir.
  5. Kullanıcı onaylarsa Google, uygulamanıza kısa süreli bir erişim jetonu verir.
  6. Uygulamanız, erişim jetonunu isteğe ekleyerek kullanıcı verileri için istekte bulunur.
  7. Google, isteğinizin ve jetonun geçerli olduğuna kanaat getirirse istenen verileri döndürür.

Bazı akışlarda başka adımlar da yer alır. Örneğin, yeni erişim jetonları almak için yenileme jetonları kullanmak. Farklı uygulama türlerine yönelik akışlar hakkında ayrıntılı bilgi için Google'ın OAuth 2.0 dokümanlarına bakın.

Analytics API için OAuth 2.0 kapsam bilgileri aşağıda verilmiştir:

Kapsam Anlamı
https://www.googleapis.com/auth/analytics.provision Varsayılan mülkü ve görünümüyle birlikte yeni bir Google Analytics hesabı oluşturma

Uygulamanızın OAuth 2.0 kullanarak erişim isteğinde bulunabilmesi için hem kapsam bilgilerine hem de uygulamanızı kaydederken Google tarafından sağlanan bilgilere (ör. istemci kimliği ve istemci gizli anahtarı) ihtiyacı vardır.

İpucu: Google API'leri istemci kitaplıkları, yetkilendirme işleminin bazı adımlarını sizin yerinize gerçekleştirebilir. Bu kitaplıklar çeşitli programlama dilleri için kullanıma sunulmuştur. Ayrıntılar için kitaplıkların ve örneklerin bulunduğu sayfayı inceleyin.

Yaygın OAuth 2.0 Akışları

Aşağıda, belirli OAuth 2.0 akışları için yaygın kullanım alanları listelenmektedir:

Web Sunucusu

Bu akış, bir kullanıcının Google Analytics verilerine otomatik, çevrimdışı veya planlanmış erişim için idealdir.

Örnek:

  • Kullanıcı kontrol panellerini en son Google Analytics verileriyle otomatik olarak güncelleme.

İstemci tarafı

Bu akış, kullanıcıların Google Analytics verilerine bir tarayıcıdan erişmek üzere doğrudan uygulamayla etkileşim kurduğu uygulamalar için idealdir. Sunucu tarafı özelliklere olan ihtiyacı ortadan kaldırır ancak otomatik, çevrimdışı veya planlanmış raporlamayı kullanılamaz hale getirir.

Örnek:

Yüklü Uygulamalar

Bu akış, paket olarak dağıtılan ve kullanıcı tarafından yüklenen uygulamalar içindir. Bu akış, uygulamanın veya kullanıcının kimlik doğrulama akışını tamamlamak için bir tarayıcıya erişiminin olmasını gerektirir.

Örnekler:

  • PC veya Mac'te masaüstü widget'ı.
  • İçerik yönetim sistemi eklentisi - Bu akışın, web sunucusuna veya istemci tarafına göre avantajı, uygulamanız için tek bir API Konsolu projesinin kullanılabilmesidir. Bu, birleştirilmiş raporlamaya ve kullanıcılar için daha basit kuruluma olanak tanır.

Hizmet Hesapları

Hizmet hesapları, kendi hesabınızdaki Google Analytics verilerine otomatik, çevrimdışı veya planlı erişim için kullanışlıdır. Örneğin, kendi Google Analytics verilerinizden canlı bir kontrol paneli oluşturabilir ve bunu diğer kullanıcılarla paylaşabilirsiniz.

Analytics API'yi kullanmaya başlamak için önce kurulum aracını kullanmanız gerekir. Bu araç, Google API Konsolu'nda proje oluşturma, API'yi etkinleştirme ve kimlik bilgileri oluşturma konusunda size rehberlik eder.

Yeni bir hizmet hesabı oluşturmak için aşağıdakileri yapın:

  1. Kimlik bilgileri oluştur > Hizmet hesabı anahtarı'nı tıklayın.
  2. Hizmet hesabının ortak/özel anahtarının standart P12 dosyası olarak mı yoksa bir Google API istemci kitaplığı tarafından yüklenebilen JSON dosyası olarak mı indirileceğini seçin.

Yeni herkese açık/özel anahtar çiftiniz oluşturulur ve makinenize indirilir; bu anahtarın tek kopyası olarak işlev görür. Dosyanın güvenli bir şekilde depolanmasından siz sorumlu olursunuz.

Sorun giderme

Yetkilendirmeniz aşağıdaki durumlarda başarısız olur:

  • access_token öğenizin süresi dolduysa veya API için yanlış kapsamı kullanıyorsanız 401 durum kodu alırsınız.

  • Yetkili kullanıcının görünüme (profile) erişimi yoksa bir 403 durum kodu alırsınız. Doğru kullanıcı için yetkilendirildiğinden ve seçtiğiniz görünüme (profile) sahip olduğundan emin olun.

OAuth 2.0 deneme alanı

Bu araç, bir web arayüzü üzerinden yetkilendirme akışının tamamını yapmanıza olanak tanır. Araç, yetkili bir sorgu yapmak için gereken tüm HTTP istek başlıklarını da görüntüler. Kendi uygulamanızda çalışma yetkisi alamıyorsanız, uygulamayı OAuth 2.0 oyun alanında çalışır duruma getirmeyi denemeniz gerekir. Daha sonra HTTP başlıklarını ve oyun alanından istekleri, uygulamanızın Google Analytics'e gönderdiği bilgilerle karşılaştırabilirsiniz. Bu kontrol, isteklerinizi doğru şekilde biçimlendirdiğinizden emin olmanın kolay bir yoludur.

Geçersiz izin

Yenileme jetonu kullanmaya çalıştığınızda aşağıdaki kod invalid_grant hatasını döndürür:

Uygulamalar, tek bir Google Analytics hesabına erişmek için birden fazla yenileme jetonu isteyebilir.

Örneğin, bir kullanıcı bir uygulamayı birden çok makineye yüklemek ve aynı Google Analytics hesabına erişmek isterse her makine için ayrı bir jeton gerekir. Yenileme jetonu sayısı sınırı aştığında eski jetonlar geçersiz hale gelir. Uygulama, geçersiz kılınan bir yenileme jetonu kullanmaya çalışırsa invalid_grant hata yanıtı döndürülür.

Benzersiz OAuth 2.0 istemcisi çifti ve Google Analytics hesabı için sınır 25 yenileme jetonudur. Uygulama aynı İstemci/Hesap çifti için yenileme jetonları istemeye devam ederse 26. jeton verildikten sonra daha önce yayınlanan 1. yenileme jetonu geçersiz hale gelir. İstenen 27. yenileme jetonu, önceden verilen 2. jetonu geçersiz kılar ve bu şekilde devam eder.