ממשק ה-API הראשי לדיווח – מדריך עזר

במסמך הזה תמצאו את ההנחיות המלאות לשאילתות ולתשובות בגרסה 3.0 של Core Reporting API.

מבוא

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

בקשה

ה-API מספק שיטה אחת לבקשת נתונים:

analytics.data.ga.get()

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

אפשר לשלוח שאילתות לגבי ה-API גם כנקודת קצה עם מילוי REST:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

כל פרמטר של שאילתה בכתובת URL מציין פרמטר של שאילתת API שחייב להיות מקודד בכתובת ה-URL.

סיכום הפרמטרים של השאילתה

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

שם Value נדרש סיכום
ids string כן מזהה הטבלה הייחודי של הטופס ga:XXXX, שבו XXXX הוא מזהה התצוגה המפורטת (פרופיל) ב-Analytics, שעבורו השאילתה תאחזר את הנתונים.
start-date string כן תאריך ההתחלה של שליפת נתוני Analytics. הבקשות יכולות לציין תאריך התחלה בפורמט YYYY-MM-DD, או כתאריך יחסי (למשל, today, yesterday או NdaysAgo כאשר N הוא מספר שלם חיובי).
end-date string כן תאריך הסיום של אחזור נתוני Analytics. הבקשה יכולה לציין תאריך סיום בפורמט YYYY-MM-DD או כתאריך יחסי (למשל, today, yesterday או NdaysAgo כאשר N הוא מספר שלם חיובי).
metrics string כן רשימה של מדדים שמופרדים בפסיקים, כמו ga:sessions,ga:bounces.
dimensions string no רשימה של מאפיינים שמופרדים בפסיקים של נתוני Analytics, כמו ga:browser,ga:city.
sort string no רשימה של מאפיינים ומדדים שמופרדים בפסיקים, שמציינים את סדר המיון ואת כיוון המיון של הנתונים שהוחזרו.
filters string no מסננים של מאפיינים או מדדים שמגבילים את הנתונים שמוחזרים עבור הבקשה שלך.
segment string no מפלחים את הנתונים שהוחזרו לגבי הבקשה שלך.
samplingLevel string no רמת הדגימה הרצויה. ערכים מותרים:
  • DEFAULT – מחזירה תגובה באמצעות גודל דגימה שמאזן את המהירות והדיוק.
  • FASTER – מחזירה תגובה מהירה עם דגימה קטנה יותר.
  • HIGHER_PRECISION – מחזירה תגובה מדויקת יותר באמצעות דגימה גדולה, אבל זה עלול לגרום לתגובה איטית יותר.
include-empty-rows boolean no ברירת המחדל היא TRUE. אם המדיניות מוגדרת כ-False, שורות שבהן כל ערכי המדדים הם אפס לא יוסרו מהתשובה.
start-index integer no השורה הראשונה של הנתונים שצריך לאחזר, החל מ-1. צריך להשתמש בפרמטר הזה כמנגנון עימוד יחד עם הפרמטר max-results.
max-results integer no מספר השורות המקסימלי שאפשר לכלול בתגובה.
output string no סוג הפלט הרצוי של נתוני Analytics שהוחזרו בתגובה. הערכים הקבילים הם json ו-dataTable. ברירת המחדל: json.
fields string no בורר שמציין קבוצת משנה של שדות שצריך לכלול בתשובה.
prettyPrint string no מחזירה תגובה עם כניסות פסקה ומעברי שורה. ברירת המחדל היא false.
userIp string no מציינת את כתובת ה-IP של משתמש הקצה שעבורו מבוצעת הקריאה ל-API. משמש להגבלת השימוש לכל כתובת IP.
quotaUser string no היא חלופית ל-userIp במקרים שבהם כתובת ה-IP של המשתמש לא ידועה.
access_token string no אחת מהדרכים לספק אסימון OAuth 2.0
callback string no השם של פונקציית הקריאה החוזרת (callback) של JavaScript שמטפלת בתגובה. משמש בבקשות JSON-P JavaScript.
key string no משמש להרשאת OAuth 1.0a לצורך ציון האפליקציה שלכם לקבלת מכסה. לדוגמה: key=AldefliuhSFADSfasdfasdfASdf.

פרטי פרמטר השאילתה

ids

ids=ga:12345
חובה.
המזהה הייחודי המשמש לאחזור הנתונים מ-Analytics. המזהה הזה הוא שרשור של מרחב השמות ga: עם מזהה התצוגה המפורטת (הפרופיל) ב-Analytics. אפשר לאחזר את מזהה התצוגה המפורטת (פרופיל) באמצעות השיטה analytics.management.profiles.list, שמספקת את הערך id במשאב 'תצוגה מפורטת (פרופיל)' ב-Google Analytics Management API.

תאריך התחלה

start-date=2009-04-20
חובה.
בכל הבקשות לנתוני Analytics יש לציין טווח תאריכים. אם לא תכללו בבקשה את הפרמטרים start-date ו-end-date, השרת יחזיר שגיאה. אפשר להזין ערכים של תאריך ספציפי באמצעות התבנית YYYY-MM-DD, או יחסית, באמצעות התבנית today, yesterday או התבנית NdaysAgo. הערכים חייבים להתאים ל-[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
start-date התאריך המוקדם ביותר שתקף הוא 2005-01-01. אין מגבלת תקרה לגבי תאריך התחלה.
התאריכים היחסיים הם תמיד יחסיים לתאריך הנוכחי בזמן השאילתה, והם מבוססים על אזור הזמן של התצוגה המפורטת (הפרופיל) שצוין בשאילתה.

טווח תאריכים לדוגמה מ-7 הימים האחרונים (החל מאתמול) לפי תאריכים יחסיים:

  &start-date=7daysAgo
  &end-date=yesterday

תאריך סיום

end-date=2009-05-20
חובה.
בכל הבקשות לנתוני Analytics יש לציין טווח תאריכים. אם לא תכללו בבקשה את הפרמטרים start-date ו-end-date, השרת יחזיר שגיאה. אפשר להזין ערכים של תאריך ספציפי באמצעות התבנית YYYY-MM-DD, או יחסית, באמצעות התבנית today, yesterday או התבנית NdaysAgo. הערכים חייבים להתאים ל-[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
end-date התאריך המוקדם ביותר שתקף הוא 2005-01-01. אין הגבלה על התקרה של end-date.
התאריכים היחסיים הם תמיד יחסיים לתאריך הנוכחי בזמן השאילתה, והם מבוססים על אזור הזמן של התצוגה המפורטת (הפרופיל) שצוין בשאילתה.

טווח תאריכים לדוגמה מ-10 הימים האחרונים (החל מהיום) עם תאריכים יחסיים:

  &start-date=9daysAgo
  &end-date=today

מימדים

dimensions=ga:browser,ga:city
אפשרות.
הפרמטר dimensions מפצל מדדים לפי קריטריונים נפוצים, לדוגמה לפי ga:browser או ga:city. אפשר לברר את המספר הכולל של צפיות בדף באתר שלך, אבל מעניין יותר לבקש להציג את מספר הצפיות בדפים בחלוקה לפי דפדפן. במקרה כזה, יוצג מספר הצפיות בדפים מ-Firefox, מ-Internet Explorer, מ-Chrome וכו'.

כשמשתמשים בשדה dimensions בבקשת נתונים, חשוב לשים לב למגבלות הבאות:

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


metrics

metrics=ga:sessions,ga:bounces
חובה.
הנתונים הסטטיסטיים המצטברים על פעילות המשתמשים באתר שלך, כמו קליקים או צפיות בדפים. אם שאילתה לא מכילה פרמטר dimensions, המדדים שמוחזרים מספקים ערכים נצברים לטווח התאריכים המבוקש, כמו סה"כ צפיות בדף או סה"כ עזיבות מהדף הראשון. עם זאת, כשנשלחת בקשה למאפיינים, הערכים מפולחים לפי ערך המאפיין. לדוגמה, הפונקציה ga:pageviews שהתבקשה עם ga:country מחזירה את המספר הכולל של צפיות בדף לכל מדינה. כשמבקשים מדדים, חשוב לזכור:
  • כל בקשה חייבת להכיל מדד אחד לפחות. בקשה לא יכולה להכיל רק מאפיינים.
  • ניתן לציין עד 10 מדדים לכל שאילתה.
  • ניתן להשתמש ברוב שילובי המדדים מכמה קטגוריות, כל עוד לא צוינו מאפיינים.
  • ניתן להשתמש במדד בשילוב עם מאפיינים או ערכים אחרים, אבל רק כאשר שילובים חוקיים חלים על אותו מדד. לפרטים נוספים, אפשר לעיין בחומר העזר בנושא מאפיינים ומדדים.


מיון

sort=ga:country,ga:browser
אפשרות.

רשימה של מדדים ומאפיינים שמציינים את סדר המיון ואת הכיוון של המיון של הנתונים שהוחזרו.

  • המיון של סידור נקבע לפי הסדר משמאל לימין של המדדים והמאפיינים המפורטים.
  • ברירת המחדל של מיון direction היא סדר עולה, וניתן לשנות אותו בסדר יורד באמצעות סימן חיסור (-) בשדה המבוקש.

מיון התוצאות של שאילתה מאפשר לך לשאול שאלות שונות על הנתונים. לדוגמה, כדי לענות על השאלה "מהן המדינות המובילות שלי ובאילו דפדפנים הם משתמשים בתדירות הגבוהה ביותר?" אפשר ליצור שאילתה עם הפרמטר הבא. הוא ממיין ראשון לפי ga:country ואז לפי ga:browser, שניהם בסדר עולה:

sort=ga:country,ga:browser

כדי לענות על השאלה הקשורה "מהם הדפדפנים המובילים שלי, ובאילו מדינות הם משתמשים בתדירות הגבוהה ביותר?", ניתן ליצור שאילתה עם הפרמטר הבא. הוא ממוין תחילה לפי ga:browser ולאחר מכן לפי ga:country, בסדר עולה:
sort=ga:browser,ga:country

כשמשתמשים בפרמטר sort, חשוב לזכור:

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

מסננים

filters=ga:medium%3D%3Dreferral
אפשרות.

הפרמטר של מחרוזת השאילתה filters מגביל את הנתונים שמוחזרים מהבקשה שלך. כדי להשתמש בפרמטר filters, עליך לציין מאפיין או מדד שלפיו יתבצע הסינון, ולאחר מכן את ביטוי המסנן. לדוגמה, השאילתה הבאה מבקשת את הערכים ga:pageviews ו-ga:browser עבור התצוגה המפורטת (פרופיל) 12134, שבה המאפיין ga:browser מתחיל במחרוזת Firefox:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

שאילתות מסוננות מגבילות את השורות שכלולות (או לא) נכללות בתוצאה. כל שורה בתוצאה נבדקת מול המסנן: אם המסנן תואם, השורה נשמרת, ואם היא לא תואמת, השורה מוסרת.

  • קידוד כתובות URL: ספריות הלקוח של Google API מקודדות באופן אוטומטי את האופרטורים של המסננים.
  • סינון מאפיינים: הסינון מתבצע לפני שמאפיינים נצברים, כך שהמדדים שהוחזרו מייצגים את הסכום הכולל של המאפיינים הרלוונטיים בלבד. בדוגמה שלמעלה, מספר הצפיות בדף יהיה רק אותן צפיות בדפים שבהן Firefox הוא הדפדפן.
  • סינון מדדים: סינון לפי מדדים מתרחש אחרי צבירת המדדים.
  • שילובים חוקיים: אפשר לסנן לפי מאפיין או מדד שלא נכללים בשאילתה, בתנאי שכל המאפיינים/המדדים שציינת בבקשה וגם שהמסנן הוא שילובים חוקיים. לדוגמה, ייתכן שתרצו להריץ שאילתה על רשימה של צפיות בדפים עם תאריך, תוך סינון בדפדפן מסוים. מידע נוסף זמין בחומר העזר בנושא מאפיינים ומדדים.

תחביר הסינון


מסנן יחיד משתמש בצורה הבאה:

ga:name operator expression

בתחביר הזה:

  • name - שם המאפיין או המדד שלפיו רוצים לסנן. לדוגמה: מסננים מסוג ga:pageviews לפי המדד 'צפיות בדף'.
  • אופרטור — מגדיר את סוג התאמת המסנן שבו יש להשתמש. האופרטורים הם ספציפיים למאפיינים או למדדים.
  • expression - מציין את הערכים שייכללו בתוצאות, או שיוחרגו מהן. בביטויים רגולריים נעשה שימוש בתחביר של ביטויים רגולריים.

אופרטורים של מסננים


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

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

מסנני מדדים
מפעיל התיאור טופס מקודד של כתובת URL דוגמאות
== שווה ל- %3D%3D הצגת תוצאות שבהן הזמן בדף הוא 10 שניות בדיוק:
filters=ga:timeOnPage%3D%3D10
!= לא שווה לערך !%3D החזרת תוצאות שבהן משך הביקור בדף אינו עשר שניות:
filters=ga:timeOnPage!%3D10
> גדול מ- %3E הצגת תוצאות שבהן משך הביקור בדף ארוך רק מעשר שניות:
filters=ga:timeOnPage%3E10
< פחות מ- %3C הצגת תוצאות שבהן משך הביקור בדף הוא פחות מעשר שניות:
filters=ga:timeOnPage%3C10
>= גדול מ- או שווה ל- %3E%3D הצגת תוצאות שבהן משך הביקור בדף הוא 10 שניות או יותר:
filters=ga:timeOnPage%3E%3D10
<= פחות מ- או שווה ל- %3C%3D הצגת תוצאות שבהן משך הביקור בדף הוא עשר שניות או פחות:
filters=ga:timeOnPage%3C%3D10

מסנני מאפיינים
מפעיל התיאור טופס מקודד של כתובת URL דוגמה
== התאמה מדויקת %3D%3D מדדים נצברים שבהם העיר היא אירווין:
filters=ga:city%3D%3DIrvine
!= לא תואמת !%3D מדדים נצברים שבהם העיר אינה אירווין:
filters=ga:city!%3DIrvine
=@ מכיל מחרוזת משנה %3D@ מדדים נצברים שבהם העיר מכילה את יורק:
filters=ga:city%3D@York
!@ לא מכיל מחרוזת משנה !@ מדדים נצברים שבהם העיר לא מכילה את המילה York:
filters=ga:city!@York
=~ מכיל התאמה לביטוי הרגולרי %3D~ מדדים נצברים שבהם העיר מתחילה בערך חדש:
filters=ga:city%3D~%5ENew.*
(%5E היא כתובת ה-URL שמקודדת מתוך התו ^ שקושר דפוס לתחילת המחרוזת).
!~ אינו תואם ביטוי רגיל !~ מדדים נצברים שבהם העיר לא מתחילה בערך חדש:
filters=ga:city!~%5ENew.*

ביטויי סינון

יש כמה כללים חשובים לגבי ביטויי סינון:

  • תווים שמורים של כתובות URL — קידוד כתובת ה-URL של תווים כמו & חייב להתבצע כרגיל.
  • תווים שמורים — יש לסמן בתו 'קו נטוי לאחור' ו'פסיק' כשהם מופיעים בביטוי:
    • נקודה ופסיק \;
    • פסיק \,
  • ביטויים רגולריים — ניתן להשתמש גם בביטויים רגולריים בביטויי סינון באמצעות האופרטורים =~ ו-!~. התחביר שלהן דומה לביטויים רגולריים של Perl, וכולל את הכללים הנוספים הבאים:
    • אורך מקסימלי של 128 תווים — ביטויים רגולריים שאורכם יותר מ-128 תווים יחזירו קוד סטטוס 400 Bad Request מהשרת.
    • תלות באותיות רישיות – התאמה של ביטויים רגולריים היא לא תלוית אותיות רישיות (case-sensitive).

שילוב מסננים

ניתן לשלב מסננים באמצעות לוגיקה בוליאנית OR ו-AND. כך תוכלו להאריך ביעילות את המגבלה של 128 תווים של ביטוי מסנן.

או

האופרטור OR מוגדר באמצעות פסיק (,). הוא מקבל עדיפות על האופרטור AND ולא ניתן להשתמש בו כדי לשלב מאפיינים ומדדים באותו ביטוי.

דוגמאות: (כל כתובת צריכה להיות מקודדת בקידוד)

המדינה היא אחת מהאפשרויות הבאות (ארצות הברית OR קנדה):
ga:country==United%20States,ga:country==Canada

משתמשי Firefox במערכות הפעלה (Windows או Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

AND

האופרטור AND מוגדר באמצעות נקודה ופסיק (;). לפניו מופיע האופרטור OR, ואפשר להשתמש בו כדי לשלב מאפיינים ומדדים באותו ביטוי.

דוגמאות: (כל כתובת צריכה להיות מקודדת בקידוד)

המדינה היא ארצות הברית וגם הדפדפן הוא Firefox:
ga:country==United%20States;ga:browser==Firefox

המדינה היא ארצות הברית וגם השפה לא מתחילה ב-'en':
ga:country==United%20States;ga:language!~^en.*

מערכת ההפעלה היא (Windows או Macintosh) והדפדפן הוא (Firefox או Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

המדינה היא ארצות הברית וגם מספר הסשנים גדול מ-5:
ga:country==United%20States;ga:sessions>5



פלח

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
אפשרות.

לפרטים מלאים על אופן ההגשה של בקשת פלח ב-Core Reporting API, מומלץ לעיין במדריך למפתחים בנושא פלחים.

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

מאפיינים ומדדים שמותרים לשימוש בפלחים.
לא ניתן להשתמש בכל המאפיינים והמדדים ליצירת פלחים. כדי לבדוק אילו מאפיינים ומדדים מותר להשתמש בפלחים, אפשר להיכנס לדף Dimensions and Metrics Explorer.


samplingLevel

samplingLevel=DEFAULT
אפשרות.
צריך להשתמש בפרמטר הזה כדי להגדיר את רמת הדגימה (כלומר, מספר הסשנים שישמשו לחישוב התוצאה) של שאילתת דיווח. הערכים המותרים תואמים לממשק האינטרנט, וכוללים:
  • DEFAULT – מחזירה תגובה באמצעות גודל דגימה שמאזן את המהירות והדיוק.
  • FASTER – מחזירה תגובה מהירה עם דגימה קטנה יותר.
  • HIGHER_PRECISION – מחזירה תגובה מדויקת יותר באמצעות דגימה גדולה, אבל זה עלול לגרום לתגובה איטית יותר.
אם לא תספקו נתונים, המערכת תשתמש ברמת הדגימה של DEFAULT.
בקטע דגימה מוסבר איך לחשב את אחוז הסשנים שבהם נעשה שימוש בשאילתה.

כלול-שורות ריקות

include-empty-rows=true
אפשרות.
ברירת המחדל היא TRUE. אם המדיניות מוגדרת כ-False, שורות שבהן כל ערכי המדדים הם אפס לא יוסרו מהתשובה. לדוגמה, אם תכלול יותר ממדד אחד בשאילתה, השורות יוסרו רק אם כל ערכי המדדים הם אפס. האפשרות הזו יכולה להיות שימושית כששולחים בקשה, כשמספר השורות החוקיות צפוי להיות קטן בהרבה מהמספר של ערכי המאפיינים הצפויים.

start-index

start-index=10
אפשרות.
אם לא תספקו כתובת, האינדקס ההתחלתי הוא 1. (האינדקסים של התוצאות מבוססים על 1. כלומר השורה הראשונה היא השורה 1 ולא שורה 0.) משתמשים בפרמטר הזה כמנגנון עימוד יחד עם הפרמטר max-results למצבים שבהם totalResults חורג מ-10,000 ורוצים לאחזר שורות שנוספו לאינדקס מ-10,001 ואילך.

max-results

max-results=100
אפשרות.
מספר השורות המקסימלי שאפשר לכלול בתשובה הזו. אפשר להשתמש באפשרות הזו בשילוב עם start-index כדי לאחזר קבוצת משנה של רכיבים, או להשתמש בה בלבד כדי להגביל את מספר הרכיבים שמוחזרים, החל מהראשון. אם לא הוזן max-results, השאילתה תחזיר את ערך ברירת המחדל המקסימלי של 1,000 שורות.
Analytics Core Reporting API מחזיר עד 10,000 שורות לכל בקשה, לא משנה כמה מבקשים. היא יכולה גם להחזיר פחות שורות מהבקשה, אם אין פלחי מאפיינים רבים כפי שציפית. לדוגמה, יש פחות מ-300 ערכים אפשריים למאפיין ga:country, ולכן כשמפלחים רק לפי מדינה, אי אפשר לקבל יותר מ-300 שורות, גם אם מגדירים ל-max-results ערך גבוה יותר.

output

output=dataTable
אפשרות.
משתמשים בפרמטר הזה כדי להגדיר את סוג הפלט של נתוני Analytics שיוחזרו בתגובה. הערכים המותרים הם:
  • json – יוצר בתגובה את מאפיין ברירת המחדל rows, שמכיל אובייקט JSON.
  • dataTable – הפונקציה יוצרת כפלט את המאפיין dataTable, שמכיל אובייקט טבלת נתונים. אפשר להשתמש באובייקט Data Table הזה ישירות עם תצוגות חזותיות של Google Graphs.
אם לא תספקו כתובת, ייעשה שימוש בתגובת ברירת המחדל של JSON.

Fields

fields=rows,columnHeaders(name,dataType)
אפשרות.

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

הפורמט של ערך פרמטר הבקשה בשדות מבוסס באופן רופף על תחביר XPath. בהמשך מופיע סיכום של התחביר הנתמך.

  • משתמשים ברשימה שמופרדת בפסיקים כדי לבחור שדות מרובים.
  • אפשר להשתמש ב-a/b כדי לבחור שדה b שמוצב בתוך שדה a. משתמשים בפונקציה a/b/c כדי לבחור שדה c שמוצב בתוך שדה b.
  • צריך להשתמש בבורר משנה כדי לבקש קבוצה של שדות משנה ספציפיים של מערכים או אובייקטים על ידי הוספת ביטויים בסוגריים "( )".
    לדוגמה: הפונקציה fields=columnHeaders(name,dataType) מחזירה רק את השדות name ו-dataType במערך columnHeaders. אפשר גם לציין שדה משנה יחיד, שבו fields=columnHeader(name) יהיה שווה-ערך ל-fields=columnHeader/name.

prettyPrint

prettyPrint=false
אפשרות.

מחזירה את התשובה בפורמט קריא לאנשים אם true. ערך ברירת המחדל: false.


quotaUser

quotaUser=4kh4r2h4
אפשרות.

המדיניות הזאת מאפשרת לאכוף מכסות לכל משתמש מאפליקציה בצד השרת, גם במקרים שבהם כתובת ה-IP של המשתמש לא ידועה. זה יכול לקרות, לדוגמה, באפליקציות שמפעילות משימות cron ב-App Engine בשמו של המשתמש. אפשר לבחור כל מחרוזת שרירותית שמזהה את המשתמש באופן ייחודי, אבל היא מוגבלת ל-40 תווים.

המדיניות הזו מבטלת את userIp אם תספקו את שניהם.


תשובה

אם הפעולה בוצעה ללא שגיאות, הבקשה מחזירה גוף תגובה עם מבנה ה-JSON שמוגדר בהמשך. אם הפרמטר output מוגדר ל-dataTable, אז הבקשה מחזירה גוף תגובה עם מבנה ה-JSON (Data Table) שמוגדר למטה.

הערה: המונח 'תוצאות' מתייחס לכל השורות שתואמות לשאילתה, ואילו 'תגובה' מתייחס לקבוצת השורות שמוחזרת בדף התוצאות הנוכחי. הם יכולים להיות שונים אם המספר הכולל של התוצאות גדול מגודל הדף של התגובה הנוכחית, כמו שמוסבר ב-itemsPerPage.

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

שדות תגובה

המאפיינים של מבנה גוף התגובה מוגדרים כך:

שם הנכס Value התיאור
kind string סוג המשאב. הערך הוא "analytics#gaData".
id string המזהה של תגובת הנתונים הזו.
query object האובייקט הזה מכיל את כל הערכים שהועברו כפרמטרים לשאילתה. המשמעות של כל שדה מוסברת בתיאור של הפרמטר של השאילתה התואם לו.
query.start-date string תאריך התחלה.
query.end-date string תאריך סיום.
query.ids string מזהה טבלה ייחודי.
query.dimensions[] list רשימה של מאפיינים לניתוח נתונים.
query.metrics[] list רשימה של מדדים לניתוח נתונים.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean ברירת המחדל היא TRUE. אם המדיניות מוגדרת כ-False, שורות שבהן כל ערכי המדדים הם אפס לא יוסרו מהתשובה.
query.sort[] list רשימת מדדים או מאפיינים שלגביהם הנתונים ממוינים.
query.filters string רשימה מופרדת בפסיקים של מסננים של מדדים או מאפיינים.
query.segment string פלח ב-Analytics.
query.start-index integer יצירת אינדקס.
query.max-results integer מספר התוצאות המקסימלי לדף.
startIndex integer אינדקס השורות הראשוני שצוין על ידי פרמטר השאילתה start-index. ערך ברירת המחדל הוא 1.
itemsPerPage integer מספר השורות המקסימלי שהתגובה יכולה להכיל, ללא קשר למספר השורות שהוחזרו בפועל. אם פרמטר השאילתה max-results צוין, הערך של itemsPerPage הוא הקטן מ-max-results או 10,000. ערך ברירת המחדל של itemsPerPage הוא 1,000.
totalResults integer המספר הכולל של השורות בתוצאת השאילתה, ללא קשר למספר השורות שהוחזרו בתגובה. בשאילתות שהתוצאה שלהן מספר גדול של שורות, הערך totalResults יכול להיות גדול מ-itemsPerPage. בקטע חלוקה לדפים יש הסבר נוסף על totalResults ועל itemsPerPage לשאילתות גדולות.
startDate string תאריך ההתחלה של שאילתת הנתונים, כפי שצוין בפרמטר start-date.
endDate string תאריך הסיום של שאילתת הנתונים, כפי שצוין בפרמטר end-date.
profileInfo object מידע על התצוגה המפורטת (הפרופיל) שעבורה התבקשו הנתונים. נתוני התצוגה המפורטת (פרופיל) זמינים דרך ממשק ה-API לניהול של Google Analytics.
profileInfo.profileId string מזהה תצוגה (פרופיל), למשל 1174.
profileInfo.accountId string מספר החשבון שאליו שייכת התצוגה המפורטת (הפרופיל) הזו, למשל 30481.
profileInfo.webPropertyId string מזהה נכס אינטרנט שאליו שייכת התצוגה המפורטת (פרופיל) הזו, למשל UA-30481-1.
profileInfo.internalWebPropertyId string מזהה פנימי של נכס האינטרנט שאליו שייכת התצוגה המפורטת (פרופיל) הזו, כמו UA-30481-1.
profileInfo.profileName string שם התצוגה המפורטת (פרופיל).
profileInfo.tableId string מזהה טבלה לתצוגה מפורטת (profile), הכולל את המחרוזת 'ga:' ולאחר מכן את מזהה התצוגה המפורטת (profile).
containsSampledData boolean הערך הוא True אם התשובה מכילה נתונים שנדגמו.
sampleSize string מספר הדגימות ששימשו לחישוב הנתונים שנדגמו.
sampleSpace string הגודל הכולל של שטח הדגימה. מציין את הגודל הכולל של שטח הדגימה, שממנו נבחרו הדגימות.
columnHeaders[] list כותרות של עמודות שמציגות שמות של מאפיינים ואחריהם שמות המדדים. סדר המאפיינים והמדדים זהה לזה שצוין בבקשה באמצעות הפרמטרים metrics ו-dimensions. מספר הכותרות הוא מספר המאפיינים + מספר המדדים.
columnHeaders[].name string שם המאפיין או המדד.
columnHeaders[].columnType string סוג עמודה. 'dimension' או 'METRIC'.
columnHeaders[].dataType string סוג נתונים. בכותרות העמודות של המאפיינים יש רק STRING כסוג הנתונים. כותרות עמודות של מדדים כוללות סוגי נתונים של ערכים, כמו INTEGER, PERCENT, TIME, CURRENCY, FLOAT וכו'. מידע נוסף זמין בתגובת ה-API של המטא-נתונים לכל סוגי הנתונים האפשריים.
totalsForAllResults object הערכים הכוללים של המדדים המבוקשים כצמדי מפתח/ערך של שמות וערכים של מדדים. הסדר של הסכומים הכוללים של המדדים זהה לסדר המדדים שצוין בבקשה.
rows[] list שורות של נתוני Analytics, שבהן כל שורה מכילה רשימה של ערכי מאפיינים ולאחר מכן ערכי המדדים. סדר המאפיינים והמדדים זהה לסדר שצוין בבקשה. בכל שורה יש רשימה של N שדות, כאשר N = מספר המאפיינים + מספר המדדים.
JSON (טבלת נתונים)
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

שדות תגובה

המאפיינים של מבנה גוף התגובה מוגדרים כך:

שם הנכס Value התיאור
kind string סוג המשאב. הערך הוא "analytics#gaData".
id string המזהה של תגובת הנתונים הזו.
query object האובייקט הזה מכיל את כל הערכים שהועברו כפרמטרים לשאילתה. המשמעות של כל שדה מוסברת בתיאור של הפרמטר של השאילתה התואם לו.
query.start-date string תאריך התחלה.
query.end-date string תאריך סיום.
query.ids string מזהה טבלה ייחודי.
query.dimensions[] list רשימה של מאפיינים לניתוח נתונים.
query.metrics[] list רשימה של מדדים לניתוח נתונים.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean ברירת המחדל היא TRUE. אם המדיניות מוגדרת כ-False, שורות שבהן כל ערכי המדדים הם אפס לא יוסרו מהתשובה.
query.sort[] list רשימת מדדים או מאפיינים שלגביהם הנתונים ממוינים.
query.filters string רשימה מופרדת בפסיקים של מסננים של מדדים או מאפיינים.
query.segment string פלח ב-Analytics.
query.start-index integer יצירת אינדקס.
query.max-results integer מספר התוצאות המקסימלי לדף.
startIndex integer אינדקס השורות הראשוני שצוין על ידי פרמטר השאילתה start-index. ערך ברירת המחדל הוא 1.
itemsPerPage integer מספר השורות המקסימלי שהתגובה יכולה להכיל, ללא קשר למספר השורות שהוחזרו בפועל. אם פרמטר השאילתה max-results צוין, הערך של itemsPerPage הוא הקטן מ-max-results או 10,000. ערך ברירת המחדל של itemsPerPage הוא 1,000.
totalResults integer המספר הכולל של השורות בתוצאת השאילתה, ללא קשר למספר השורות שהוחזרו בתגובה. בשאילתות שהתוצאה שלהן מספר גדול של שורות, הערך totalResults יכול להיות גדול מ-itemsPerPage. בקטע חלוקה לדפים יש הסבר נוסף על totalResults ועל itemsPerPage לשאילתות גדולות.
startDate string תאריך ההתחלה של שאילתת הנתונים, כפי שצוין בפרמטר start-date.
endDate string תאריך הסיום של שאילתת הנתונים, כפי שצוין בפרמטר end-date.
profileInfo object מידע על התצוגה המפורטת (הפרופיל) שעבורה התבקשו הנתונים. נתוני התצוגה המפורטת (פרופיל) זמינים דרך ממשק ה-API לניהול של Google Analytics.
profileInfo.profileId string מזהה תצוגה (פרופיל), למשל 1174.
profileInfo.accountId string מספר החשבון שאליו שייכת התצוגה המפורטת (הפרופיל) הזו, למשל 30481.
profileInfo.webPropertyId string מזהה נכס אינטרנט שאליו שייכת התצוגה המפורטת (פרופיל) הזו, למשל UA-30481-1.
profileInfo.internalWebPropertyId string מזהה פנימי של נכס האינטרנט שאליו שייכת התצוגה המפורטת (פרופיל) הזו, כמו UA-30481-1.
profileInfo.profileName string שם התצוגה המפורטת (פרופיל).
profileInfo.tableId string מזהה טבלה לתצוגה מפורטת (profile), הכולל את המחרוזת 'ga:' ולאחר מכן את מזהה התצוגה המפורטת (profile).
containsSampledData boolean הערך הוא True אם התשובה מכילה נתונים שנדגמו.
sampleSize string מספר הדגימות ששימשו לחישוב הנתונים שנדגמו.
sampleSpace string הגודל הכולל של שטח הדגימה. מציין את הגודל הכולל של שטח הדגימה, שממנו נבחרו הדגימות.
columnHeaders[] list כותרות של עמודות שמציגות שמות של מאפיינים ואחריהם שמות המדדים. סדר המאפיינים והמדדים זהה לזה שצוין בבקשה באמצעות הפרמטרים metrics ו-dimensions. מספר הכותרות הוא מספר המאפיינים + מספר המדדים.
columnHeaders[].name string שם המאפיין או המדד.
columnHeaders[].columnType string סוג עמודה. 'dimension' או 'METRIC'.
columnHeaders[].dataType string סוג נתונים. בכותרות העמודות של המאפיינים יש רק STRING כסוג הנתונים. כותרות עמודות של מדדים כוללות סוגי נתונים של ערכים, כמו INTEGER, PERCENT, TIME, CURRENCY, FLOAT וכו'. מידע נוסף זמין בתגובת ה-API של המטא-נתונים לכל סוגי הנתונים האפשריים.
totalsForAllResults object הערכים הכוללים של המדדים המבוקשים כצמדי מפתח/ערך של שמות וערכים של מדדים. הסדר של הסכומים הכוללים של המדדים זהה לסדר המדדים שצוין בבקשה.
dataTable object אובייקט של Data Table (טבלת נתונים), שאפשר להשתמש בו יחד עם GoogleCharts.
dataTable.cols[] list רשימה של תיאורי עמודות למאפיינים ואחריהם מדדים. סדר המאפיינים והמדדים זהה לזה שצוין בבקשה באמצעות הפרמטרים metrics ו-dimensions. מספר העמודות הוא מספר המאפיינים + מספר המדדים.
dataTable.cols[].id string מזהה שיכול לשמש להפניה לעמודה ספציפית (כחלופה לשימוש באינדקסים של עמודות). מזהה המאפיין או המדד משמש להגדרת הערך הזה.
dataTable.cols[].label string תווית לעמודה (שיכולה להופיע בתצוגה החזותית). מזהה המאפיין או המדד משמש להגדרת הערך הזה.
dataTable.cols[].type string סוג הנתונים בעמודה הזו.
dataTable.rows[] list שורות הנתונים של Analytics בפורמט 'טבלת נתונים', שבו כל שורה היא אובייקט שמכיל רשימה של ערכי תאים של מאפיינים ולאחר מכן ערכים. סדר המאפיינים והמדדים זהה לסדר שצוין בבקשה. לכל תא יש רשימה של N שדות, כאשר N = מספר המאפיינים + מספר המדדים.

קודי שגיאות

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

רוצה לנסות?

אפשר לנסות שאילתות על ממשק ה-API הראשי לדיווח.

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

  • כדי לשלוח בקשה לגבי נתונים פעילים ולראות את התשובה בפורמט JSON, אפשר לנסות את השיטה analytics.data.ga.get ב-Google Data APIs Explorer.

דגימות

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

אפשר לציין את רמת הדגימה של בקשה באמצעות הגדרת הפרמטר samplingLevel.

אם תגובה של Core Reporting API מכילה נתונים שנדגמו, שדה התגובה containsSampledData יהיה true. בנוסף, שני נכסים יספקו מידע על רמת הדגימה לשאילתה: sampleSize ו-sampleSpace. בעזרת שני הערכים האלה אפשר לחשב את אחוז הסשנים שבהם נעשה שימוש בשאילתה. לדוגמה, אם הערך של sampleSize הוא 201,000 והערך של sampleSpace הוא 220,000, הדוח יתבסס על (201,000 חלקי 220,000) * 100 = 91.36% מהביקורים.

בקטע דגימה מפורט תיאור כללי של דגימה ואופן השימוש בה ב-Google Analytics.


טיפול בתוצאות של נתונים גדולים

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

הקטנת מאפיינים לכל שאילתה

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

פיצול השאילתה לפי טווח תאריכים

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

חלוקה לדפים

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

שימוש ב-gzip

דרך קלה ונוחה לצמצם את רוחב הפס הדרוש לכל בקשה היא להפעיל דחיסת gzip. למרות שהפעולה הזו דורשת זמן נוסף במעבד (CPU) כדי לבטל את הדחיסה של התוצאות, בזכות הפשרה עם העלויות של הרשת היא בדרך כלל משתלמת מאוד. כדי לקבל תגובה בקידוד gzip, עליך לבצע שני דברים: להגדיר כותרת Accept-Encoding ולשנות את סוכן המשתמש כך שיכיל את המחרוזת gzip. דוגמה לכותרות HTTP בפורמט תקין כדי להפעיל דחיסת gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)