مدیریت سهمیه برای Google Analytics Data API

Minhaz Kazi ، مدافع توسعه دهنده، Google Analytics - فوریه 2023

اگر در حال توسعه برنامه‌هایی با استفاده از Google Analytics Data API هستید، باید بدانید که سهمیه‌ها و محدودیت‌های API چگونه کار می‌کنند. اگر برنامه شما به خوبی طراحی شده باشد، احتمال کمتری وجود دارد که کاربران به محدودیت های سهمیه برسند. برخی از بهترین شیوه های مرتبط نیز منجر به پرس و جوهای عملکردی به API می شوند. این می تواند گزارش ها و داشبوردها را در برنامه شما سرعت بخشد و منجر به تجربه کاربری مطلوب تری شود. این مقاله سیستم سهمیه بندی و بهترین شیوه ها برای پیاده سازی Google Analytics Data API را مورد بحث قرار می دهد.

درک سیستم سهمیه برای Google Analytics Data API

از آنجایی که گوگل آنالیتیکس توسط میلیون‌ها توسعه‌دهنده و کاربر استفاده می‌شود، سهمیه درخواست‌های API از سیستم در برابر پردازش داده‌های بیشتر از توان پردازشی محافظت می‌کند و در عین حال توزیع عادلانه منابع سیستم را تضمین می‌کند. Data API برای ویژگی های Google Analytics 4 از یک سیستم سطل توکن برای مدیریت سهمیه های API استفاده می کند. برای درک مفهوم: تصور کنید یک سطل وجود دارد که می تواند حداکثر تعداد توکن را در خود جای دهد. هر درخواست API ابتدا سطل را بررسی می کند. اگر هیچ نشانه ای باقی نماند، درخواست با شکست مواجه خواهد شد. در غیر این صورت، درخواست اجرا می شود و بسته به پیچیدگی درخواست، یک یا چند توکن از سطل مصرف می کند. توکن ها در سطل تا حداکثر در بازه های زمانی ثابت پر می شوند.

بسته به اینکه از کدام روش Data API استفاده می کنید، سه دسته سهمیه جداگانه وجود دارد:

• بلادرنگ (برای runRealtimeReport )
• قیف (برای runFunnelReport )
• هسته (برای همه روش های دیگر)

و متدهای Data API چندین سطل را برای توکن‌های سهمیه بررسی می‌کنند:

1. هر ملک در روز
2. هر ملک در ساعت
3. هر پروژه در هر ملک در ساعت
4. درخواست های همزمان برای هر ملک
5. خطاهای سرور در هر پروژه در هر ویژگی در ساعت

هر زمان که درخواست Data API برای یک ویژگی وارد شود، این پنج سطل بررسی می‌شوند. اگر هر یک از سطل ها خالی باشد، درخواست بلافاصله با خطای 429 شکست می خورد. اگر هیچ یک از سطل ها خالی نباشد، یک توکن از درخواست های همزمان در هر سطل دارایی مصرف می شود و سپس درخواست API اجرا می شود. بر اساس پیچیدگی درخواست، پس از اتمام اجرا، مقدار مشخصی توکن از هر یک از سه سطل اول مصرف می‌شود. درخواست‌های همزمان به ازای هر دارایی نیز در این زمان یک توکن پر می‌شود.

سهمیه هر پروژه به ازای هر ملک در ساعت تضمین می کند که کاهش سهمیه برای یک یا چند کاربر بر دیگر کاربران برنامه شما تأثیری نخواهد گذاشت. در اینجا، پروژه به پروژه GCP برنامه شما اشاره دارد. سهمیه هر ملک در ساعت معمولاً چهار برابر سهمیه هر پروژه در هر ملک در ساعت است. بنابراین برای کاربران نهایی، یک دارایی باید توسط حداقل چهار پروژه مختلف قبل از اتمام سهمیه Per خاصیت در ساعت قابل دسترسی باشد. اجرای سهمیه در هر دو سطح پروژه و دارایی تضمین می‌کند که مسائل مربوط به سهمیه به یک دارایی محدود می‌شود و بر سایر دارایی‌هایی که برنامه شما به آنها دسترسی دارد تأثیر نمی‌گذارد.

هشدار: توسعه دهندگان به شدت از اشتراک گذاری توکن های سهمیه در چندین پروژه API منصرف می شوند. این نقض شرایط سرویس Google APIs است.

سهمیه خطاهای سرور به پاسخ های API با 500 یا 503 کد اشاره دارد. اگر برنامه شما هنگام دسترسی به یک ویژگی خطاهای زیادی ایجاد کند، خطاهای سرور در هر پروژه در هر ویژگی در هر ساعت سهمیه را تمام می کند.

تمام نشانه های سهمیه در بازه های زمانی مشخص شده تا حد مجاز پر می شوند. برای اطلاعات سهمیه به روز شده به Google Analytics Data API Quotas مراجعه کنید. به عنوان مثال، روش‌های Core 1250 توکن سهمیه در پروژه Per هر ویژگی در سطل ساعت دریافت می‌کنند. با فرض اینکه یک درخواست متوسط ​​از برنامه شما 10 توکن سهمیه مصرف می کند، برنامه شما می تواند 125 درخواست Core در ساعت برای یک ویژگی استاندارد و 10 برابر این مقدار (1250 درخواست هسته ) برای هر ویژگی Analytics 360 ارسال کند. محدودیت توکن سهمیه بالاتر یکی از مزایای اصلی خواص Analytics 360 است.

از آنجایی که مصرف توکن برای سه سطل اول به پیچیدگی درخواست بستگی دارد، پیش‌بینی استفاده دقیق از توکن قبل از اجرای درخواست دشوار است. موارد زیر معمولاً پیچیدگی یک درخواست را افزایش می دهد و در نتیجه استفاده از توکن را در پی خواهد داشت:

• درخواست ابعاد بیشتر
• جستجو در محدوده زمانی بالاتر
• از جمله ابعاد با کاردینالیته بالاتر
• پرس و جو از یک ملک با تعداد رویداد بالاتر

بنابراین، یک پرس و جو برای دو ویژگی مختلف ممکن است منجر به استفاده از توکن کاملاً متفاوت شود، زیرا ممکن است اصلی بودن ابعاد متفاوت باشد یا حجم ترافیک ممکن است متفاوت باشد. با این حال، می‌توانید انتظار داشته باشید ویژگی‌هایی با سطوح ترافیکی مشابه و پیکربندی مشابه، استفاده از توکن مشابهی داشته باشند. شما می توانید از این فرض برای پیش بینی استفاده از نشانه مشتری در مراحل برنامه ریزی و طراحی برنامه استفاده کنید.

توجه: اگر قبلاً از Reporting API برای Universal Analytics استفاده کرده بودید، متوجه خواهید شد که Reporting API سهمیه ای را در سطح پروژه Application/API اعمال می کند. اما برای Data API، اجرا در سطح ویژگی Google Analytics و همچنین در سطح پروژه API است.

نظارت بر استفاده از سهمیه

برای نظارت بر استفاده از سهمیه و انتقال آن اطلاعات به کاربر نهایی خود، می توانید "returnPropertyQuota": true به بدنه درخواست API اضافه کنید. این شیء PropertyQuota را همراه با پاسخ API برمی گرداند. شی PropertyQuota شامل مقادیر مصرف و وضعیت سهمیه باقی مانده برای هر پنج سطل خواهد بود. در اینجا یک نمونه بدنه درخواست و پاسخ آمده است:

درخواست کنید

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

پاسخ

{
  "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",
  ...
}

بنابراین، پس از هر درخواست موفقیت آمیز Data API، می توانید انتظار داشته باشید که میزان سهمیه درخواست مصرف شده و چه مقدار سهمیه برای ملک باقی مانده است. همچنین این امکان وجود دارد که این اطلاعات از طریق رابط برنامه شما به کاربر ارائه شود.

توجه: در مرحله فعلی Data API، باید یک درخواست API را با موفقیت اجرا کنید تا شی PropertyQuota را برگردانید. اگر دارایی قبلاً یک سطل توکن سهمیه را تمام کرده باشد، درخواست شما با خطای 429 ناموفق خواهد بود و پاسخ شامل شی PropertyQuota نخواهد بود. اگر تحت تأثیر این موضوع هستید و فکر می‌کنید که برنامه شما از داشتن یک راه جداگانه برای دسترسی به اطلاعات سهمیه سود می‌برد، این درخواست ویژگی را در ردیاب مشکل 1+ کنید.

مدیریت سهمیه

توصیه می‌کنیم بهترین شیوه‌های مدیریت سهمیه را که در زیر شرح داده شده است، اجرا کنید تا بیشترین بهره را از Data API ببرید. همچنین ارتقای ویژگی های خود به 360 می تواند میزان داده های قابل دسترسی از طریق API را افزایش دهد.

بهترین شیوه ها

به طور کلی دو راه برای کاهش استفاده از سهمیه برای برنامه شما وجود دارد:

• ارسال درخواست های API کمتر
• ارسال درخواست های کمتر پیچیده API

با در نظر گرفتن این دو اصل، در اینجا اقداماتی وجود دارد که می توانید اجرا کنید:

• ذخیره سازی: پیاده سازی یک لایه حافظه پنهان، هم قابلیت استفاده و هم مدیریت سهمیه برای برنامه شما مفید خواهد بود. گوگل آنالیتیکس خود درخواست های API شما را کش می کند، اما درخواست های مکرر همچنان دارای توکن های سهمیه ای هستند. با ذخیره کردن پاسخ API، می توانید تعداد درخواست های تکراری را به شدت کاهش دهید. به عنوان مثال، داده های روزانه برای ویژگی های استاندارد می تواند 4 ساعت یا بیشتر زمان انقضای کش داشته باشد. به تازگی داده ها برای Google Analytics مراجعه کنید.
• درخواست های ادغام: سعی کنید چندین درخواست API را در یک درخواست ادغام کنید. به عنوان مثال، 5 درخواست برای داده در یک چارچوب زمانی 2 روزه می تواند 3 برابر توکن های سهمیه در مقایسه با 1 درخواست برای یک چارچوب زمانی 10 روزه استفاده کند. اگر چندین درخواست دارید که فقط در یک بعد متفاوت هستند، آنها را در یک درخواست ادغام کنید.
• ساده سازی درخواست ها: درخواست های خود را به حداقل داده های مورد نیاز برنامه خود و کاربر محدود کنید. تعداد زیاد سطر/ستون یا معیارهای فیلتر پیچیده، توکن های سهمیه بیشتری مصرف می کند. محدوده‌های تاریخ طولانی‌تر معمولاً گران‌تر هستند (مثلاً تغییر محدوده تاریخ از 28 روز به 365 روز می‌تواند 3 برابر توکن‌های سهمیه مصرف کند). همچنین می‌توانید در صورت امکان از ابعاد با کاردینالیتی کمتر استفاده کنید (مثلاً درخواست dateHour به جای dateHourMinute ).
• استفاده مؤثر از limit : تغییر limit در درخواست API برای کاهش تعداد ردیف‌های برگشتی تأثیر قابل‌توجهی بر سهمیه‌های مصرفی ندارد. به عنوان مثال، 5 درخواست با محدودیت 10 هزار ردیف می توانند در مقایسه با 1 درخواست با محدودیت 50 هزار، توکن های پنج برابر سهمیه مصرف کنند.
• استفاده از دسته روش مناسب: همانطور که در بالا ذکر شد، محدودیت های سهمیه در سه دسته روش توزیع می شوند. استفاده از روش مناسب برای موارد استفاده مناسب می تواند سهمیه را در سایر دسته ها ذخیره کند. به عنوان مثال، به جای ایجاد قیف خود در برنامه خود با استفاده از داده های متدهای Core، از روش runFunnelReport برای ایجاد قیف استفاده کنید.
• تنظیمات پیش‌فرض را به‌روزرسانی کنید: هنگام نوشتن یا سفارشی کردن گزارش‌ها در پلتفرم، کاربران ممکن است گزینه‌های پیش‌فرض ارائه‌شده توسط برنامه شما را به‌روزرسانی نکنند و فقط در زمان اجرا آن‌ها را تغییر دهند. اگر برنامه شما دارای محدوده تاریخ پیش‌فرض 365 روزه باشد و کاربر معمولاً به گزارش 28 روزه نگاه می‌کند، در نهایت سهمیه‌ای بیش از مقدار مورد نیاز به طور منظم مصرف می‌شود. محدود کردن محدوده ها و انتخاب ها را در تنظیمات پیش فرض در نظر بگیرید و به کاربران اجازه دهید تنظیمات بهینه را برای موارد استفاده خود انتخاب کنند. یا در برخی موارد، می‌توانید پیش‌فرض‌هایی را که کاربران می‌توانند تغییر دهند، محدود کنید.
• درخواست‌های صف و بارگذاری تنبل: به محدودیت توکن درخواست‌های همزمان برای هر ویژگی توجه کنید. برنامه شما نباید درخواست های زیادی را همزمان ارسال کند. اگر برنامه شما دارای تعداد زیادی از عناصر UI است که منجر به تعداد قابل توجهی درخواست های API می شود، صفحه بندی UI، بارگذاری تنبل، و صف بندی درخواست ها با عقب نشینی نمایی برای تلاش های مجدد را در نظر بگیرید. از روش returnPropertyQuota برای نظارت جدی بر درخواست‌های همزمان برنامه‌تان به ازای استفاده از نشانه خاصیت استفاده کنید.

مدیریت تجربه و انتظارات کاربر

• قبل از اجرای پرس و جوهایی با استفاده از رمز بالا، بازخورد خود را به کاربر ارائه دهید. به عنوان مثال، پرس و جوهایی با چند بعد کاردینالیتی بالا یا با بازه زمانی بزرگ می توانند از تعداد زیادی نشانه استفاده کنند. ارائه اخطار و درخواست تأیید برای چنین پرسش‌هایی می‌تواند کاربران را از ایجاد تغییرات غیرضروری در گزارش‌ها جلوگیری کند و به آنها کمک کند دامنه را به سؤالات خود محدود کنند.
• برای راه‌حل‌های گزارش‌دهی سفارشی، راهی برای درک استفاده از پرس و جو از هر عنصر در گزارش خود برای کاربران فراهم کنید. برای مثال، می‌توانید یک نمای اشکال‌زدایی ارائه دهید که میزان استفاده از نشانه سهمیه را برای هر عنصر گزارش فهرست می‌کند.
• در مورد نوع خاص خطای سهمیه بازخورد ارائه دهید و اقدام کاربر را تجویز کنید.
• از آنجایی که دارایی‌های Google Analytics 360 در مقایسه با دارایی‌های استاندارد محدودیت سهمیه 5 تا 10 برابری دارند، با ویژگی‌های Google Analytics 360 انعطاف‌پذیری بیشتری خواهید داشت.

افزایش سهمیه API بالاتر از محدودیت‌های پیش‌فرض برای Data API برای Google Analytics 4 در دسترس نیست. Google Analytics 360 محدودیت‌های سهمیه بالاتری را برای ویژگی‌های Google Analytics 4 ارائه می‌کند. اگر کاربران شما حتی پس از اجرای بهترین شیوه‌ها، محدودیت‌های سهمیه را رعایت می‌کنند، باید به ارتقای ویژگی‌های خود به 360 فکر کنند. گزینه دیگر برای کاربران استفاده از Google Analytics BigQuery صادراتی است. این به کاربران امکان می‌دهد داده‌های سطح رویداد را به BigQuery صادر کرده و تجزیه و تحلیل خود را انجام دهند.

برای سؤالات بیشتر در مورد سهمیه های Data API، به GA Discord بروید یا در Stack Overflow سؤال کنید. اگر درخواست‌های ویژگی خاصی در مورد Data API دارید، می‌توانید آنها را در ردیاب مشکل ما پست کنید.