منهاج قاضی، مدافع توسعه‌دهندگان، Google Analytics – فوریه ۲۰۲۳
اگر بااستفاده از [Google Analytics Data API] درحال توسعه برنامه‌ها هستید، باید با نحوه عملکرد سهمیه‌ها و محدودیت‌های این API آشنا باشید. اگر برنامه شما طراحی خوبی داشته باشد، احتمال اینکه کاربران به محدودیت‌های سهمیه برسند کمتر است. برخی‌از روال‌های مطلوب مرتبط نیز به پرسمان‌های کارآمد برای «میانای برنامه‌سازی کاربردی» منجر می‌شود. این کار می‌تواند سرعت گزارش‌ها و داشبوردهای برنامه شما را افزایش دهد و منجر به تجربه کاربری مطلوب‌تری شود. این مقاله درباره سیستم سهمیه و روال‌های مطلوب برای پیاده‌سازی «میانای برنامه‌سازی کاربردی داده Google Analytics» بحث می‌کند.
درک سیستم سهمیه برای Google Analytics Data API
ازآنجایی‌که میلیون‌ها توسعه‌دهنده و کاربر از Google Analytics استفاده می‌کنند، سهمیه درخواست‌های API از سیستم دربرابر پردازش داده‌های بیشتر از ظرفیتش محافظت می‌کند و درعین‌حال توزیع عادلانه منابع سیستم را تضمین می‌کند. «میانای برنامه‌سازی کاربردی داده» برای دارایی‌های Google Analytics 4 از سیستم سطل نشان برای مدیریت سهمیه‌های میانای برنامه‌سازی کاربردی استفاده می‌کند. برای درک مفهوم: تصور کنید سطلی وجود دارد که می‌تواند حداکثر تعداد معینی داده‌واحد را در خود جای دهد. هر درخواست API ابتدا سطل را بررسی می‌کند. اگر هیچ رمزی باقی نمانده باشد، درخواست ناموفق خواهد بود. درغیراین‌صورت، درخواست اجرا خواهد شد و بسته به پیچیدگی درخواست، یک یا چند کد از مخزن مصرف خواهد شد. توکن‌ها در فواصل زمانی ثابت تا حداکثر مقدار در باکت دوباره پر می‌شوند.
بسته به روش Data API که استفاده می‌کنید، سه دسته سهمیه جداگانه وجود دارد:
- هم‌زمان (برای
runRealtimeReport) - قیف (برای
runFunnelReport) - هسته (برای همه روش‌های دیگر)
و روش‌های Data API چندین مخزن را برای [نشان‌های سهمیه][سهمیه‌های Google Analytics Data API] بررسی می‌کنند:
- به‌ازای هر دارایی در روز
- برای هر ملک در ساعت
- به‌ازای هر پروژه، هر دارایی، هر ساعت
- درخواست‌های هم‌زمان برای هر ملک
- خطاهای سرور به‌ازای هر پروژه به‌ازای هر دارایی به‌ازای هر ساعت
این پنج دسته هر زمان که درخواست «میانای برنامه‌سازی کاربردی داده» برای دارایی ارسال می‌شود بررسی می‌شوند. اگر هریک از دسته‌ها خالی باشد، درخواست بلافاصله با خطای ۴۲۹ ناموفق خواهد بود. اگر هیچ‌کدام از دسته‌ها خالی نباشند، یک توکن از دسته درخواست‌های هم‌زمان برای هر دارایی مصرف خواهد شد و سپس درخواست API اجرا خواهد شد. براساس پیچیدگی درخواست، پس‌از تکمیل اجرا، مقدار مشخصی از هریک از سه ظرف اول مصرف خواهد شد. درخواست‌های هم‌زمان برای هر دارایی نیز در این زمان یک داده‌واحد (توکن) دریافت می‌کند.
سهمیه به‌ازای هر پروژه به‌ازای هر دارایی به‌ازای هر ساعت تضمین می‌کند که اتمام سهمیه برای یک یا چند کاربر بر سایر کاربران برنامه شما تأثیر نگذارد. در اینجا، پروژه به پروژه GCP برنامه شما اشاره دارد. سهمیه به‌ازای هر دارایی در ساعت معمولاً چهار برابر سهمیه به‌ازای هر پروژه در هر دارایی در ساعت است. بنابراین برای کاربران نهایی، قبل‌از اینکه سهمیه به‌ازای هر دارایی در هر ساعت تمام شود، باید حداقل چهار پروژه مختلف به دارایی دسترسی داشته باشند. اجرای سهمیه در هر دو سطح پروژه و دارایی تضمین می‌کند که مشکلات سهمیه به یک دارایی محدود می‌شود و بر دارایی‌های دیگری که برنامه شما به آن‌ها دسترسی دارد تأثیر نمی‌گذارد.
سهمیه خطاهای سرور به پاسخ‌های «میانای برنامه‌سازی کاربردی» با کدهای ۵۰۰ یا ۵۰۳ اشاره دارد. اگر برنامه شما هنگام دسترسی به دارایی خطاهای زیادی تولید کند، سهمیه خطاهای سرور در هر پروژه در هر دارایی در هر ساعت را مصرف خواهد کرد.
همه نشان‌های سهمیه در فواصل زمانی مشخص‌شده به حد مجاز بازپر می‌شوند. برای اطلاعات سهمیه به‌روزرسانی‌شده، به [سهمیه‌های Google Analytics Data API] مراجعه کنید. برای مثال، روش‌های اصلی در به‌ازای هر پروژه به‌ازای هر دارایی در هر ساعت ، ۱٬۲۵۰ واحد سهمیه دریافت می‌کنند. با فرض اینکه درخواست میانگین از برنامه شما ۱۰ واحد سهمیه مصرف می‌کند، برنامه شما می‌تواند در هر ساعت ۱۲۵ درخواست «اصلی» برای دارایی استاندارد و ۱۰ برابر این مقدار (۱۲۵۰ درخواست اصلی) برای هر دارایی Analytics 360 ارائه دهد. حد بالاتر برای تعداد نشانه‌های سهمیه یکی از مزایای اصلی دارایی‌های Analytics 360 است.
ازآنجایی‌که مصرف کد برای سه دسته اول به پیچیدگی درخواست بستگی دارد، پیش‌بینی دقیق استفاده از کد قبل‌از اجرای درخواست دشوار است. موارد زیر معمولاً پیچیدگی درخواست را افزایش می‌دهند، بنابراین منجر به استفاده از کد می‌شود:
- درحال درخواست ابعاد بیشتر
- درحال پُرسمان محدوده زمانی بالاتر
- شامل ابعاد با کاردینالیته بالاتر
- پرسش از دارایی با تعداد رویداد بیشتر
بنابراین، پُرسمان یکسان برای دو دارایی مختلف ممکن است منجر به استفاده کاملاً متفاوت از نشان شود زیرا ممکن است کاردینالیتی ابعاد متفاوت باشد یا حجم ترافیک متفاوت باشد. بااین‌حال، می‌توانید انتظار داشته باشید دارایی‌هایی با سطوح ترافیک مشابه و پیکربندی مشابه مصرف کد مشابهی داشته باشند. می‌توانید از این فرض برای پیش‌بینی استفاده از نشان مشتری در مراحل طراحی برنامه و برنامه‌ریزی استفاده کنید.
نظارت بر مصرف سهمیه
برای نظارت بر استفاده از سهمیه و انتقال این اطلاعات به کاربر نهایی خود، می‌توانید
"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، می‌توانید ببینید درخواست چقدر از سهمیه را مصرف کرده است و چقدر سهمیه برای دارایی باقی مانده است. همچنین می‌توانید این اطلاعات را ازطریق میانای برنامه خود به کاربر نشان دهید.
مدیریت سهمیه
توصیه می‌کنیم روال‌های مطلوب مدیریت سهمیه را که در زیر به‌تفصیل آمده است پیاده‌سازی کنید تا بیشترین بهره را از «میانای برنامه‌سازی کاربردی داده» ببرید. همچنین ارتقا دادن دارایی‌هایتان به ۳۶۰ می‌تواند مقدار داده‌های قابل‌دسترسی ازطریق API را افزایش دهد.
روال‌های مطلوب
به‌طور کلی دو روش برای کاهش استفاده از سهمیه برای برنامه شما وجود دارد:
- ارسال درخواست‌های کمتر به میانای برنامه‌سازی کاربردی
- ارسال درخواست‌های میانای برنامه‌سازی کاربردی کمتر پیچیده
با درنظر گرفتن این دو اصل، در اینجا روش‌هایی که می‌توانید پیاده‌سازی کنید آورده شده است:
- ذخیره در حافظه نهان: پیاده‌سازی لایه ذخیره در حافظه نهان هم برای قابلیت استفاده و هم برای مدیریت سهمیه برنامه شما مفید خواهد بود. خود Google Analytics درخواست‌های API شما را در حافظه نهان ذخیره می‌کند، اما درخواست‌های تکراری همچنان باعث مصرف واحدهای سهمیه می‌شود. با ذخیره کردن پاسخ «میانای برنامه‌سازی کاربردی» در حافظه نهان، می‌توانید تعداد درخواست‌های تکراری را به‌شدت کاهش دهید. برای مثال، داده‌های درون‌روزی برای دارایی‌های استاندارد می‌تواند زمان انقضای حافظه نهان ۴ ساعت یا بیشتر داشته باشد. تازگی داده‌ها برای Google Analytics را ببینید.
- ادغام درخواست‌ها: سعی کنید چندین درخواست API را در یک درخواست ادغام کنید. برای مثال، ۵ درخواست برای داده‌ها در یک بازه زمانی ۲ روزه می‌تواند ۳ برابر از نشان‌های سهمیه در مقایسه با ۱ درخواست برای یک بازه زمانی ۱۰ روزه استفاده کند. اگر چندین درخواست دارید که فقط در یک بُعد متفاوت هستند، آن‌ها را در یک درخواست ادغام کنید.
- ساده کردن درخواست‌ها: درخواست‌هایتان را به حداقل میزان داده‌های موردنیاز برنامه و کاربر محدود کنید. تعداد زیاد ردیف/ستون یا
معیارهای فیلتر پیچیده باعث مصرف بیشتر نشانه‌های سهمیه می‌شود. محدوده‌های تاریخ طولانی‌تر معمولاً گران‌تر هستند (برای مثال، تغییر محدوده تاریخ از ۲۸ روز به ۳۶۵ روز می‌تواند ۳ برابر نشانه‌های سهمیه را مصرف کند). همچنین می‌توانید درصورت امکان از
ابعاد با کاردینالیتی پایین‌تر استفاده کنید (برای نمونه، به‌جای
dateHourMinute، dateHourرا درخواست کنید). - استفاده مؤثر از
limit: تغییرlimitدر درخواست API برای کاهش تعداد ردیف‌های برگشتی تأثیر قابل‌توجهی بر توکن‌های سهمیه مصرف‌شده ندارد. برای مثال، ۵ درخواست با محدودیت ۱۰ هزار ردیف می‌تواند پنج برابر توکن‌های سهمیه را در مقایسه با ۱ درخواست با محدودیت ۵۰ هزار مصرف کند. - استفاده از دسته روش صحیح: همان‌طور که در بالا ذکر شد، محدودیت‌های سهمیه
در سه دسته روش پخش می‌شوند. استفاده از روش صحیح برای مورد استفاده صحیح می‌تواند سهمیه را در دسته‌های دیگر ذخیره کند. برای مثال، به‌جای اینکه
بااستفاده از داده‌های روش‌های «اصلی» در برنامه‌تان قیف خودتان را بسازید،
از روش
runFunnelReportبرای ساختن قیف‌ها استفاده کنید. - به‌روزرسانی تنظیمات پیش‌فرض: هنگام ساختن یا سفارشی‌سازی کردن گزارش‌ها در پلاتفرم شما، کاربران ممکن است گزینه‌های پیش‌فرض ارائه‌شده توسط برنامه شما را به‌روزرسانی نکنند و فقط آن‌ها را در زمان اجرا تغییر دهند. اگر برنامه شما محدوده تاریخ پیش‌فرضی ۳۶۵ روزه داشته باشد و کاربر معمولاً گزارش ۲۸ روزه را ببیند، این کار درنهایت باعث می‌شود که سهمیه بیشتری از آنچه به‌طور معمول لازم است مصرف شود. محدود کردن محدوده‌ها و انتخاب‌ها در تنظیمات پیش‌فرض را درنظر بگیرید و به کاربران اجازه دهید تنظیمات بهینه را برای موارد استفاده خود انتخاب کنند. یا در برخی موارد، می‌توانید محدود کنید که کاربران کدام پیش‌فرض‌ها را می‌توانند تغییر دهند.
- درخواست‌های در صف و بارگذاری تنبل: به محدودیت داده‌واحد درخواست‌های هم‌زمان برای هر دارایی توجه داشته باشید. برنامه شما نباید
تعداد زیادی درخواست را به‌طور هم‌زمان ارسال کند. اگر برنامه شما تعداد زیادی عنصر رابط کاربری دارد که منجر به تعداد قابل‌توجهی درخواست API می‌شود،
صفحه‌بندی رابط کاربری، بارگیری تنبل، و صف کردن درخواست‌ها با
پس‌افت نمایی برای تلاش مجدد را درنظر بگیرید. از روش
returnPropertyQuotaبرای نظارت دقیق بر استفاده از نشان درخواست‌های هم‌زمان به‌ازای هر دارایی در برنامه‌تان استفاده کنید.
مدیریت تجربه و انتظارات کاربر
- پیش‌از اینکه کاربر پُرسمان‌هایی با احتمال استفاده زیاد از نشان اجرا کند، به او بازخورد بدهید. برای مثال، پُرسمان‌هایی با چندین بُعد با تعداد عناصر زیاد یا با بازه زمانی طولانی می‌تواند از تعداد زیادی نشان استفاده کند. ارائه هشدار و پیام‌واره تأیید برای چنین پُرسمان‌هایی می‌تواند از ایجاد تغییرات غیرضروری در گزارش‌ها توسط کاربران جلوگیری کند و به آن‌ها کمک کند محدوده پُرسمان‌هایشان را محدود کنند.
- برای راه‌حل‌های گزارش‌دهی سفارشی، روشی برای کاربران فراهم کنید تا بتوانند استفاده از پُرسمان هر عنصر در گزارششان را درک کنند. برای مثال، می‌توانید فهرست نمای اشکال‌زدایی را ارائه دهید که استفاده از نشان سهمیه را برای هر عنصر گزارش فهرست می‌کند.
- درباره نوع خاص خطای سهمیه بازخورد ارائه دهید و اقدام کاربر را تجویز کنید.
- ازآنجایی‌که دارایی‌های Google Analytics 360 در مقایسه با دارایی‌های استاندارد، ۵ تا ۱۰ برابر حد سهمیه دارند، با دارایی‌های Google Analytics 360 انعطاف‌پذیری بیشتری خواهید داشت.
افزایش سهمیه «میانای برنامه‌سازی کاربردی» بالاتر از محدوده‌های پیش‌فرض برای «میانای برنامه‌سازی کاربردی داده» برای Google Analytics 4 دردسترس نیست. Google Analytics 360 سهمیه‌هایی با محدودیت‌های بالاتر برای دارایی‌های Google Analytics 4 ارائه می‌دهد. اگر کاربران شما حتی پس‌از اجرای روال‌های مطلوب به حد سهمیه می‌رسند، باید ارتقا دادن دارایی‌هایشان به ۳۶۰ را درنظر بگیرند. گزینه دیگر برای کاربران استفاده از صادرات Google Analytics BigQuery است. این کار به کاربران امکان می‌دهد داده‌های سطح رویداد را به BigQuery صادر کنند و تجزیه‌وتحلیل خودشان را اجرا کنند.
برای سؤالات بیشتر درباره سهمیه‌های «میانای برنامه‌سازی کاربردی داده»، به GA Discord بروید یا در Stack Overflow بپرسید. اگر درخواست‌های ویژگی خاصی درباره Data API دارید، می‌توانید آن‌ها را در ردیاب مشکل ما پست کنید.