Tag Manager API Yetkilendirmesi

Bu belgede, bir uygulamanın Etiket Yöneticisi API'sine istekte bulunmak için nasıl yetki alabileceği açıklanmaktadır.

İstekleri Yetkilendirme

Kullanıcıların herhangi bir Google sitesinde hesap bilgilerini görüntüleyebilmesi için önce Google Hesabı ile giriş yapması gerekir. Aynı şekilde, kullanıcılar uygulamanıza ilk kez eriştiğinde uygulamanızı verilerine erişmek için yetkilendirmeleri gerekir.

Uygulamanız tarafından Tag Manager API'ye gönderilen her isteğin bir yetkilendirme jetonu içermesi gerekir. 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

Etiket Yöneticisi API'sine 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 Etiket Yöneticisi API'sini 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.

Etiket Yöneticisi API'si için OAuth 2.0 kapsam bilgileri şöyledir:

Kapsam Anlamı
https://www.googleapis.com/auth/tagmanager.readonly Google Etiket Yöneticisi kapsayıcılarınızı görüntüleyin.
https://www.googleapis.com/auth/tagmanager.edit.containers Google Etiket Yöneticisi kapsayıcılarınızı yönetin.
https://www.googleapis.com/auth/tagmanager.delete.containers Google Etiket Yöneticisi kapsayıcılarınızı silin.
https://www.googleapis.com/auth/tagmanager.edit.containerversions Google Etiket Yöneticisi kapsayıcı sürümlerinizi yönetin.
https://www.googleapis.com/auth/tagmanager.publish Google Etiket Yöneticisi kapsayıcılarınızı yayınlayın.
https://www.googleapis.com/auth/tagmanager.manage.users Google Etiket Yöneticisi verilerinizin kullanıcı izinlerini yönetme
https://www.googleapis.com/auth/tagmanager.manage.accounts Google Etiket Yöneticisi hesaplarınızı yönetin.

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.

Başlarken

Etiket Yöneticisi API'yi kullanmaya başlamak için önce kurulum aracını kullanmanız gerekir. Bu araç, Google API Konsolu'nda proje oluşturma ve API'yi etkinleştirme 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 genel/özel anahtarını standart bir P12 dosyası olarak mı yoksa Google API istemci kitaplığı tarafından yüklenebilecek bir JSON dosyası olarak mı indireceğinizi 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. Anahtarın güvenli bir şekilde saklanması sizin sorumluluğunuzdadır.

Sık Kullanılan OAuth 2.0 Akışları

Aşağıdaki yönergelerde, belirli OAuth 2.0 akışlarıyla ilgili yaygın kullanım alanları özetlenmektedir:

Web Sunucusu

Bu akış, kullanıcının Google Etiket Yöneticisi hesabına otomatik/çevrimdışı/planlanmış erişim için uygundur.

Örnek:
  • Etiket Yöneticisi bilgilerini sunucudan otomatik olarak güncelleme.

İstemci tarafı

Kullanıcıların tarayıcıda Google Etiket Yöneticisi hesaplarına erişmek için doğrudan uygulamayla etkileşimde bulunduğu durumlarda idealdir. Bu akış, sunucu tarafı özelliklerine olan ihtiyacı ortadan kaldırır ancak otomatik/çevrimdışı/planlanmış raporlama için de pratik değildir.

Örnek:
  • Özelleştirilmiş bir tarayıcı tabanlı yapılandırma aracı.

Yüklü uygulamalar

Paket olarak dağıtılan ve kullanıcı tarafından yüklenen uygulamalar için. Kimlik doğrulama akışının tamamlanması için uygulamanın veya kullanıcının bir tarayıcıya erişmesi gerekir.

Ö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 projesi kullanılabilmesidir. Bu sayede kullanıcılar daha kolay bir kurulum yapabilir.

Hizmet Hesapları

Kendi Google Etiket Yöneticisi hesabınıza otomatik/çevrimdışı/planlanmış erişim için kullanışlıdır. Örneğin, kendi Google Etiket Yöneticisi hesabınızı izlemek ve diğer kullanıcılarla paylaşmak için özel bir araç oluşturabilirsiniz.

Sorun giderme

access_token süreniz dolduysa veya belirli bir API çağrısı için yanlış kapsamı kullanıyorsanız yanıtta 401 durum kodu alırsınız.

Yetkili kullanıcının Google Etiket Yöneticisi hesabına veya kapsayıcısına erişimi yoksa yanıtta 403 durum kodu alırsınız. Doğru kullanıcıyla yetkilendirildiğinizden ve Etiket Yöneticisi hesabına veya kapsayıcısına erişmek için izin verildiğinden emin olun.

OAuth 2.0 Playground

OAuth 2.0 Playground, web arayüzü üzerinden yetkilendirme akışının tamamını uygulamanıza olanak tanır. Bu araç, yetkili bir sorgu oluşturmak için gereken tüm HTTP isteği üst bilgilerini de gösterir. Kendi uygulamanızda yetkilendirme alamıyorsanız OAuth 2.0 Playground'u kullanarak yetkilendirme almaya çalışmalısınız. Ardından, HTTP üst bilgilerini ve isteği, uygulamanızın gönderdiği bilgilerle karşılaştırabilirsiniz. Bu kontrol, isteklerinizi doğru şekilde biçimlendirdiğinizden emin olmanın basit bir yoludur.

Geçersiz izin

Yenileme jetonu kullanmaya çalışırken invalid_grant hata yanıtı alırsanız hata, aşağıdakilerden biri veya her ikisinden kaynaklanıyor olabilir:

  1. Sunucunuzun saati NTP ile senkronize değil.
  2. Yenileme jetonu sınırını aştınız.
    Uygulamalar, tek bir Google Etiket Yöneticisi hesabına erişmek için birden fazla yenileme jetonu isteyebilir. Örneğin, bir kullanıcının bir uygulamayı birden fazla makineye yüklemek ve aynı Google Etiket Yöneticisi hesabına erişmek istediği durumlarda bu özellikten yararlanılabilir. Bu durumda, her yükleme için bir tane olmak üzere iki yenileme jetonu 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. Her benzersiz client-ID/hesap kombinasyonunda en fazla 25 yenileme jetonu olabilir. (Bu sınırın değişebileceğini unutmayın.) Uygulama aynı istemci kimliği/hesap kombinasyonu için yenileme jetonları istemeye devam ederse 26. jeton verildikten sonra verilen ilk yenileme jetonu geçersiz hale gelir. 27. istenen yenileme jetonu, verilen 2. jetonu geçersiz kılar. Bu durum diğer jetonlar için de geçerlidir.