ניהול מכסות עבור Google Analytics Data API

מינז קאזי (Minhaz Kazi), אחראי קשרי מפתחים (Developers Advocate), Google Analytics – פברואר 2023

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

הסבר על מערכת המכסות של Google Analytics Data API

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

בהתאם לשיטה של Data API שבה אתם משתמשים, יש שלוש קטגוריות נפרדות של מכסות:

השיטות של Data API יבדקו כמה מאגרי מידע לגבי [טוקנים של מכסות][מכסות של Google Analytics Data API]:

  1. לכל נכס ביום
  2. לכל נכס לשעה
  3. לכל פרויקט לכל נכס לשעה
  4. בקשות מקבילות לכל נכס
  5. שגיאות בחיבור לשרת לכל פרויקט, לכל נכס ולכל שעה

המערכת בודקת את חמשת המאגרי המידע האלה בכל פעם שמתקבלת בקשה ל-Data API עבור נכס. אם אחת מהקטגוריות ריקה, הבקשה תיכשל באופן מיידי עם השגיאה 429. אם אף אחד מהמאגרים לא ריק, ייצרך טוקן אחד מהמאגר בקשות מקבילות לכל נכס, ואז בקשת ה-API תופעל. בהתאם למורכבות הבקשה, כמות מסוימת של טוקנים תנוצל מכל אחת משלוש הקטגוריות הראשונות אחרי שהביצוע יסתיים. גם הבקשות המקבילות לכל נכס יקבלו החזר של אסימון בשלב הזה.

המכסה לכל פרויקט, לכל נכס, לכל שעה מבטיחה שמיצוי המכסה של משתמש אחד או יותר לא ישפיע על משתמשים אחרים באפליקציה. כאן, project מתייחס לפרויקט GCP של האפליקציה. המכסה לכל נכס לשעה היא בדרך כלל פי ארבע מהמכסה לכל פרויקט לכל נכס לשעה. לכן, משתמשי קצה יכולים לגשת לנכס לפחות מארבעה פרויקטים שונים לפני שהם ממצים את מכסת השימוש לכל נכס לשעה. האכיפה של המכסה ברמת הפרויקט וברמת הנכס מבטיחה שבעיות שקשורות למכסה יוגבלו לנכס יחיד ולא ישפיעו על נכסים אחרים שהאפליקציה שלכם ניגשת אליהם.

המכסה שגיאות בחיבור לשרת מתייחסת לתגובות מה-API עם קודים 500 או 503. אם האפליקציה שלכם יוצרת יותר מדי שגיאות בזמן הגישה לנכס, היא תמצה את המכסה Server errors per project per property per hour.

כל אסימוני המכסה מתחדשים עד למגבלה במרווחי זמן קבועים. מידע מעודכן על מכסות זמין במאמר [מכסות של Google Analytics Data API]. לדוגמה, לשיטות Core מוקצים 1,250 אסימוני מכסה ב-bucket Per project per property per hour. בהנחה שבקשה ממוצעת מהאפליקציה שלכם צורכת 10 טוקנים של מכסת שימוש, האפליקציה תוכל לשלוח 125 בקשות Core לשעה לנכס רגיל, ופי 10 מהכמות הזו (1,250 בקשות 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 שבוצעה בהצלחה, תוכלו לראות כמה מכסה נצרכה בבקשה וכמה מכסה נשארה לנכס. אפשר גם להציג את המידע הזה למשתמש דרך ממשק האפליקציה.

ניהול מכסות

כדי להפיק את המרב מ-Data API, מומלץ להטמיע את השיטות המומלצות לניהול מכסות שמפורטות בהמשך. בנוסף, שדרוג הנכסים ל-360 יכול להגדיל את כמות הנתונים שאפשר לגשת אליהם דרך ה-API.

שיטות מומלצות

יש שתי דרכים עיקריות לצמצם את השימוש במכסה באפליקציה:

  • שליחת פחות בקשות API
  • שליחת בקשות API פחות מורכבות

בהתאם לשני העקרונות האלה, הנה כמה שיטות מומלצות שאפשר ליישם:

  • שמירת נתונים במטמון: הטמעה של שכבת מטמון תשפר את נוחות השימוש ואת ניהול המכסות באפליקציה. מערכת Google Analytics עצמה תאחסן במטמון את הבקשות ל-API, אבל בקשות חוזרות עדיין יגררו שימוש בטוקנים של מכסת השימוש. באמצעות שמירת תגובה מה-API במטמון, אפשר לצמצם באופן משמעותי את מספר הבקשות החוזרות. לדוגמה, נתונים שמתקבלים במהלך היום לגבי נכסים רגילים יכולים להיות עם זמן תפוגה של המטמון של 4 שעות או יותר. מידע נוסף זמין במאמר עדכניות הנתונים ב-Google Analytics.
  • מיזוג בקשות: נסו למזג כמה בקשות ל-API לבקשה אחת. לדוגמה, 5 בקשות לנתונים בפרק זמן של יומיים יכולות להשתמש בפי 3 יותר אסימוני מכסה בהשוואה לבקשה אחת לפרק זמן של 10 ימים. אם יש לכם כמה בקשות ששונות רק במאפיין אחד, כדאי למזג אותן לבקשה אחת.
  • פישוט הבקשות: כדאי להגביל את הבקשות לכמות המינימלית של נתונים שנדרשת לאפליקציה ולמשתמש. מספר גדול של שורות או עמודות או קריטריוני סינון מורכבים יצרכו יותר טוקנים מהמכסה. בדרך כלל, טווחי תאריכים ארוכים יותר יקרים יותר (לדוגמה, שינוי טווח התאריכים מ-28 ימים ל-365 ימים יכול לצרוך פי 3 יותר אסימוני מכסה). בנוסף, מומלץ להשתמש במאפיינים עם קרדינליות נמוכה יותר כשאפשר (למשל, בקשה dateHour במקום dateHourMinute).
  • שימוש יעיל ב-limit: שינוי הערך של limit בבקשת ה-API כדי להקטין את מספר השורות שמוחזרות לא משפיע באופן משמעותי על מספר הטוקנים של המכסה שנצרכו. לדוגמה, 5 בקשות עם מגבלות של 10,000 שורות יכולות לצרוך פי חמישה יותר אסימוני מכסה בהשוואה לבקשה אחת עם מגבלה של 50,000 שורות.
  • שימוש בקטגוריית השיטות הנכונה: כמו שצוין למעלה, מכסת השימוש מתחלקת בין שלוש קטגוריות של שיטות. שימוש בשיטה הנכונה לתרחיש השימוש הנכון יכול לחסוך מכסת שימוש בקטגוריות אחרות. לדוגמה, במקום ליצור משפך משלכם באפליקציה באמצעות נתונים משיטות ליבה, כדאי להשתמש בשיטה runFunnelReport ליצירת משפכים.
  • עדכון הגדרות ברירת המחדל: כשמשתמשים יוצרים דוחות או מתאימים אותם אישית בפלטפורמה שלכם, יכול להיות שהם לא יעדכנו את אפשרויות ברירת המחדל שמוצגות על ידי האפליקציה שלכם, וישנו אותן רק בזמן הריצה. אם לאפליקציה שלכם יש טווח תאריכים שמוגדר כברירת מחדל ל-365 ימים, והמשתמש בדרך כלל מעיין בדוח של 28 ימים, בסופו של דבר האפליקציה תנצל מכסת שימוש גדולה יותר מהנדרש באופן קבוע. מומלץ להגביל את הטווחים והבחירות בהגדרות ברירת המחדל ולאפשר למשתמשים לבחור את ההגדרות האופטימליות לתרחישי השימוש שלהם. או במקרים מסוימים, אפשר גם להגביל את ברירות המחדל שהמשתמשים יכולים לשנות.
  • הוספת בקשות לתור וטעינה מדורגת: חשוב לשים לב למגבלת האסימונים של בקשות בו-זמניות לכל נכס. האפליקציה לא צריכה לשלוח יותר מדי בקשות בו-זמנית. אם לאפליקציה שלכם יש מספר גדול של רכיבי ממשק משתמש שמובילים למספר משמעותי של בקשות ל-API, כדאי להשתמש בחלוקה לדפים בממשק המשתמש, בטעינה מדורגת ובבקשות בתור עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff) לניסיונות חוזרים. כדי לעקוב באופן אקטיבי אחרי השימוש באסימונים של בקשות מקבילות לכל נכס באפליקציה, צריך להשתמש ב-method‏ returnPropertyQuota.

ניהול חוויית המשתמש והציפיות שלו

  • לספק למשתמשים משוב לפני שהם מריצים שאילתות עם פוטנציאל לשימוש גבוה בטוקנים. לדוגמה, שאילתות עם כמה מאפיינים בעלי עוצמה גבוהה או עם טווח זמן גדול עשויות להשתמש במספר גדול של טוקנים. הצגת אזהרה והנחיה לאישור של שאילתות כאלה יכולה למנוע ממשתמשים לבצע שינויים מיותרים בדוחות ולעזור להם להגביל את ההיקף של השאילתות שלהם.
  • כדי לספק פתרונות דיווח בהתאמה אישית, צריך לאפשר למשתמשים להבין את השימוש בשאילתות של כל אלמנט בדוח שלהם. לדוגמה, אפשר לספק תצוגת ניפוי באגים שמפרטת את השימוש באסימון המכסה לכל רכיב בדוח.
  • לספק משוב על סוג השגיאה הספציפי שקשור למכסת השימוש, ולהציע פעולה למשתמש.
  • בנכסי Google Analytics 360, מכסת המגבלות גבוהה פי 5 עד פי 10 בהשוואה לנכסים רגילים, ולכן יש יותר גמישות בשימוש בנכסי Google Analytics 360.

אי אפשר להגדיל את המכסות של Data API מעבר למגבלות ברירת המחדל ב-Google Analytics 4. ב-Google Analytics 360 מוגדרות מכסות גבוהות יותר עבור נכסי Google Analytics 4. אם המשתמשים שלכם מגיעים למגבלות המכסה גם אחרי הטמעה של שיטות מומלצות, כדאי להם לשדרג את הנכסים שלהם ל-360. אפשרות נוספת למשתמשים היא להשתמש בייצוא של Google Analytics ל-BigQuery. כך המשתמשים יוכלו לייצא נתונים ברמת האירוע ל-BigQuery ולהריץ ניתוח משלהם.

אם יש לכם שאלות נוספות לגבי המכסות של Data API, אתם יכולים להיכנס ל-GA Discord או לפרסם שאלה ב-Stack Overflow. אם יש לכם בקשות ספציפיות לתכונות שקשורות ל-Data API, אתם יכולים לפרסם אותן בכלי למעקב אחר בעיות.