מגבלות ומכסות של 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.

בקשות API לשיטות ליבה מחויבות במכסות ליבה. בקשות API לשיטות של Realtime מחויבות במכסות של Realtime. בקשות API ל-methods של משפך מחויבות במכסות של משפך. בקשות API לשיטות של Chat מחויבות במכסות של Chat. כל בקשה צורכת רק סוג אחד של מכסה.

קטגוריית המכסה שיטות API
ליבה runReport, runPivotReport, batchRunReports, batchRunPivotReports, runAccessReport, getMetadata, checkCompatibility, createAudienceExports
זמן אמת runRealtimeReport
משפך runFunnelReport
צ'אט properties.chat

מכסות בנכסי Analytics

כל הבקשות צורכות מכסות של הנכס.

שם המכסה מגבלות בנכסים רגילים מגבלת נכס Analytics 360
אסימוני ליבה לכל נכס ביום 200,000 2,000,000
מספר הטוקנים הבסיסיים לכל נכס בשעה 40,000 400,000
מספר הטוקנים של Core לכל פרויקט, לכל נכס, לשעה 14,000 140,000
בקשות מקבילות ליבה לכל נכס 10 50
שגיאות בחיבור לשרת הליבה לכל פרויקט, לכל נכס, לשעה 10 50
טוקנים בזמן אמת לכל נכס ביום 200,000 2,000,000
אסימונים בזמן אמת לכל נכס לשעה 40,000 400,000
אסימונים בזמן אמת לכל פרויקט לכל נכס לשעה 14,000 140,000
בקשות מקבילות בזמן אמת לכל נכס 10 50
שגיאות בחיבור לשרת בזמן אמת לכל פרויקט לכל נכס לשעה 10 50
טוקנים של משפך לכל נכס ביום 200,000 2,000,000
אסימוני משפך לכל נכס לשעה 40,000 400,000
אסימוני משפך לכל פרויקט לכל נכס לכל שעה 14,000 140,000
בקשות מקבילות במשפך לכל נכס 10 50
שגיאות בחיבור לשרת המשפך לכל פרויקט לכל נכס לשעה 10 50
טוקנים של צ'אט לכל נכס ביום 3,750,000 3,750,000
טוקנים לצ'אט לכל נכס לשעה 500,000 500,000
  • בקשות מקבילות נמדדות לפי מספר הבקשות שמבוצעות בו-זמנית. כדי לצמצם את מספר הבקשות בו-זמנית, המתינו עד שהבקשות הקודמות יושלמו לפני שתשלחו בקשות נוספות.
  • שגיאות בחיבור לשרת הן קודים 500 ו-503. המכסות של שגיאות בחיבור לשרת מחויבות רק כשבקשה גורמת לשגיאה בחיבור לשרת. כשמכסת השגיאות בחיבור לשרת נגמרת בצמד של פרויקט ונכס, כל הבקשות לנכס מהפרויקט נחסמות. לרשימה המלאה של תגובות השגיאה, ראו תגובות שגיאה.
  • כל בקשה צורכת מכסה של טוקנים לנכס לשעה וגם של טוקנים לפרויקט לנכס לשעה. כלומר, כדי שהמכסה "אסימונים לכל נכס לשעה" תנוצל לפני המכסה "אסימונים לכל פרויקט לכל נכס לשעה", צריך לגשת לנכס אחד מיותר מ-3 פרויקטים.

בכל נכס אפשר לשלוח 120 בקשות בשעה שעשויות להיות כפופות לסף. יכול להיות שיופעלו ערכי סף על המאפיינים userAgeBracket,‏ userGender,‏ brandingInterest,‏ audienceId ו-audienceName. המערכת מחילה ערכי סף כדי למנוע ממי שצופה בדוח להסיק את המאפיינים הדמוגרפיים או תחומי העניין של משתמשים ספציפיים.

מכסת טוקנים של נכסים

כל בקשה ל-Google Analytics Data API v1 צורכת טוקנים. מספר האסימונים שנדרשים תלוי במורכבות הבקשה. רוב הבקשות יחויבו ב-10 טוקנים או פחות, אבל בקשות מורכבות יותר (כמו שאילתות של Ask Advisor chat) יצרכו יותר.

גורמים שמשפיעים על צריכת הטוקנים

העלות המדויקת של טוקנים לבקשה נקבעת בזמן הביצוע, ולכן קשה לחשב אותה מראש. העלות מושפעת משילוב של גורמים שקשורים לבקשה עצמה ולנתונים הבסיסיים בנכס ב-Google Analytics. הגורמים הבאים יכולים להוביל לעלויות גבוהות יותר:

  • מספר השורות: בקשה למספר גדול יותר של שורות.
  • מספר המאפיינים והמדדים: ככל שכוללים יותר מאפיינים ומדדים,
  • מורכבות המסנן: שימוש בביטויי סינון מורכבים.
  • אורך טווח התאריכים: שאילתות על טווחי תאריכים ארוכים יותר.
  • עוצמת הנתונים (cardinality): מאפיינים עם עוצמה גבוהה (הרבה ערכים ייחודיים, כמו 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
}
דוגמה למטען ייעודי (payload) של תגובה ב-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 כדי לקבץ עד 5 דוחות בקריאת HTTP אחת, וכך לצמצם את התקורה של זמן הלוך ושוב (RTT) של HTTP (שימו לב שכל דוח בקבוצה עדיין נספר בנפרד במכסות של האסימונים ושל concurrentRequests).
  • הפחתת המורכבות והעוצמה (cardinality) של השאילתות: הגבילו את הבקשות רק למאפיינים ולמדדים שאתם צריכים, קצרו את dateRanges כשאפשר, והימנעו משילוב של כמה מאפיינים בעלי עוצמה גבוהה (כמו pagePath או fullPageUrl) בשאילתות דגימה תכופות.
  • שליטה על מספר הבקשות בו-זמנית: אפשר להכניס בקשות לתור או להגביל את גודל מאגר ה-workers כדי שמספר הבקשות הפעילות לא יעבור את המגבלה של concurrentRequests (10 בגרסה הרגילה, 50 ב-Analytics 360).
  • הטמעת השהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם מגבלות על ניסיונות חוזרים: אם בקשה נכשלת עם השגיאה 429 RESOURCE_EXHAUSTED,‏ 500 INTERNAL או 503 UNAVAILABLE, נסו שוב באמצעות השהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff), כמו שמתואר בקטע תגובות לשגיאות.

מעקב אחרי השימוש בטוקנים ב-Chat

בבקשות של Ask Advisor chat, הטוקנים מייצגים את עלויות החישוב, החשיבה ואחזור הנתונים הבסיסיים של המודל. צריכת הטוקנים ב-Chat מושפעת מהגורמים הבאים:

  • היקף השאילתה והניתוח: המורכבות וההיקף של הניתוח המבוקש.
  • טוקנים של קלט ופלט של המודל: נפח הנתונים ההקשריים שעובדו והתשובה שנוצרה.
  • טוקנים של חשיבה: שלבי החשיבה של המודל שנדרשים כדי לסכם את הממצאים.
  • זמן אחזור של ביצוע: זמן העיבוד שנדרש לניתוח נתונים בכמה שלבים.

כדי לעקוב אחרי השימוש בטוקנים בצ'אט, מגדירים את "returnPropertyQuota": true ב-ChatRequest. התגובה תכלול את האובייקט PropertyChatQuota שמכיל את השדות tokensPerDay ו-tokensPerHour עם היתרות שנוצלו והיתרות שנותרו.