Google Analytics Data API için kotayı yönetme

Minhaz Kazi, Geliştirici Destekçisi, Google Analytics – Şubat 2023

[Google Analytics Data API]'yi kullanarak uygulamalar geliştiriyorsanız API'nin kotalarının ve sınırlarının nasıl çalıştığını anlamanız gerekir. Uygulamanız iyi tasarlanmışsa kullanıcıların kota sınırlarına ulaşma olasılığı daha düşüktür. İlgili en iyi uygulamalardan bazıları, API'ye yönelik yüksek performanslı sorgulara da yol açar. Bu sayede uygulamanızdaki raporlar ve kontrol panelleri hızlanabilir ve daha iyi bir kullanıcı deneyimi elde edilebilir. Bu makalede, kota sistemi ve Google Analytics Veri API'sinin uygulanmasıyla ilgili en iyi uygulamalar ele alınmaktadır.

Google Analytics Data API'nin kota sistemini anlama

Google Analytics milyonlarca geliştirici ve kullanıcı tarafından kullanıldığından API istekleriyle ilgili kota, sistemin işleyebileceğinden daha fazla veri işlemesini engellerken sistem kaynaklarının eşit şekilde dağıtılmasını sağlar. Google Analytics 4 mülkleri için Data API, API kotalarını yönetmek üzere jeton grubu sistemi kullanır. Bu kavramı anlamak için maksimum sayıda jeton alabilen bir kova olduğunu düşünün. Tüm API istekleri önce paketi kontrol eder. Hiç jeton kalmamışsa istek başarısız olur. Aksi takdirde, istek yürütülür ve isteğin karmaşıklığına bağlı olarak paketten bir veya daha fazla jeton tüketilir. Jetonlar, belirli zaman aralıklarında maksimum seviyeye kadar kovaya eklenir.

Hangi Data API yöntemini kullandığınıza bağlı olarak üç ayrı kota kategorisi vardır:

Veri API'si yöntemleri ise [kota jetonları][Google Analytics Data API Kotaları] için birden fazla paketi kontrol eder:

  1. Mülk başına günlük
  2. Tesis başına saatlik
  3. Proje başına, mülk başına saatlik
  4. Mülk başına eşzamanlı istek sayısı
  5. Mülk başına proje başına saatlik sunucu hataları

Bu beş grup, bir mülk için Data API isteği geldiğinde kontrol edilir. Paketlerden herhangi biri boşsa istek hemen 429 hatasıyla başarısız olur. Hiçbir paket boş değilse Mülk başına eşzamanlı istekler paketinden tek bir jeton tüketilir ve ardından API isteği yürütülür. İsteğin karmaşıklığına bağlı olarak, yürütme tamamlandıktan sonra ilk üç paketin her birinden belirli sayıda jeton tüketilir. Mülk başına eşzamanlı istekler de bu sırada jeton yenileme işlemi alır.

Proje başına mülk başına saatlik kota, bir veya daha fazla kullanıcının kota tükenmesinin uygulamanızın diğer kullanıcılarını etkilememesini sağlar. Burada proje, uygulamanızın GCP projesini ifade eder. Mülk başına saatlik kota, genellikle proje başına mülk başına saatlik kotanın dört katıdır. Bu nedenle, son kullanıcılar için Saatlik mülk başına kota dolmadan önce bir mülke en az dört farklı proje tarafından erişilmesi gerekir. Hem proje hem de mülk düzeyinde kota zorunluluğu, kota sorunlarının tek bir mülkle sınırlı kalmasını ve uygulamanızın eriştiği diğer mülkleri etkilememesini sağlar.

Sunucu hataları kotası, 500 veya 503 kodlu API yanıtlarını ifade eder. Uygulamanız bir mülke erişirken çok fazla hata oluşturursa Saat başına proje başına mülk başına sunucu hatası kotası tükenir.

Tüm kota jetonları, belirtilen aralıklarla sınıra kadar yenilenir. Güncellenmiş kota bilgileri için [Google Analytics Data API Kotaları] başlıklı makaleyi inceleyin. Örneğin, Temel yöntemler, Proje başına, mülk başına, saat başına grubunda 1.250 kota jetonu alır. Uygulamanızdan gelen ortalama bir isteğin 10 kota jetonu kullandığını varsayarsak uygulamanız, standart bir mülk için saatte 125 temel istekte bulunabilir. Bu miktar, herhangi bir Analytics 360 mülkü için 10 katına (1.250 temel istek) çıkar. Daha yüksek kota token sınırı, Analytics 360 mülklerinin en önemli avantajlarından biridir.

İlk üç paket için jeton tüketimi isteğin karmaşıklığına bağlı olduğundan, istek yürütülmeden önce tam jeton kullanımını tahmin etmek zordur. Aşağıdaki durumlar genellikle isteğin karmaşıklığını artırır ve bu nedenle jeton kullanımıyla sonuçlanır:

  • Daha fazla boyut isteme
  • Daha yüksek bir zaman aralığı sorgulama
  • Daha yüksek kardinaliteli boyutlar dahil
  • Daha yüksek etkinlik sayısına sahip bir mülkte sorgu oluşturma

Bu nedenle, iki farklı mülk için aynı sorgu, boyutların kardinalitesi değişebileceğinden veya trafik hacmi farklı olabileceğinden tamamen farklı jeton kullanımıyla sonuçlanabilir. Ancak benzer trafik düzeylerine ve benzer yapılandırmaya sahip mülklerin benzer jeton kullanımına sahip olmasını bekleyebilirsiniz. Bu varsayımı, planlama ve uygulama tasarımı aşamalarında müşteri jetonu kullanımını tahmin etmek için kullanabilirsiniz.

Kota kullanımını izleme

Kota kullanımını izlemek ve bu bilgileri son kullanıcınıza iletmek için API isteği gövdesine "returnPropertyQuota": true ekleyebilirsiniz. Bu işlem, API yanıtıyla birlikte PropertyQuota nesnesini döndürür. PropertyQuota nesnesi, beş paketin tamamı için tüketim tutarlarını ve kalan kota durumunu içerir. İstek gövdesi ve yanıt örneğini aşağıda bulabilirsiniz:

İstek

{
  "dimensions": [
    {
      "name": "medium"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "yesterday"
    }
  ],
  "returnPropertyQuota": true
}

Yanıt

{
  "dimensionHeaders": [
    {
      "name": "medium"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  ...
  
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 24997
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 4997
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 1247
    }
  },
  
  "kind": "analyticsData#runReport",
  ...
}

Bu nedenle, her başarılı Veri API'si isteğinden sonra isteğin ne kadar kota kullandığını ve mülk için ne kadar kota kaldığını görebilirsiniz. Bu bilgileri uygulama arayüzünüz üzerinden kullanıcıya da gösterebilirsiniz.

bu özellik isteğini +1'leyin.

Kota yönetimi

Veri API'sinden en iyi şekilde yararlanmak için aşağıda ayrıntılı olarak açıklanan kota yönetimiyle ilgili en iyi uygulamaları uygulamanızı öneririz. Ayrıca, mülklerinizi 360'a yükseltmek API üzerinden erişilen veri miktarını artırabilir.

En iyi uygulamalar

Uygulamanızın kota kullanımını azaltmanın genel olarak iki yolu vardır:

  • Daha az API isteği gönderme
  • Daha az karmaşık API istekleri gönderme

Bu iki ilkeyi göz önünde bulundurarak uygulayabileceğiniz yöntemleri aşağıda bulabilirsiniz:

  • Önbelleğe alma: Önbelleğe alma katmanı uygulamak, hem kullanılabilirlik hem de uygulamanızın kota yönetimi açısından faydalı olur. Google Analytics, API isteklerinizi kendisi önbelleğe alır ancak tekrarlanan istekler yine de kota jetonlarına neden olur. API yanıtını önbelleğe alarak tekrarlanan isteklerin sayısını önemli ölçüde azaltabilirsiniz. Örneğin, standart mülklerin gün içi verileri 4 saat veya daha uzun bir önbellek geçerlilik süresine sahip olabilir. Google Analytics'te veri güncelliği başlıklı makaleyi inceleyin.
  • İstekleri birleştirme: Birden fazla API isteğini tek bir istekte birleştirmeyi deneyin. Örneğin, 2 günlük zaman aralığında 5 veri isteği, 10 günlük zaman aralığında 1 isteğe kıyasla 3 kat daha fazla kota jetonu kullanabilir. Yalnızca tek bir boyut açısından farklılık gösteren birden fazla isteğiniz varsa bunları tek bir istekte birleştirmeyi düşünebilirsiniz.
  • İstekleri basitleştirme: İsteklerinizi, uygulamanız ve kullanıcı tarafından gerekli olan minimum veri miktarıyla sınırlayın. Çok sayıda satır/sütun veya karmaşık filtre ölçütleri daha fazla kota jetonu kullanır. Daha uzun tarih aralıkları genellikle daha pahalıdır (ör. tarih aralığını 28 günden 365 güne değiştirmek, kota jetonlarının 3 katını tüketebilir). Mümkün olduğunda daha düşük kardinaliteye sahip boyutları da kullanabilirsiniz (ör. dateHourMinute yerine dateHour isteğinde bulunma).
  • limit etkili kullanımı: Döndürülen satır sayısını azaltmak için API isteğindeki limit değerini değiştirmek, kullanılan kota jetonlarını önemli ölçüde etkilemez. Örneğin, 10 bin satır sınırı olan 5 istek, 50 bin satır sınırı olan 1 isteğe kıyasla beş kat daha fazla kota jetonu tüketebilir.
  • Doğru yöntem kategorisini kullanma: Yukarıda belirtildiği gibi, kota sınırları üç yöntem kategorisine yayılmıştır. Doğru kullanım alanı için doğru yöntemi kullanmak, diğer kategorilerde kota tasarrufu sağlayabilir. Örneğin, temel yöntemlerden alınan verileri kullanarak uygulamanızda kendi dönüşüm huninizi oluşturmak yerine dönüşüm hunileri oluşturmak için runFunnelReport yöntemini kullanın.
  • Varsayılan ayarları güncelleme: Kullanıcılar, platformunuzda rapor oluştururken veya özelleştirirken uygulamanızın sunduğu varsayılan seçenekleri güncellemek yerine yalnızca çalışma zamanında değiştirebilir. Uygulamanızın varsayılan tarih aralığı 365 günse ve kullanıcı genellikle 28 günlük raporu görüntülüyorsa bu durum, düzenli olarak gerekenden daha fazla kota tüketimine neden olur. Varsayılan ayarlardaki aralıkları ve seçimleri sınırlayarak kullanıcıların kullanım alanları için en uygun ayarları seçmesine olanak tanıyabilirsiniz. Bazı durumlarda, kullanıcıların değiştirebileceği varsayılan ayarları da sınırlayabilirsiniz.
  • İstekleri sıraya alma ve geç yükleme: Mülk Başına Eşzamanlı İstek jetonu sınırına dikkat edin. Uygulamanız aynı anda çok fazla istek göndermemelidir. Uygulamanızda çok sayıda kullanıcı arayüzü öğesi varsa ve bu durum önemli sayıda API isteğine neden oluyorsa kullanıcı arayüzünde sayfalama, geç yükleme ve yeniden denemeler için üstel geri çekilme ile istekleri sıraya alma gibi yöntemleri kullanabilirsiniz. Uygulamanızın Mülk Başına Eşzamanlı İstek jetonu kullanımını agresif bir şekilde izlemek için returnPropertyQuota yöntemini kullanın.

Kullanıcı Deneyimini ve Beklentilerini Yönetme

  • Kullanıcılar, yüksek jeton kullanımı olasılığı olan sorgular çalıştırmadan önce geri bildirimde bulunun. Örneğin, birden fazla yüksek kardinaliteli boyut içeren veya geniş bir zaman aralığına sahip sorgular çok sayıda jeton kullanabilir. Bu tür sorgular için uyarı ve onay istemi sunmak, kullanıcıların raporlarda gereksiz değişiklikler yapmasını önleyebilir ve sorgularının kapsamını sınırlamalarına yardımcı olabilir.
  • Özelleştirilmiş raporlama çözümleri için kullanıcılara, raporlarındaki her bir öğenin sorgu kullanımını anlamaları için bir yol sunun. Örneğin, her bir rapor öğesi için kota jetonu kullanımını listeleyen bir hata ayıklama görünümü sağlayabilirsiniz.
  • Belirli bir kota hatası türü hakkında geri bildirim sağlayın ve kullanıcı işlemine yönelik talimatlar verin.
  • Google Analytics 360 mülkleri, standart mülklere kıyasla 5-10 kat daha fazla kota limiti aldığından Google Analytics 360 mülkleriyle daha fazla esneklik elde edersiniz.

Google Analytics 4 için Data API'de varsayılan sınırların üzerinde API kota artışları kullanılamaz. Google Analytics 360, Google Analytics 4 mülkleri için daha yüksek kotalar sunar. Kullanıcılarınız en iyi uygulamaları uyguladıktan sonra bile kota sınırlarına ulaşıyorsa mülklerini 360'a yükseltmeyi düşünebilirler. Kullanıcılar için bir diğer seçenek de Google Analytics BigQuery Export'u kullanmaktır. Bu sayede kullanıcılar, etkinlik düzeyindeki verileri BigQuery'ye aktarabilir ve kendi analizlerini çalıştırabilir.

Veri API'si kotalarıyla ilgili başka sorularınız varsa GA Discord'a gidin veya Stack Overflow'da sorun. Veri API'si ile ilgili belirli özellik istekleriniz varsa bunları Issue Tracker'da paylaşabilirsiniz.