מדריך למפתחים

במסמך הזה מוסבר איך משתמשים ב-Real Time Reporting API כדי לקבל נתונים מ-Google Analytics.

מבוא

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

אם זו הפעם הראשונה שאתם משתמשים ב-API, מומלץ לקרוא את הסקירה הכללית על Real Time Reporting API כדי לקבל מבוא ל-Real Time Reporting API ולנתונים שהוא מספק.

ידע מוקדם שנדרש לקורס

לפני שמשתמשים ב-Real Time Reporting API כדי לקבל נתונים מ-Google Analytics:

  • בדף ספריות לקוח אפשר למצוא רשימה מלאה של ספריות לקוח ספציפיות לשפת תכנות שעובדות עם ה-API.
  • קראו את מדריך העזר כדי ללמוד כיצד להשתמש ב-API בלבד (ללא שימוש בספריית לקוח) כדי לקבל נתונים של Google Analytics.

כל ספריית לקוח מספקת אובייקט שירות יחיד של ניתוח נתונים כדי לגשת לכל הנתונים של Real Time Reporting API. כדי ליצור אובייקט שירות:

  1. רשום את האפליקציה שלך ב מסוף Google API.
  2. הרשאת גישה לנתוני Google Analytics.
  3. יוצרים אובייקט שירות של Analytics.

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

שימוש ב-Real Time Reporting API

כדי להשתמש ב-Real Time Reporting API, יש אפליקציה:

  1. שאילתה מ-Real Time Reporting API.
  2. טיפול בתגובת ה-API.

שליחת שאילתות אל Real Time Reporting API

האובייקט של השירות לניתוח נתונים מספק שיטה ליצירת שאילתה ב-Real Time Reporting API. לקבלת פרטים על הפרמטרים של השאילתה והנתונים שזמינים ל-API, כדאי לקרוא את המאמרים הבאים:

אחרי שמגדירים שאילתה, צריך לבצע קריאה ל-method execute שלה כדי לשלוח אותה לשרתים של Google Analytics.

טיפול בתגובת ה-API

אם השאילתה ל-Real Time Reporting API מצליחה, ה-API מחזיר את הנתונים המבוקשים כחלק ממשאב נתונים בזמן אמת. לפרטים על המבנה והפורמט של תגובות API, אפשר לעיין בחומר העזר בנושא Real Time Reporting API.

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

דוגמאות לקוד

הקטע דוגמאות בדף נתונים בזמן אמת: קבלת מספק קוד לדוגמה בשפות תכנות שונות, שמיועד לשליחת שאילתות ל-Real Time Reporting API ולטיפול בתגובת ה-API.

מגבלות השאילתה

אלה ההגבלות על שאילתות בזמן אמת של ה-API:

  • אם המדד rt:activeUsers נכלל בשאילתה עם מסנני המאפיינים הבאים, יש תמיכה רק באופרטור AND ובסוג התאמה שוויון (==).
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    מאחר שהמדד rt:activeUsers מאחזר רק את מספר המשתמשים הפעילים באתר כרגע, אין להשתמש ב-rt:minutesAgo עם rt:activeUsers. כלומר, rt:activeUsers מרמז ש-rt:minutesAgo הוא 0.

  • אין תמיכה במסנני מדדים.
  • אין תמיכה בפרמטר fields.

ניהול מכסות

כמו שמתואר בקטע Limits and Quota, ל-Real Time Reporting API יש מכסות יומיות שמשותפות עם ממשקי API אחרים של Google Analytics. אם מבצעים דגימה של ה-Real Time Reporting API במרווחי זמן קצרים, תוכלו להגיע למכסות היומיות במהירות רבה. במקרה כזה, גם בקשות מממשקי API אחרים של Google Analytics יפסיקו לפעול עד לעדכון המכסה.

דוגמאות להטמעות שעשויות לנצל את המכסה מהר מאוד:

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

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

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

דוגמה: חישוב מרווח הרענון

אם צפויים לשלוח בקשות לנתונים בזמן אמת על בסיס קבוע, יש לבחור מרווח רענון סביר על סמך השימוש הצפוי.

לדוגמה, לתצוגה מפורטת אחת (פרופיל) ב-Google Analytics יש מגבלה יומית של 10,000 בקשות ביום. אם צפויה לשלוח 6,000 שאילתות ב-Core Reporting API לתצוגה מפורטת אחת (פרופיל) ביום אחד, תישאר מכסה של 4,000 בקשות לתצוגה המפורטת הזו (פרופיל).

נניח שהחלטת להשתמש ב-Real Time Reporting API כדי להטמיע 3 מרכזי בקרה בזמן אמת שמפעילים שאילתות במשך כל היום כדי לקבל נתונים בזמן אמת מאותה תצוגה מפורטת (פרופיל). בכל מרכז בקרה אפשר לשלוח כ-1,333 שאילתות ליום (4,000 שאילתות / 3 מרכזי בקרה). ביום יש 86,400 שניות. לכן, מרווח הרענון בכל מרכז בקרה צריך להיות גדול מ-65 שניות (86,400 / 1,333), כך שהמספר הכולל של בקשות יומיות לצפייה (פרופיל) יהיה נמוך מהמגבלה היומית של 4,000.