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

Minhaz Kazi, יועץ למפתחים, 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 שבה אתם משתמשים, יש שלוש מכסות נפרדות קטגוריות:

• זמן אמת (במשך runRealtimeReport)
• משפך (במשך runFunnelReport)
• ליבה (לכל השיטות האחרות)

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

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

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

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

אזהרה: מומלץ מאוד למפתחים לא לפלח אסימוני מכסה בכל פרויקטים מרובים של API. זו הפרה של התנאים וההגבלות של Google APIs.

המכסה של שגיאות בחיבור לשרת מתייחסת לתשובות מ-API עם 500 או קודים של 503. אם האפליקציה יוצרת יותר מדי שגיאות בגישה לנכס, הוא ינצל את שגיאות השרת לכל פרויקט נכסים לשעה.

כל אסימוני המכסה מתחדשים בהתאם למגבלה במרווחי הזמן שצוינו. פרטים נוספים מכסות של Google Analytics Data API להצגת פרטי המכסות העדכניים. לדוגמה, שיטות ליבה מקבלות 1,250 אסימוני מכסה בהגדרה לכל פרויקט לנכס לשעה בקטגוריה שלכם. בהנחה שבקשה ממוצעת מהאפליקציה שלכם צורכת מכסה של 10 האפליקציה שלך תוכל לשלוח 125 בקשות ליבה בשעה נכס רגיל ופי 10 מהסכום הזה (1,250 בקשות ליבה) לכל Analytics נכס 360. המגבלה הגבוהה יותר לאסימוני מכסה היא אחת היתרונות של נכסי Analytics 360.

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

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

לכן, אותה שאילתה בשני נכסים שונים עשויה להוביל שימוש שונה לחלוטין באסימונים, מכיוון שהעוצמה (cardinality) של המאפיינים עשויה שונים, או שנפח התנועה עשוי להיות שונה. עם זאת, אפשר לצפות עם רמות דומות של תנועה ותצורות דומות שימוש דומה באסימון. אפשר להשתמש בהנחה הזו כדי לחזות את השימוש באסימון הלקוח במהלך התכנון ותכנון האפליקציה.

הערה: אם השתמשתם בעבר ב-Reporting API ל-Universal Analytics, יבחינו שהמכסה שנאכפה על ידי Reporting API בפרויקט Application/API ברמה. אבל ב-Data API, האכיפה מתבצעת בנכס ב-Google Analytics וגם ברמת פרויקט ה-API.

מעקב אחרי ניצול המכסות

כדי לעקוב אחרי ניצול המכסות ולהציג את המידע הזה למשתמשי הקצה, אפשר להוסיף "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, צריך להריץ בהצלחה בקשת API לקבלת חזרה את האובייקט PropertyQuota. אם בנכס כבר יחרוג מקטגוריה של אסימון מכסה, הבקשה תיכשל עם שגיאה 429 התגובה לא תכיל את האובייקט PropertyQuota. אם הושפעת מהמצב בנושא הזה, ולדעתי האפליקציה שלכם תפיק תועלת מדרך נפרדת לבצע גישה לפרטי המכסה, סימוני 1+ את הבקשה לתכונה הזו בכלי למעקב אחר בעיות.

ניהול מכסות

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

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

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

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

כדאי ליישם את שני העקרונות האלה:

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

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

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

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

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