Management API - Yetkilendirme

Bu kılavuzda, bir uygulamanın Management API'ye gönderilen istekleri nasıl yetkilendirdiği açıklanmaktadır.

İstekleri Yetkilendirme

Kullanıcıların Google Analytics web sitesinde hesap bilgilerini görüntüleyebilmesi için önce 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 yetkilendirmeleri 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 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 için OAuth 2.0 kapsam bilgileri aşağıda verilmiştir:

Kapsam Anlamı
https://www.googleapis.com/auth/analytics.readonly Analytics API'ye salt okuma erişimi.
https://www.googleapis.com/auth/analytics.edit Google Analytics yönetim varlıklarını düzenleme
https://www.googleapis.com/auth/analytics.manage.users Analytics hesapları için kullanıcı izinlerini görüntüleyin ve yönetin.
https://www.googleapis.com/auth/analytics.manage.users.readonly Google Analytics kullanıcı izinlerini görüntüleme

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 örnekleri 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 Google Analytics verilerine bir tarayıcıdan erişmek üzere uygulamayla doğrudan etkileşimde bulunduğu uygulamalar için idealdir. Sunucu tarafındaki özelliklere duyulan ihtiyacı ortadan kaldırır ancak otomatik, çevrimdışı veya planlanmış raporlamayı pratik hale getirir.

Örnek:

Yüklü Uygulamalar

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

Örnekler:

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

Hizmet Hesapları

Hizmet hesapları, kendi hesabınızın Google Analytics verilerine otomatik, çevrimdışı veya planlı erişim sağlamak için kullanışlıdır. Örneğin, kendi Google Analytics verilerinizle ilgili canlı bir kontrol paneli oluşturabilir ve 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 bilgisi oluştur > Hizmet hesabı anahtarı'nı tıklayın.
  2. Hizmet hesabının herkese açık/özel anahtarını standart bir P12 dosyası veya Google API istemci kitaplığı tarafından yüklenebilen bir JSON dosyası olarak indirme arasında seçim yapın.

Yeni herkese açık/özel anahtar çiftiniz oluşturulur ve makinenize indirilir; bu anahtarın tek kopyası olarak işlev görür. Güvenli şekilde saklamaktan siz sorumlusunuz.

Sorun giderme

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

  • access_token geçerliliğini yitirdiyse 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ı tarafından yetkilendirildiğinden ve gerçekten de seçtiğiniz görünüme (profile) sahip olduğundan emin olun.

OAuth 2.0 oyun alanı

Bu araç, yetkilendirme akışının tamamını bir web arayüzü üzerinden gerçekleştirmenize olanak tanır. Araç, yetkilendirilmiş bir sorgu yapmak için gereken tüm HTTP isteği başlıklarını da görüntüler. Kendi uygulamanızda çalışma yetkisi alamıyorsanız, OAuth 2.0 geçiş noktasından çalışmasını sağlamaya çalışmalısınız. Daha sonra, HTTP üstbilgilerini ve oyun alanından gelen isteği, uygulamanızın Google Analytics'e gönderdiği istekle 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 çok yenileme jetonu isteyebilir.

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

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