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

מסמך זה מתאר כיצד להשתמש ב-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.
  • כדי לקבל מידע נוסף על השימוש ב-Google Analytics, ניתן לקרוא את קובץ העזר (ללא שימוש בספריית לקוחות).

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

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

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

שימוש ב-Real Time Reporting API

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

  1. שולח שאילתה לממשק ה-API לדיווח בזמן אמת.
  2. מטפל בתגובת ה-API.

שליחת שאילתה ל-Real Time Reporting API

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

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

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

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

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

דוגמאות קוד

הקטע דוגמאות בדף נתוני זמן אמת: get מספק קוד לדוגמה בשפות תכנות שונות כדי לשלוח שאילתה ל-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.

ניהול מכסות

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

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

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

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

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

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

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

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

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