محدودیت‌ها و سهمیه‌های Data API

محدودیت‌ها و سهمیه‌های زیر بر Data API اعمال می‌شود.

نحوه اعمال سهمیه‌ها

همه درخواست‌ها به Google Analytics Data API v1 به پروژه Google Cloud نیاز دارند و مشمول سهمیه‌های ذکرشده در این صفحه هستند. سهمیه‌ها صرف‌نظر از روش استفاده‌شده برای شناسایی پروژه فراخواننده مصرف می‌شوند، ازجمله:

  • درخواست‌های اصالت‌سنجی‌شده با اعتبارنامه‌های OAuth 2.0.
  • درخواست‌هایی که فقط بااستفاده از کلید میانای برنامه‌سازی کاربردی (API) اصالت‌سنجی شده‌اند.

از کلیدهای API برای مرتبط کردن درخواست با پروژه Google Cloud خاصی برای اهداف سهمیه و صورت‌حساب استفاده می‌شود. همه فراخوانی‌های API که بااستفاده از اطلاعات کاربری یا کلید API از پروژه شما انجام می‌شود، در سهمیه‌های قابل‌اعمال پروژه شما و دارایی Google Analytics لحاظ خواهد شد.

دسته‌های سهمیه

Data API چهار دسته سهمیه درخواست دارد: Core،‏ Realtime،‏ Funnel، و Chat.

درخواست‌های میانای برنامه‌سازی کاربردی به روش‌های Core از سهمیه‌های Core کسر می‌شود. درخواست‌های میانای برنامه‌سازی کاربردی به روش‌های Realtime، سهمیه‌های Realtime را کسر می‌کند. درخواست‌های میانای برنامه‌سازی کاربردی به روش‌های Funnel، سهمیه‌های Funnel را کسر می‌کند. درخواست‌های API به روش‌های Chat، سهمیه‌های Chat را کسر می‌کنند. هر درخواست فقط یک نوع سهمیه مصرف می‌کند.

دسته سهمیه روش‌های میانای برنامه‌سازی کاربردی
Core ‫runReport،‏ runPivotReport،‏ batchRunReports،‏ batchRunPivotReports،‏ runAccessReport،‏ getMetadata،‏ checkCompatibility،‏ createAudienceExports
Realtime runRealtimeReport
قیف runFunnelReport
گپ properties.chat

سهمیه‌های دارایی Analytics

همه درخواست‌ها سهمیه‌های دارایی را مصرف می‌کنند.

نام سهمیه حد دارایی استاندارد محدودیت دارایی Analytics 360
کدهای اصلی به‌ازای هر دارایی در روز ۲۰۰٫۰۰۰ ۲٬۰۰۰٬۰۰۰
کدهای اصلی به‌ازای هر دارایی در ساعت ‫۴۰٬۰۰۰ ۴۰۰٬۰۰۰
کدهای اصلی به‌ازای هر پروژه به‌ازای هر دارایی در ساعت ۱۴٬۰۰۰ ۱۴۰۰۰۰
درخواست‌های هم‌زمان اصلی برای هر دارایی 10 50
خطاهای سرور اصلی در هر پروژه در هر دارایی در هر ساعت 10 50
کدهای هم‌زمان به‌ازای هر دارایی در روز ۲۰۰٫۰۰۰ ۲٬۰۰۰٬۰۰۰
کدهای بی‌درنگ به‌ازای هر دارایی در ساعت ‫۴۰٬۰۰۰ ۴۰۰٬۰۰۰
کدهای هم‌زمان به‌ازای هر پروژه به‌ازای هر دارایی در ساعت ۱۴٬۰۰۰ ۱۴۰۰۰۰
درخواست‌های هم‌زمان هم‌زمان برای هر دارایی 10 50
خطاهای سرور هم‌زمان در هر پروژه در هر دارایی در هر ساعت 10 50
کدهای قیف به‌ازای هر دارایی در روز ۲۰۰٫۰۰۰ ۲٬۰۰۰٬۰۰۰
کدهای قیف به‌ازای هر دارایی در ساعت ‫۴۰٬۰۰۰ ۴۰۰٬۰۰۰
کدهای قیف در هر پروژه در هر دارایی در هر ساعت ۱۴٬۰۰۰ ۱۴۰۰۰۰
درخواست‌های هم‌زمان قیف برای هر دارایی 10 50
خطاهای سرور قیف به‌ازای هر پروژه به‌ازای هر دارایی در ساعت 10 50
کدهای گپ برای هر دارایی در روز ۳٬۷۵۰٬۰۰۰ ۳٬۷۵۰٬۰۰۰
کدهای گپ به‌ازای هر دارایی در ساعت ۵۰۰٬۰۰۰ ۵۰۰٬۰۰۰
  • درخواست‌های هم‌زمان با تعداد درخواست‌هایی که به‌طور هم‌زمان اجرا می‌شوند اندازه‌گیری می‌شود. برای کاهش هم‌زمانی درخواست، قبل‌از ارسال درخواست‌های بیشتر، منتظر بمانید تا درخواست‌های قبلی تکمیل شوند.
  • خطاهای سرور کدهای ۵۰۰ و ۵۰۳ هستند. سهمیه‌های «خطاهای سرور» فقط زمانی کسر می‌شود که درخواست به خطای سرور منجر شود. وقتی سهمیه «خطاهای سرور» برای یک جفت پروژه و دارایی تمام شود، همه درخواست‌ها به دارایی از پروژه مسدود می‌شود. برای مشاهده فهرست کامل پاسخ‌های خطا، به پاسخ‌های خطا مراجعه کنید.
  • هر درخواست سهمیه را هم برای «ژتون به‌ازای هر دارایی در ساعت» و هم برای «ژتون به‌ازای هر پروژه در هر دارایی در ساعت» مصرف می‌کند. این یعنی بیش‌از ۳ پروژه باید به یک دارایی دسترسی داشته باشند تا سهمیه «ژتون به‌ازای هر دارایی در ساعت» بتواند قبل‌از سهمیه «ژتون به‌ازای هر پروژه برای هر دارایی در ساعت» تمام شود.

دارایی‌ها مجاز به ۱۲۰ درخواست بالقوه آستانه‌دار در ساعت هستند. ابعاد userAgeBracket، userGender، brandingInterest، audienceId، و audienceName احتمالاً آستانه‌گذاری شده‌اند. آستانه‌ها اعمال می‌شوند تا از استنباط جمعیت‌شناسی یا علایق کاربران منفرد توسط هرکسی که گزارش را مشاهده می‌کند جلوگیری شود.

سهمیه کدهای دارایی

با هر درخواست به Google Analytics Data API v1، از ژتون‌ها استفاده می‌شود. تعداد توکن‌های کسرشده به پیچیدگی درخواست بستگی دارد. درحالی‌که اکثر درخواست‌ها ۱۰ یا تعداد کمتری از ژتون‌ها را مصرف می‌کنند، درخواست‌های پیچیده‌تر (مانند پُرسمان‌های «از مشاور بپرسید» chat) تعداد بیشتری را مصرف خواهند کرد.

عوامل مؤثر بر مصرف کردن نشان‌واره

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

  • تعداد ردیف‌ها: درخواست تعداد بیشتری ردیف.
  • تعداد ابعاد و سنجه‌ها: شامل تعداد بیشتری از ابعاد و سنجه‌ها.
  • پیچیدگی فیلتر: استفاده از عبارت‌های فیلتر پیچیده.
  • طول محدوده تاریخ: پُرسمان در دوره‌های تاریخ طولانی‌تر.
  • کاردینالیته داده: ابعاد با کاردینالیته بالا (مقادیر منحصربه‌فرد زیاد، مانند pagePath، ابعاد سفارشی) می‌توانند هزینه ژتون را به‌طور قابل‌توجهی افزایش دهند.
  • حجم رویداد دارایی: پُرسمان‌ها در دارایی‌هایی با حجم رویداد بالاتر ممکن است نسبت‌به همان پُرسمان در دارایی با داده‌های کمتر، توکن‌های بیشتری مصرف کنند.

پایش مصرف داده‌واحد

مؤثرترین روش برای تعیین هزینه ژتون برای فراخوانی‌های میانای برنامه‌سازی کاربردی خاص شما این است که پارامتر "returnPropertyQuota": true را در متن درخواست اضافه کنید (در runReport، batchRunReports، runPivotReport، batchRunPivotReports، runRealtimeReport، و runFunnelReport پشتیبانی می‌شود). سپس پاسخ میانای برنامه‌سازی کاربردی شامل شیء PropertyQuota خواهد بود که جزئیات ژتون‌های مصرف‌شده توسط آن درخواست خاص و مانده سهمیه باقی‌مانده را ارائه می‌دهد.

درخواست نمونه با returnPropertyQuota
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ],
  "returnPropertyQuota": true
}
نمونه بار داده پاسخ propertyQuota

وقتی "returnPropertyQuota": true تنظیم شود، پاسخ شامل شیء propertyQuota است که هر فیلد آن حاوی QuotaStatus با اعداد صحیح consumed و remaining است:

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    }
  ],
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 199999
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 39999
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 13999
    }
  }
}

هر فیلد در propertyQuota با یک سهمیه در سهمیه‌های دارایی Analytics مطابقت دارد. هزینه ژتون یک درخواست API به‌طور هم‌زمان از tokensPerDay، tokensPerHour، و tokensPerProjectPerHour کسر می‌شود. اگر هریک از دسته‌های سهمیه به 0 باقی‌مانده برسد، درخواست‌های بعدی به آن دارایی خطای 429 RESOURCE_EXHAUSTED برمی‌گرداند.

روال‌های مطلوب برای اجتناب از خطاهای 429 RESOURCE_EXHAUSTED
  • ترازها را به‌طور پویا پایش کنیدremaining: propertyQuota.tokensPerProjectPerHour.remaining و propertyQuota.tokensPerHour.remaining را در پاسخ‌ها بررسی کنید و وقتی تعداد کدهای باقی‌مانده به کمتر از آستانه ایمنی رسید، کارهای پس‌زمینه غیرفوری را محدود یا موقتاً متوقف کنید.
  • دسته‌بندی پُرسمان‌های مرتبط: از batchRunReports یا batchRunPivotReports برای گروه‌بندی حداکثر ۵ گزارش در یک تماس HTTP و کاهش سربار رفت‌وبرگشت HTTP استفاده کنید (توجه داشته باشید که هر گزارش در یک دسته همچنان به‌طور جداگانه در سهمیه‌های توکن و concurrentRequests محاسبه می‌شود).
  • کاهش پیچیدگی و کاردینالیته پُرسمان: درخواست‌ها را فقط به بعدها و سنجه‌های موردنیازتان محدود کنید، dateRanges را درصورت امکان کوتاه کنید، و از ترکیب کردن چند بعد کاردینالیته بالا (مثل pagePath یا fullPageUrl) در پُرسمان‌های نظرسنجی مکرر خودداری کنید.
  • کنترل هم‌زمانی درخواست: درخواست‌ها را در صف قرار دهید یا اندازه استخر کارگر را محدود کنید تا درخواست‌های درحال پردازش زیر حد concurrentRequests (۱۰ برای Standard،‏ ۵۰ برای Analytics 360) باقی بمانند.
  • عقب‌گرد نمایی را با محدودیت‌های تکرار پیاده‌سازی کنید: اگر درخواستی با 429 RESOURCE_EXHAUSTED،‏ 500 INTERNAL، یا 503 UNAVAILABLE ناموفق بود، بااستفاده از عقب‌گرد نمایی کوتاه تکرار کنید، همان‌طور که در پاسخ‌های خطا توضیح داده شده است.

مصرف و نظارت بر توکن گپ

برای درخواست‌های «از مشاور بپرسید» chat، ژتون‌ها نشان‌دهنده هزینه‌های محاسبات مدل، استدلال، و بازیابی داده‌های زیربنایی هستند. مصرف توکن Chat تحت‌تأثیر موارد زیر است:

  • دامنه پُرسمان و تحلیل: پیچیدگی و گستردگی تحلیل درخواستی.
  • نشان‌های ورودی و خروجی مدل: حجم داده‌های زمینه‌ای پردازش‌شده و روایت پاسخ تولیدشده.
  • داده‌واحدهای اندیشیدن: مراحل استدلال مدل که برای ترکیب کردن یافته‌ها لازم است.
  • تأخیر اجرا: زمان پردازش موردنیاز برای کاوش‌های داده چندمرحله‌ای.

برای نظارت بر استفاده از کد گپ، "returnPropertyQuota": true را در ChatRequest تنظیم کنید. پاسخ شامل شیء PropertyChatQuota خواهد بود که حاوی فیلدهای tokensPerDay و tokensPerHour با ترازهای مصرف‌شده و باقی‌مانده است.