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

محدودیت‌ها و سهمیه‌های زیر برای «میانای برنامه‌سازی کاربردی داده» اعمال می‌شود.

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

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

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

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

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

‫Data API چهار دسته سهمیه درخواست دارد: «اصلی»، «زمان واقعی»، «قیف»، و «گپ».

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

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

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

• درخواست‌های هم‌زمان با تعداد درخواست‌هایی که به‌طور هم‌زمان اجرا می‌شوند اندازه‌گیری می‌شود. برای کاهش هم‌زمانی درخواست، قبل‌از ارسال درخواست‌های بیشتر، منتظر بمانید تا درخواست‌های قبلی تکمیل شوند.
• «خطاهای سرور» کدهای ۵۰۰ و ۵۰۳ هستند. سهمیه‌های «خطاهای سرور» فقط زمانی کسر می‌شود که درخواست به خطای سرور منجر شود. وقتی سهمیه خطاهای سرور برای یک جفت پروژه و دارایی تمام می‌شود، همه درخواست‌های دارایی از پروژه مسدود می‌شود. برای مشاهده فهرست کامل پاسخ‌های خطا، پاسخ‌های خطا را ببینید.
• هر درخواست، سهمیه «تعداد نشان‌ها در هر دارایی در هر ساعت» و «تعداد نشان‌ها در هر پروژه در هر دارایی در هر ساعت» را مصرف می‌کند. این یعنی قبل‌از اینکه سهمیه «تعداد نشان در هر دارایی در هر ساعت» تمام شود، باید بیش‌از ۳ پروژه به یک دارایی دسترسی داشته باشند تا سهمیه «تعداد نشان در هر پروژه در هر دارایی در هر ساعت» تمام شود.

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

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

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

عواملی که بر مصرف نشان تأثیر می‌گذارند

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

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

نظارت بر مصرف داده‌واحد

مؤثرترین راه برای تعیین هزینه رمز برای فراخوانی‌های API خاص شما این است که پارامتر "returnPropertyQuota": true را در بدنه درخواست بگنجانید (در runReport، batchRunReports، runPivotReport، batchRunPivotReports، runRealtimeReport، و runFunnelReport پشتیبانی می‌شود). پاسخ API سپس شامل 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 (۱۰ برای «استاندارد»، ۵۰ برای Analytics 360) باقی بمانند.
• عقب‌گرد نمایی را با محدودیت‌های تکرار اجرا کنید: اگر درخواستی با 429 RESOURCE_EXHAUSTED، 500 INTERNAL، یا 503 UNAVAILABLE ناموفق بود، بااستفاده از عقب‌گرد نمایی کوتاه تکرار کنید، همان‌طور که در پاسخ‌های خطا توضیح داده شده است.

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

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

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

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