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

Minhaz Kazi, Developer Advocate, Google Analytics – Şubat 2023

Google Analytics Data API kullanarak uygulama geliştiriyorsanız API için geçerli kota ve sınırların işleyiş şeklini 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. Alakalı en iyi uygulamalardan bazıları, API'ye yüksek performanslı sorgular yapılmasını da sağlar. Bu sayede, uygulamanızdaki raporları ve kontrol panellerini hızlandırabilir ve daha iyi bir kullanıcı deneyimi sunabilirsiniz. Bu makalede, kota sistemi ve Google Analytics Data API'yi uygulamayla ilgili en iyi uygulamalar ele alınmaktadır.

Google Analytics Data API için kota sistemini anlama

Google Analytics milyonlarca geliştirici ve kullanıcı tarafından kullanıldığından, API isteklerindeki kota, sistemi işleyebileceğinden daha fazla veri işlemeye karşı korur ve sistem kaynaklarının adil bir şekilde dağıtılmasını sağlar. Google Analytics 4 mülkleri için Data API, API kotalarını yönetmek için jeton paketi sistemi kullanır. Kavramı anlamak için: Maksimum sayıda jeton barındırabilen bir paket olduğunu düşünün. Herhangi bir API isteği önce paketi kontrol eder. Hiç jeton kalmazsa istek başarısız olur. Aksi takdirde, istek yürütülür ve karmaşıklığına bağlı olarak paketten bir veya daha fazla jeton tüketir. Jetonlar, sabit zaman aralıklarında paketteki maksimum değere kadar yenilenir.

Kullandığınız Data API yöntemine bağlı olarak üç ayrı kota kategorisi vardır:

Data API yöntemleri ise kota jetonları için birden fazla paketi kontrol eder:

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

Bir mülk için Data API isteği her geldiğinde bu beş paket kontrol edilir. Paketlerden herhangi biri boşsa istek, 429 hatasıyla hemen başarısız olur. Paketlerden hiçbiri boş değilse Mülk başına eşzamanlı istek sayısı paketinden tek bir jeton tüketilir ve API isteği yürütülür. İsteğin karmaşıklığına bağlı olarak, yürütme tamamlandığında ilk üç paketin her birinden belirli miktarda jeton tüketilir. Mülk başına eşzamanlı istek sayısı da bu anda yenilenen bir jeton alır.

Mülk başına saatlik olarak proje başına kotası, bir veya daha fazla kullanıcı için kota tükenmesinin uygulamanızın diğer kullanıcılarını etkilememesini sağlar. Buradaki proje, uygulamanızın GCP projesi anlamına gelir. Saatlik mülk başına kotası genellikle Proje başına saatlik mülk başına kotasının dört katıdır. Bu nedenle, son kullanıcılar söz konusu olduğunda Saatlik mülk başına kotasının tükenmeden önce mülke en az dört farklı proje tarafından erişilmelidir. Hem proje hem de mülk düzeyinde kota yaptırımı, kota sorunlarının tek bir mülkle sınırlı olmasını sağlar ve uygulamanızın eriştiği diğer mülkleri etkilemez.

Sunucu hataları kotası, 500 veya 503 kodlarına sahip API yanıtlarını belirtir. Uygulamanız bir mülke erişirken çok fazla hata oluşturuyorsa mülk ve saat başına proje başına sunucu hatası kotasını tüketir.

Tüm kota jetonları, belirtilen aralıklarda sınıra kadar yenilenir. Güncellenen kota bilgileri için Google Analytics Data API Kotaları'na bakın. Örneğin Temel yöntemler, Proje başına saatlik olarak mülk başına paketinden 1.250 kota jetonu alır. Uygulamanızdan gelen ortalama bir isteğin 10 kota jetonu tükettiğini varsayarsak uygulamanız standart bir mülk için saatte 125 Çekirdek istek ve herhangi bir Analytics 360 mülkü için bu tutarın 10 katı (1.250 Temel istek) oluşturabilir. Daha yüksek kota jeton 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, yürütme isteğinde bulunmadan önce jeton kullanımını tam olarak tahmin etmek zordur. Aşağıdakiler genellikle isteğin daha karmaşık hale gelmesini sağlayarak jeton kullanımına neden olur:

  • Daha fazla boyut isteme
  • Daha yüksek zaman aralığını sorgulama
  • Daha yüksek kardinaliteye sahip boyutları dahil etme
  • Daha yüksek etkinlik sayısına sahip bir mülkü sorgulama

Bu nedenle, boyutların kardinalitesi veya trafik hacmi farklı olabileceğinden iki farklı özellik için aynı sorgu tamamen farklı jeton kullanımına yol açabilir. Bununla birlikte, benzer trafik seviyelerine 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 bilgiyi son kullanıcıya iletmek için API isteği gövdesine "returnPropertyQuota": true ekleyebilirsiniz. Bu, API yanıtıyla birlikte PropertyQuota nesnesini döndürür. PropertyQuota nesnesi, beş paketin tümü için tüketim miktarlarını ve kalan kota durumunu içerir. Aşağıda örnek bir istek gövdesi ve yanıtı verilmiştir:

İ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ı Data API isteğinden sonra isteğin ne kadar kota tükettiğini ve mülk için ne kadar kota kaldığını görebilirsiniz. Bu bilgiler, kullanıcıya uygulama arayüzünüz aracılığıyla da sunulabilir.

Kota yönetimi

Data API'den en iyi şekilde yararlanmak için aşağıda ayrıntılı olarak açıklanan kota yönetimi en iyi uygulamalarını 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 basit API istekleri gönderme

Bu iki ilkeyi göz önünde bulundurarak uygulayabileceğiniz uygulamalar şunlardır:

  • Önbelleğe alma: Bir önbelleğe alma katmanı uygulamak, uygulamanız için hem kullanılabilirlik hem de kota yönetimi açısından faydalıdır. Google Analytics, API isteklerinizi önbelleğe alır ancak tekrarlanan istekler için kota jetonları geçerli olmaya devam eder. 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 önbellek geçerlilik süresine sahip olabilir. Google Analytics için veri güncelliği bölümünü inceleyin.
  • Birleştirme istekleri: Birden çok API isteğini tek bir istekte birleştirmeyi deneyin. Örneğin, 2 günlük bir zaman aralığında 5 veri isteği, 10 günlük bir zaman dilimindeki 1 istekle karşılaştırıldığında kota jetonlarını 3 kez kullanabilir. Yalnızca tek bir boyuta göre değişiklik gösteren birden fazla isteğiniz varsa bunları tek bir istekte birleştirmeyi düşünün.
  • İstekleri basitleştirme: İsteklerinizi, uygulamanız ve kullanıcı için gereken minimum veri miktarıyla sınırlandırın. Çok sayıda satır/sütun veya karmaşık filtre ölçütü daha fazla kota jetonu tüketir. Daha uzun tarih aralıkları genellikle daha pahalıdır (ör. tarih aralığının 28 günden 365 güne çıkarılması, 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 isteyin).
  • limit kullanımının etkili kullanımı: Döndürülen satır sayısını azaltmak için API isteğindeki limit değerinin değiştirilmesi, tüketilen kota jetonlarını önemli ölçüde etkilemez. Örneğin, 10.000 satır sınırı olan 5 istek, 50.000 satır sınırı olan 1 istekle karşılaştırıldığında kota jetonu beş kez tüketebilir.
  • Doğru yöntem kategorisini kullanma: Yukarıda belirtildiği gibi, kota sınırları üç yöntem kategorisine yayılır. Doğru kullanım alanı için doğru yöntemin kullanılması, diğer kategorilerde kota tasarrufu sağlayabilir. Örneğin, Temel yöntemlerdeki 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üncellemeyebilir ve bunları yalnızca çalışma zamanında değiştirebilirler. Uygulamanızın varsayılan tarih aralığı 365 günse ve kullanıcı genellikle 28 günlük rapora bakarsa bu durum düzenli olarak gerekenden daha fazla kota tüketir. Varsayılan ayarlarda aralıkları ve seçimleri sınırlandırmayı deneyin ve kullanıcıların kullanım alanları için en uygun ayarları seçmesine izin verin. Bazı durumlarda, kullanıcıların değiştirebileceği varsayılan değerleri de sınırlayabilirsiniz.
  • İstekleri sıraya ekleme ve geç yükleme: Mülk Başına Eşzamanlı İstek Sayısı jeton sınırına dikkat edin. Uygulamanız aynı anda çok fazla istek göndermemelidir. Uygulamanızda çok sayıda API isteğine neden olan çok sayıda kullanıcı arayüzü öğesi varsa kullanıcı arayüzünü sayfalara ayırmayı, geç yüklemeyi ve yeniden denemeler için eksponansiyel geri yüklemeyle istekleri sıraya koymayı düşünebilirsiniz. Uygulamanızın Mülk Başına Eşzamanlı İstekler jeton kullanımını agresif bir şekilde izlemek için returnPropertyQuota yöntemini kullanın.

Kullanıcı Deneyimini ve Beklentilerini Yönetme

  • Yüksek jeton kullanımı potansiyeli olan sorguları çalıştırmadan önce kullanıcıya geri bildirim verin. Örneğin, birden fazla yüksek kardinaliteli boyuta veya geniş bir zaman aralığına sahip sorgularda çok sayıda jeton kullanılabilir. Bu tür sorgular için uyarı ve onay istemi sağlamak, kullanıcıların raporlarda gereksiz değişiklikler yapmasını engelleyebilir ve sorgularının kapsamını sınırlandırmalarına yardımcı olabilir.
  • Özelleştirilmiş raporlama çözümleri için kullanıcıların, raporlarındaki her bir öğenin sorgu kullanımını anlamaları için bir yol sağlayın. Örneğin, her 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şlemini tanımlayın.
  • Google Analytics 360 mülkleri, standart mülklere kıyasla 5-10 kat kota sınırı aldığından, Google Analytics 360 mülkleri ile daha fazla esneklik elde edersiniz.

Google Analytics 4 için Data API'de varsayılan sınırları aşan API kota artışları kullanılamaz. Google Analytics 360, Google Analytics 4 mülkleri için daha yüksek kota sınırları sağlar. Kullanıcılarınız en iyi uygulamaları uyguladıktan sonra bile kota sınırlarına ulaşıyorsa mülklerini 360 sürümüne yükseltmeyi düşünmeleri gerekir. Kullanıcılar için diğer bir seçenek de Google Analytics BigQuery Export'u kullanmaktır. Bu sayede kullanıcılar etkinlik düzeyindeki verileri BigQuery'ye aktarıp kendi analizlerini gerçekleştirebilir.

Data API kotalarıyla ilgili diğer sorularınız için GA Discord'a gidin veya Stack Overflow'a sorun. Veri API'siyle ilgili belirli özellik istekleriniz varsa bunları sorun izleyicimizde yayınlayabilirsiniz.