Gerçek Zamanlı Raporlama API'si - Yetkilendirme

Bu kılavuzda bir uygulamanın Gerçek Zamanlı Raporlama API'sine yapılan istekleri nasıl yetkilendirdiği açıklanmaktadır.

İstekleri Yetkilendirme

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

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 işlevini kullanırsa yetkilendirme işleminin bazı kısımları sizin için gerçekleştirilir.

OAuth 2.0 kullanarak istekleri yetkilendirme

Analytics API'ye gönderilen tüm isteklerin, kimliği doğrulanmış bir kullanıcı tarafından yetkilendirilmesi gerekir.

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'si için OAuth 2.0 kapsam bilgileri şöyledir:

Kapsam Anlamı
https://www.googleapis.com/auth/analytics.readonly Analytics API'ye salt okuma erişimi.

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.

Genel OAuth 2.0 Akışları

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

Web Sunucusu

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

Örnek:

  • Kullanıcı gösterge tablolarını en son Google Analytics verileriyle otomatik olarak güncelleme.

İstemci tarafı

Bu akış, kullanıcıların tarayıcıyla Google Analytics verilerine erişmek için doğrudan uygulamayla etkileşimde bulunduğu uygulamalar için idealdir. Sunucu tarafı özelliklerine olan ihtiyacı ortadan kaldırır ancak otomatik, çevrimdışı veya planlı raporlamayı kullanışsız 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şebilmesini gerektirir.

Örnekler:

  • PC veya Mac'teki bir masaüstü widget'ı.
  • İçerik yönetim sistemi için bir eklenti: Bu akışın web sunucusu veya istemci tarafına kıyasla avantajı, uygulamanız için tek bir API Konsolu projesinin kullanılabilmesidir. Bu, birleştirilmiş raporlamaya ve kullanıcıların daha kolay yüklenmesine olanak tanır.

Hizmet Hesapları

Hizmet hesapları, kendi hesabınızın Google Analytics verilerine otomatik, çevrimdışı veya planlı erişim için yararlıdır. Örneğin, kendi Google Analytics verilerinizi içeren canlı bir kontrol paneli oluşturup 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 yol gösterir.

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

  1. Kimlik bilgisi 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üklenebilecek bir 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. Bu bilgileri güvenli bir şekilde saklamak sizin sorumluluğunuzdadır.

Sorun giderme

Yetkilendirmeniz şu durumlarda başarısız olur:

  • access_token kartınızın süresi dolmuşsa veya API için yanlış kapsamı kullanıyorsanız 401 durum kodunu alırsınız.

  • Yetkili kullanıcının görünüme (profili) erişimi yoksa 403 durum kodu alırsınız. Doğru kullanıcıyla yetkilendirdiğinizden ve bu kullanıcının gerçekten seçtiğiniz görünüme (profile) sahip olduğundan emin olun.

OAuth 2.0 oyun alanı

Bu araç, bir web arayüzü üzerinden yetkilendirme akışının tamamından geçmenize olanak tanır. Araç, yetkili sorgu yapmak için gereken tüm HTTP istek başlıklarını da görüntüler. Kendi uygulamanızda çalışmak için yetki alamıyorsanız OAuth 2.0 oyun alanı üzerinden çalıştırmayı denemeniz gerekir. Ardından HTTP üst bilgilerini ve oyun alanından gelen isteği, uygulamanızın Google Analytics'e gönderdiği bilgilerle karşılaştırabilirsiniz. Bu kontrol, isteklerinizi doğru şekilde biçimlendirdiğinizden emin olmak için basit bir yoldur.

Geçersiz izin

Yenileme jetonu kullanmayı denediğinizde aşağıdakiler size invalid_grant hatası verir:

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

Örneğin, bir kullanıcı bir uygulamayı birden fazla 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 hale getirilmiş bir yenileme jetonu kullanmayı denerse invalid_grant hata yanıtı döndürülür.

Her bir OAuth 2.0 istemcisi ve Google Analytics hesabı çifti için en fazla 25 yenileme jetonu olmalıdır. Uygulama aynı İstemci/Hesap çifti için yenileme jetonu istemeye devam ederse, 26. jeton gönderildikten sonra daha önce verilen ilk yenileme jetonu geçersiz olur. İstenen 27. yenileme jetonu daha önce verilen 2. jetonu geçersiz kılar ve benzer şekilde devam eder.