מינהאז קזי, יועץ למפתחים, 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 תבדוק קודם את הקטגוריה. אם לא יישארו אסימונים, הבקשה תיכשל. אחרת, הבקשה תופעל, ותנצל אסימון אחד או יותר מהקטגוריה בהתאם למורכבות הבקשה. האסימונים מתחדשים בקטגוריה עד למקסימום במרווחי זמן קבועים.
בהתאם ל-method של Data API שבו אתם משתמשים, יש 3 קטגוריות מכסות נפרדות:
- זמן אמת (בשביל
runRealtimeReport) - משפך (עבור
runFunnelReport) - ליבה (לכל השיטות האחרות)
ושיטות Data API יבדקו אם יש אסימוני מכסות בקטגוריות מרובות:
- לנכס ליום
- לנכס לשעה
- לפרויקט לכל נכס לשעה
- בקשות בו-זמניות לכל נכס
- שגיאות שרת לכל פרויקט לנכס בשעה
חמש הקטגוריות האלה נבדקות בכל פעם שמתקבלת בקשה של Data API לנכס. במקרה שאחת מהקטגוריות ריקה, הבקשה תיכשל באופן מיידי ותוצג שגיאת 429. אם אף אחת מהקטגוריות לא ריקה, ייעשה שימוש באסימון יחיד מהקטגוריה Concurrent requests per property (בקשות בו-זמניות לכל נכס) ואז תבוצע בקשת ה-API. בהתאם למורכבות הבקשה, בסיום הביצוע תנצלו כמות מסוימת של אסימונים מכל אחת משלוש הקטגוריות הראשונות. בשלב הזה, אסימון מתחדש גם לבקשות המקבילות לכל נכס.
המכסה לכל פרויקט לשעה מבטיחה שמיצוי המכסה של משתמש אחד או יותר לא ישפיע על משתמשים אחרים באפליקציה. כאן, פרויקט מתייחס לפרויקט GCP של האפליקציה שלכם. בדרך כלל, המכסה לכל נכס לשעה גדולה פי 4 מהמכסה לפרויקט לכל נכס לשעה. כך שמשתמשי קצה צריכים לגשת לנכס לפחות מארבעה פרויקטים שונים כדי לנצל את המכסה לנכס לשעה. אכיפת המכסות ברמת הפרויקט וברמת הנכס מבטיחה שבעיות המכסות מוגבלות לנכס אחד ולא ישפיעו על נכסים אחרים שאליהם האפליקציה ניגשת.
המכסה שגיאות בחיבור לשרת מתייחסת לתגובות של API עם קודים של 500 או 503. אם האפליקציה יוצרת יותר מדי שגיאות בגישה לנכס, היא תמצה את המכסה שגיאות שרת לכל פרויקט לכל נכס לשעה.
כל אסימוני המכסות מתחדשים לפי המגבלה במרווחי זמן שנקבעו. במאמר מכסות ל-Google Analytics Data API אפשר לקרוא מידע נוסף על המכסות המעודכנות. לדוגמה, שיטות מסוג Core מקבלות 1,250 אסימוני מכסה בקטגוריה לכל פרויקט לשעה. בהנחה שבבקשה הממוצעת מהאפליקציה יש 10 אסימוני מכסה, האפליקציה תוכל לשלוח 125 בקשות ליבה לשעה לנכס רגיל ופי 10 מהכמות הזו (1,250 בקשות ליבה) לכל נכס 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 שורות יכולות לצרוך פי 5 אסימוני מכסה לעומת בקשה אחת עם מגבלה של 50,000. - שימוש בקטגוריית ה-method הנכונה: כפי שצוין למעלה, מגבלות המכסות מחולקות לשלוש קטגוריות של שיטות. אם משתמשים בשיטה המתאימה לתרחיש הנכון, אפשר לחסוך במכסות בקטגוריות אחרות. לדוגמה, במקום ליצור משפך משלכם באפליקציה באמצעות נתונים משיטות ליבה, כדאי להשתמש בשיטה
runFunnelReportליצירת משפכים. - עדכון הגדרות ברירת מחדל: כשיוצרים דוחות בפלטפורמה או מתאימים אותם אישית, יכול להיות שהמשתמשים לא יעדכנו את אפשרויות ברירת המחדל שמוצגות באפליקציה וישנו אותן רק בזמן הריצה. אם לאפליקציה יש טווח תאריכים של 365 ימים כברירת מחדל, והמשתמש בדרך כלל יעיין בדוח של 28 ימים, המכסה תנוצל על בסיס קבוע יותר. כדאי להגביל את הטווחים והבחירות בהגדרות ברירת המחדל ולאפשר למשתמשים לבחור את ההגדרות האופטימליות לתרחישים לדוגמה שלהם. במקרים מסוימים, תוכלו גם להגביל את ברירות המחדל שהמשתמשים יכולים לשנות.
- בקשות להוספת פריטים לרשימת הבאים וטעינה מדורגת: חשוב לשים לב למגבלה של בקשות בו-זמנית לכל נכס. האפליקציה לא אמורה לשלוח יותר מדי בקשות בו-זמנית. אם לאפליקציה שלכם יש אלמנטים רבים בממשק המשתמש שמובילים למספר משמעותי של בקשות API, כדאי לעבור לדפים של ממשק המשתמש, טעינה עצלה, ולהוסיף תור לבקשות עם השהיה מעריכית לפני ניסיון חוזר. משתמשים בשיטה
returnPropertyQuotaכדי לעקוב באופן אגרסיבי אחר השימוש באסימון בקשות בו-זמניות לכל נכס באפליקציה.
ניהול חוויית המשתמש והציפיות
- חשוב לתת משוב למשתמשים לפני שהם מריצים שאילתות עם פוטנציאל לשימוש גבוה באסימונים. לדוגמה, שאילתות עם כמה מאפיינים בעלי עוצמה גבוהה או עם מסגרת זמן גדולה יכולות להשתמש במספר גדול של אסימונים. הצגת אזהרה ובקשת אישור לשאילתות כאלה יכולות למנוע ממשתמשים לבצע שינויים מיותרים בדוחות, ולעזור להם להגביל את ההיקף לשאילתות שלהם.
- בפתרונות דיווח בהתאמה אישית, המשתמשים יכולים להבין את השימוש בשאילתות בכל רכיב בדוח שלהם. לדוגמה, תוכלו ליצור תצוגת ניפוי באגים שבה יצוינו השימוש באסימון המכסה לכל רכיב בדוח.
- חשוב לתת משוב על הסוג הספציפי של שגיאות שקשורות למכסה ולהגדיר את פעולת המשתמש.
- נכסים ב-Google Analytics 360 מקבלים פי 5 עד 10 ממכסת האחסון בהשוואה לנכסים רגילים, וכך נהנים מגמישות רבה יותר עם נכסי Google Analytics 360.
אי אפשר להגדיל את מכסת ה-API מעבר למגבלות ברירת המחדל ב-Data API ל-Google Analytics 4. ב-Google Analytics 360 יש מכסות גבוהות יותר לנכסי Google Analytics 4. אם המשתמשים שלכם מגיעים למכסה גם אחרי שהם מיישמים את השיטות המומלצות, כדאי להם לשדרג את הנכסים שלהם ל-360. אפשרות נוספת למשתמשים היא להשתמש בייצוא ל-BigQuery מ-Google Analytics. כך המשתמשים יוכלו לייצא נתונים ברמת האירוע ל-BigQuery ולהפעיל ניתוח משלהם.
אם יש לכם שאלות נוספות לגבי המכסות של Data API, אפשר לעבור ל-GA Discord או לשאול ב-Stack Overflow. אם יש לכם בקשות ספציפיות לתכונות ב-Data API, תוכלו לפרסם אותן באתר המעקב אחר בעיות.