مینهاز کازی ، مشاور توسعهدهندگان، گوگل آنالیتیکس - فوریه ۲۰۲۳
اگر در حال توسعه برنامههایی با استفاده از [Google Analytics Data API] هستید، باید نحوه عملکرد سهمیهها و محدودیتهای API را درک کنید. اگر برنامه شما به خوبی طراحی شده باشد، احتمال کمتری وجود دارد که کاربران به محدودیتهای سهمیه برخورد کنند. برخی از بهترین شیوههای مرتبط همچنین منجر به پرسوجوهای عملکردی به API میشوند. این میتواند گزارشها و داشبوردها را در برنامه شما سرعت بخشد و منجر به یک تجربه کاربری مطلوبتر شود. این مقاله در مورد سیستم سهمیهبندی و بهترین شیوهها برای پیادهسازی Google Analytics Data API بحث میکند.
درک سیستم سهمیهبندی برای API داده گوگل آنالیتیکس
از آنجایی که گوگل آنالیتیکس توسط میلیونها توسعهدهنده و کاربر استفاده میشود، سهمیهبندی درخواستهای API، سیستم را از پردازش دادههای بیشتر از آنچه میتواند مدیریت کند، محافظت میکند و در عین حال توزیع عادلانه منابع سیستم را تضمین میکند. ویژگیهای Data API برای گوگل آنالیتیکس ۴ از یک سیستم Token Bucket برای مدیریت سهمیههای API استفاده میکند. برای درک مفهوم: تصور کنید یک Bucket وجود دارد که میتواند حداکثر تعداد Tokenها را در خود جای دهد. هر درخواست API ابتدا Bucket را بررسی میکند. اگر هیچ Tokenی باقی نمانده باشد، درخواست با شکست مواجه میشود. در غیر این صورت، درخواست اجرا میشود و بسته به پیچیدگی درخواست، یک یا چند Token از Bucket مصرف میکند. Tokenها در فواصل زمانی ثابت تا حداکثر مقدار در Bucket دوباره پر میشوند.
بسته به اینکه از کدام متد Data API استفاده میکنید، سه دسته سهمیهبندی جداگانه وجود دارد:
- بیدرنگ (برای
runRealtimeReport) - قیف (برای
runFunnelReport) - هسته (برای همه روشهای دیگر)
و متدهای Data API چندین سطل را برای [quota tokens][Google Analytics Data API Quotas] بررسی میکنند:
- به ازای هر ملک در روز
- به ازای هر ملک در هر ساعت
- به ازای هر پروژه به ازای هر ملک به ازای هر ساعت
- درخواستهای همزمان برای هر ملک
- خطاهای سرور به ازای هر پروژه به ازای هر ملک به ازای هر ساعت
این پنج سطل هر زمان که یک درخواست Data API برای یک ویژگی دریافت میشود، بررسی میشوند. اگر هر یک از سطلها خالی باشند، درخواست بلافاصله با خطای ۴۲۹ شکست میخورد. اگر هیچ یک از سطلها خالی نباشند، یک توکن از درخواستهای همزمان برای هر سطل ویژگی مصرف میشود و سپس درخواست API اجرا میشود. بر اساس پیچیدگی درخواست، پس از اتمام اجرا، مقدار مشخصی از توکنها از هر سه سطل اول مصرف میشود. درخواستهای همزمان برای هر ویژگی نیز در این زمان یک توکن دوباره پر میکنند.
سهمیه Per project per property per hour تضمین میکند که کاهش سهمیه برای یک یا چند کاربر، سایر کاربران برنامه شما را تحت تأثیر قرار نمیدهد. در اینجا، پروژه به پروژه GCP برنامه شما اشاره دارد. سهمیه Per property per hour معمولاً چهار برابر سهمیه Per project per property per hour است. بنابراین برای کاربران نهایی، یک property باید حداقل توسط چهار پروژه مختلف مورد دسترسی قرار گیرد تا سهمیه Per property per hour به پایان برسد. اجرای سهمیه در سطح پروژه و property تضمین میکند که مشکلات سهمیه به یک property واحد محدود میشود و بر سایر propertyهایی که برنامه شما به آنها دسترسی دارد، تأثیر نمیگذارد.
سهمیه خطاهای سرور به پاسخهای API با کدهای ۵۰۰ یا ۵۰۳ اشاره دارد. اگر برنامه شما هنگام دسترسی به یک ویژگی خطاهای زیادی ایجاد کند، سهمیه خطاهای سرور به ازای هر پروژه به ازای هر ویژگی به ازای هر ساعت را تمام میکند.
تمام توکنهای سهمیه در فواصل زمانی مشخص تا سقف تعیینشده شارژ میشوند. برای اطلاعات بهروز شده در مورد سهمیه به [Google Analytics Data API Quotas] مراجعه کنید. برای مثال، متدهای Core در هر پروژه به ازای هر ویژگی در هر ساعت، 1250 توکن سهمیه دریافت میکنند. با فرض اینکه یک درخواست متوسط از برنامه شما 10 توکن سهمیه مصرف کند، برنامه شما قادر خواهد بود 125 درخواست Core در هر ساعت برای یک ویژگی استاندارد و 10 برابر این مقدار (1250 درخواست Core ) برای هر ویژگی 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 داده، بهترین شیوههای مدیریت سهمیهبندی که در زیر شرح داده شده است را پیادهسازی کنید. همچنین ارتقاء ویژگیهای شما به ۳۶۰ میتواند میزان دادههای قابل دسترسی از طریق API را افزایش دهد.
بهترین شیوهها
به طور کلی دو راه برای کاهش استفاده از سهمیه برای برنامه شما وجود دارد:
- ارسال درخواستهای API کمتر
- ارسال درخواستهای API با پیچیدگی کمتر
با در نظر داشتن این دو اصل، در اینجا به روشهایی که میتوانید اجرا کنید، اشاره میکنیم:
- ذخیره سازی: پیاده سازی یک لایه ذخیره سازی، هم به بهبود قابلیت استفاده و هم به مدیریت سهمیه برای برنامه شما کمک خواهد کرد. خود گوگل آنالیتیکس درخواستهای API شما را ذخیره میکند، اما درخواستهای مکرر همچنان توکنهای سهمیه را به همراه خواهند داشت. با ذخیره سازی پاسخ API، میتوانید تعداد درخواستهای مکرر را به شدت کاهش دهید. به عنوان مثال، دادههای درون روزی برای ویژگیهای استاندارد میتوانند ۴ ساعت یا بیشتر زمان انقضای ذخیره سازی داشته باشند. به بخش تازگی دادهها برای گوگل آنالیتیکس مراجعه کنید.
- ادغام درخواستها: سعی کنید چندین درخواست API را در یک درخواست ادغام کنید. به عنوان مثال، 5 درخواست برای داده در یک بازه زمانی 2 روزه میتواند 3 برابر توکن سهمیه مصرف کند در مقایسه با 1 درخواست برای یک بازه زمانی 10 روزه. اگر چندین درخواست دارید که فقط در یک بُعد با هم متفاوت هستند، ادغام آنها را در یک درخواست واحد در نظر بگیرید.
- سادهسازی درخواستها: درخواستهای خود را به حداقل مقدار داده مورد نیاز برنامه و کاربر محدود کنید. تعداد زیاد ردیف/ستون یا معیارهای فیلتر پیچیده، توکنهای سهمیه بیشتری مصرف میکنند. محدودههای تاریخ طولانیتر معمولاً گرانتر هستند (مثلاً تغییر محدوده تاریخ از ۲۸ روز به ۳۶۵ روز میتواند ۳ برابر توکنهای سهمیه مصرف کند). همچنین میتوانید در صورت امکان، استفاده از ابعاد با کاردینالیتی پایینتر را در نظر بگیرید (مثلاً درخواست
dateHourبه جایdateHourMinute). - استفاده موثر از
limit: تغییرlimitدر درخواست API برای کاهش تعداد ردیفهای برگردانده شده، تأثیر قابل توجهی بر توکنهای سهمیه مصرف شده ندارد. به عنوان مثال، 5 درخواست با محدودیت 10 هزار ردیف میتوانند پنج برابر توکن سهمیه مصرف کنند در مقایسه با 1 درخواست با محدودیت 50 هزار. - استفاده از دسته بندی مناسب متد: همانطور که در بالا ذکر شد، محدودیتهای سهمیه در سه دسته متد توزیع شدهاند. استفاده از روش مناسب برای مورد استفاده مناسب میتواند سهمیه را در سایر دستهها ذخیره کند. به عنوان مثال، به جای ایجاد قیف فروش (Funnel) خود در برنامهتان با استفاده از دادههای متدهای Core، از متد
runFunnelReportبرای ایجاد قیفها استفاده کنید. - بهروزرسانی تنظیمات پیشفرض: هنگام نوشتن یا سفارشیسازی گزارشها در پلتفرم شما، ممکن است کاربران گزینههای پیشفرض ارائه شده توسط برنامه شما را بهروزرسانی نکنند و فقط آنها را در زمان اجرا تغییر دهند. اگر برنامه شما محدوده تاریخ پیشفرض ۳۶۵ روز دارد و کاربر معمولاً به گزارش ۲۸ روزه نگاه میکند، این امر در نهایت سهمیه بیشتری از حد مورد نیاز را به طور منظم مصرف خواهد کرد. محدود کردن محدودهها و انتخابها در تنظیمات پیشفرض را در نظر بگیرید و به کاربران اجازه دهید تنظیمات بهینه را برای موارد استفاده خود انتخاب کنند. یا در برخی موارد، میتوانید محدودیتهایی را که کاربران میتوانند تغییر دهند نیز محدود کنید.
- صفبندی درخواستها و بارگذاری کند: به محدودیت توکن درخواستهای همزمان به ازای هر ویژگی توجه داشته باشید. برنامه شما نباید درخواستهای زیادی را همزمان ارسال کند. اگر برنامه شما تعداد زیادی عنصر رابط کاربری دارد که منجر به تعداد قابل توجهی درخواست API میشود، صفحهبندی رابط کاربری، بارگذاری کند و صفبندی درخواستها با backoff نمایی برای تلاشهای مجدد را در نظر بگیرید. از روش
returnPropertyQuotaبرای نظارت دقیق بر میزان استفاده از توکن درخواستهای همزمان به ازای هر ویژگی برنامه خود استفاده کنید.
مدیریت تجربه و انتظارات کاربر
- قبل از اجرای پرسوجوهایی با پتانسیل استفاده زیاد از توکن، به کاربر بازخورد دهید. به عنوان مثال، پرسوجوهایی با چندین بعد کاردینالیتی بالا یا با بازه زمانی طولانی میتوانند از تعداد زیادی توکن استفاده کنند. ارائه هشدار و یک اعلان تأیید برای چنین پرسوجوهایی میتواند از ایجاد تغییرات غیرضروری در گزارشها توسط کاربران جلوگیری کند و به آنها کمک کند تا دامنه پرسوجوهای خود را محدود کنند.
- برای راهکارهای گزارشدهی سفارشی، راهی برای کاربران فراهم کنید تا میزان استفاده از کوئری هر عنصر در گزارش خود را درک کنند. به عنوان مثال، میتوانید یک نمای اشکالزدایی ارائه دهید که میزان استفاده از توکن سهمیه را برای هر عنصر گزارش فهرست میکند.
- در مورد نوع خاص خطای سهمیهبندی بازخورد ارائه دهید و اقدام لازم را برای کاربر تجویز کنید.
- از آنجایی که املاک گوگل آنالیتیکس ۳۶۰ در مقایسه با املاک استاندارد، ۵ تا ۱۰ برابر محدودیت سهمیه دریافت میکنند، با املاک گوگل آنالیتیکس ۳۶۰ انعطافپذیری بیشتری خواهید داشت.
افزایش سهمیه API بالاتر از محدودیتهای پیشفرض برای Data API برای Google Analytics 4 در دسترس نیست. Google Analytics 360 سهمیههای بالاتری را برای ویژگیهای Google Analytics 4 ارائه میدهد. اگر کاربران شما حتی پس از اجرای بهترین شیوهها به محدودیت سهمیه میرسند، باید ارتقاء ویژگیهای خود را به 360 در نظر بگیرند. گزینه دیگر برای کاربران استفاده از خروجی Google Analytics BigQuery است. این به کاربران اجازه میدهد دادههای سطح رویداد را به BigQuery صادر کنند و تجزیه و تحلیل خود را اجرا کنند.
برای سوالات بیشتر در مورد سهمیههای API داده، به GA Discord مراجعه کنید یا در Stack Overflow بپرسید. اگر درخواستهای خاصی در مورد API داده دارید، میتوانید آنها را در ردیاب مشکلات ما ارسال کنید.