מגבלות ומכסות של Data API

המגבלות והמכסות הבאות חלות על Data API.

איך המכסות חלות

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

  • בקשות שאומתו באמצעות פרטי כניסה של OAuth 2.0.
  • בקשות שאומתו באמצעות מפתח API בלבד.

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

קטגוריות של מכסות

ל-Data API יש ארבע קטגוריות של מכסות בקשות: Core,‏ Realtime,‏ Funnel ו-Chat.

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

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

מכסות בנכס Analytics

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

שם המכסה מגבלות בנכסים רגילים מגבלת נכס Analytics 360
טוקנים מרכזיים לכל נכס ביום 200,000 2,000,000
Core Tokens Per Property Per Hour 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
טוקנים של משפך לכל נכס ביום 200,000 2,000,000
טוקנים של משפך לכל נכס לשעה 40,000 400,000
טוקנים של משפך המרות לכל פרויקט לכל נכס לכל שעה 14,000 140,000
בקשות מקבילות במשפך לכל נכס 10 50
שגיאות בחיבור לשרת במשפך לכל פרויקט לכל נכס לשעה 10 50
טוקנים של צ'אט לכל נכס ביום 3,750,000 3,750,000
Chat Tokens Per Property Per Hour 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
}
דוגמה למטען ייעודי לתגובה 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 אחת ולצמצם את התקורה של הלוך ושוב של HTTP (חשוב לזכור שכל דוח בקבוצה עדיין נספר בנפרד במכסת האסימונים ובמכסת concurrentRequests).
  • צמצום המורכבות והעוצמה (cardinality) של השאילתה: הגבלת הבקשות למאפיינים ולמדדים שאתם צריכים בלבד, קיצור dateRanges במידת האפשר והימנעות משילוב של כמה מאפיינים בעלי עוצמה גבוהה (כמו pagePath או fullPageUrl) בשאילתות תכופות של בדיקת סטטוס.
  • שליטה בבו-זמניות של בקשות: אפשר להוסיף בקשות לתור או להגביל את גודל מאגר ה-workers כדי שמספר הבקשות הפעילות יישאר מתחת למכסה של concurrentRequests (10 ב-Standard, 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 עם היתרות שנוצלו והיתרות שנותרו.