במסמך הזה מפורטת ההפניה המלאה לשאילתות ולתגובות בגרסה 3.0 של ממשק ה-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. לוחצים על השם של כל פרמטר כדי לקבל תיאור מפורט.
שם | תמורה לכסף | חובה | סיכום |
---|---|---|---|
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 | רמת הדגימה הרצויה. ערכים מותרים:
|
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
ga:
עם
מזהה התצוגה המפורטת (הפרופיל) ב-Analytics. אפשר לאחזר את מזהה התצוגה המפורטת (פרופיל) באמצעות השיטה analytics.management.profiles.list
, שמספקת את id
במשאב 'תצוגה מפורטת (פרופיל)' ב-Google Analytics Management API.
תאריך התחלה
start-date=2009-04-20
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
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 |
החזר תוצאות שבהן משך הזמן בדף הוא בדיוק עשר שניות:filters=ga:timeOnPage%3D%3D10 |
!= |
לא שווה ל- | !%3D |
החזר תוצאות שבהן משך הביקור בדף הוא לא עשר שניות:filters=ga:timeOnPage!%3D10 |
> |
גדול מ- | %3E |
החזר תוצאות שבהן משך הביקור בדף ארוך ממש מעשר שניות:filters=ga:timeOnPage%3E10 |
< |
פחות מ- | %3C |
החזר תוצאות שבהן משך הביקור בדף הוא פחות מעשר שניות:filters=ga:timeOnPage%3C10 |
>= |
גדול מ- או שווה ל- | %3E%3D |
הצגת תוצאות שבהן משך הביקור בדף הוא עשר שניות או יותר: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 כרגיל. - תווים שמורים — יש לסמן בתו בריחה (escape) את הנקודה-פסיק והפסיק כאשר הם מופיעים בביטוי:
\;
נקודה ופסיק- פסיק
\,
- ביטויים רגולריים — אפשר גם להשתמש בביטויים רגולריים בביטויי סינון, באמצעות האופרטורים
=~
ו-!~
. התחביר שלהם דומה לביטויים רגולריים של Perl, והם כוללים את הכללים הנוספים הבאים:- אורך מקסימלי של 128 תווים – ביטויים רגולריים שאורכם יותר מ-128 תווים יניבו קוד סטטוס
400 Bad Request
שיוחזר מהשרת. - תלות באותיות רישיות — התאמה של ביטויים רגולריים היא לא תלוית אותיות רישיות.
- אורך מקסימלי של 128 תווים – ביטויים רגולריים שאורכם יותר מ-128 תווים יניבו קוד סטטוס
שילוב מסננים
אפשר לשלב מסננים באמצעות לוגיקה בוליאנית OR
ו-AND
. כך
אפשר להרחיב ביעילות את מגבלת 128 התווים של ביטוי סינון.
או
האופרטור OR
מוגדר באמצעות פסיק (,
).
הוא מקבל קדימות על פני האופרטור AND
ולא ניתן להשתמש בו
כדי לשלב מאפיינים ומדדים באותו ביטוי.
דוגמאות: (כל כתובת URL צריכה להיות מקודדת בקידוד URL)
המדינה היא אחת (ארצות הברית OR קנדה):
ga:country==United%20States,ga:country==Canada
משתמשי Firefox במערכות ההפעלה (Windows או Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh
וגם
האופרטור AND
מוגדר באמצעות נקודה ופסיק (;
).
לפניו מופיע האופרטור OR
, ואפשר להשתמש בו כדי לשלב
מאפיינים ומדדים באותו ביטוי.
דוגמאות: (כל כתובת URL צריכה להיות מקודדת בקידוד URL)
המדינה היא ארצות הברית והדפדפן הוא 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
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 שורות.ga:country
, לכן כשמפלחים רק
לפי מדינה, לא ניתן לקבל יותר מ-300 שורות, גם אם
מגדירים את max-results
לערך גבוה יותר.output
output=dataTable
json
– מפיקה בתגובה את מאפיין ברירת המחדלrows
, שמכיל אובייקט JSON.dataTable
– מפיקה בתגובה מאפייןdataTable
שמכיל אובייקט מסוג Data Table. אפשר להשתמש באובייקטData Table
הזה ישירות עם תצוגות חזותיות של GoogleCharts.
Fields
fields=rows,columnHeaders(name,dataType)
מציין אילו שדות להחזיר בתגובה חלקית. אם משתמשים
רק בקבוצת משנה של השדות בתגובת ה-API, אפשר להשתמש
בפרמטר fields
כדי לציין אילו שדות לכלול.
הפורמט של ערך הפרמטר של הבקשה בשדות מבוסס באופן רופף על תחביר XPath. בהמשך מופיע סיכום של התחביר הנתמך.
- משתמשים ברשימה שמופרדת בפסיקים כדי לבחור כמה שדות.
- משתמשים ב-
a/b
כדי לבחור שדה b שנמצא בתוך שדה א'. משתמשים ב-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.
{
"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,
...
}
]
}
שדות תשובה
המאפיינים של מבנה גוף התגובה מוגדרים כך:
שם הנכס | תמורה לכסף | תיאור |
---|---|---|
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 . |
selfLink |
string |
קישור לדף התוצאות הזה של שאילתת הנתונים הזו. |
previousLink |
string |
קישור לדף התוצאות הקודם של שאילתת הנתונים הזו. |
nextLink |
string |
קישור לדף הבא של התוצאות עבור שאילתת הנתונים הזו. |
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 |
מזהה טבלה לתצוגה (פרופיל), הכולל את 'ga:' ואחריו את מזהה התצוגה המפורטת (פרופיל). |
containsSampledData |
boolean |
True אם התשובה מכילה נתונים שנדגמו. |
sampleSize |
string |
מספר הדגימות ששימשו לחישוב הנתונים שנדגמו. |
sampleSpace |
string |
הגודל הכולל של שטח הדגימה. מציין את הגודל הכולל הזמין של שטח הדגימה, שממנו נבחרו הדוגמאות. |
columnHeaders[] |
list |
כותרות של עמודות עם רשימה של שמות המאפיינים ושמות המדדים. סדר המאפיינים והמדדים זהה לזה שצוין בבקשה באמצעות הפרמטרים metrics ו-dimensions . מספר הכותרות הוא מספר המאפיינים + מספר המדדים. |
columnHeaders[].name |
string |
שם המאפיין או המדד. |
columnHeaders[].columnType |
string |
סוג עמודה. השדה 'מאפיינים' או 'METRIC'. |
columnHeaders[].dataType |
string |
סוג נתונים. בכותרות העמודות של המאפיינים יש רק
STRING כסוג הנתונים. בכותרות העמודות של המדדים יש סוגי נתונים של ערכים, כמו INTEGER , PERCENT , TIME , CURRENCY , FLOAT וכו'. בתגובת ה-API של המטא-נתונים אפשר לראות את כל סוגי הנתונים האפשריים.
|
totalsForAllResults |
object |
הערכים הכוללים של המדדים המבוקשים כצמדי מפתח/ערך של שמות וערכים. הסדר של הסכומים הכוללים של המדדים זהה לסדר המדדים שצוין בבקשה. |
rows[] |
list |
שורות של נתוני Analytics, שבהן כל שורה מכילה רשימה של ערכי מאפיינים ואחריה ערכי המדדים. סדר המאפיינים והמדדים זהה לסדר שצוין בבקשה. בכל שורה יש רשימה של N שדות, כאשר N = מספר המאפיינים + מספר המדדים. |
{
"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,
...
}
]
}
שדות תשובה
המאפיינים של מבנה גוף התגובה מוגדרים כך:
שם הנכס | תמורה לכסף | תיאור |
---|---|---|
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 . |
selfLink |
string |
קישור לדף התוצאות הזה של שאילתת הנתונים הזו. |
previousLink |
string |
קישור לדף התוצאות הקודם של שאילתת הנתונים הזו. |
nextLink |
string |
קישור לדף הבא של התוצאות עבור שאילתת הנתונים הזו. |
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 |
מזהה טבלה לתצוגה (פרופיל), הכולל את 'ga:' ואחריו את מזהה התצוגה המפורטת (פרופיל). |
containsSampledData |
boolean |
True אם התשובה מכילה נתונים שנדגמו. |
sampleSize |
string |
מספר הדגימות ששימשו לחישוב הנתונים שנדגמו. |
sampleSpace |
string |
הגודל הכולל של שטח הדגימה. מציין את הגודל הכולל הזמין של שטח הדגימה, שממנו נבחרו הדוגמאות. |
columnHeaders[] |
list |
כותרות של עמודות עם רשימה של שמות המאפיינים ושמות המדדים. סדר המאפיינים והמדדים זהה לזה שצוין בבקשה באמצעות הפרמטרים metrics ו-dimensions . מספר הכותרות הוא מספר המאפיינים + מספר המדדים. |
columnHeaders[].name |
string |
שם המאפיין או המדד. |
columnHeaders[].columnType |
string |
סוג עמודה. השדה 'מאפיינים' או 'METRIC'. |
columnHeaders[].dataType |
string |
סוג נתונים. בכותרות העמודות של המאפיינים יש רק
STRING כסוג הנתונים. בכותרות העמודות של המדדים יש סוגי נתונים של ערכים, כמו INTEGER , PERCENT , TIME , CURRENCY , FLOAT וכו'. בתגובת ה-API של המטא-נתונים אפשר לראות את כל סוגי הנתונים האפשריים.
|
totalsForAllResults |
object |
הערכים הכוללים של המדדים המבוקשים כצמדי מפתח/ערך של שמות וערכים. הסדר של הסכומים הכוללים של המדדים זהה לסדר המדדים שצוין בבקשה. |
dataTable |
object |
אובייקט של Data Table (טבלת נתונים), שאפשר להשתמש בו בשילוב עם Google Charts. |
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 מחזיר קוד שגיאה ותיאור.
כל אפליקציה שמשתמשת ב-API של Analytics צריכה להטמיע לוגיקה מתאימה לטיפול בשגיאות. למידע נוסף על קודי השגיאה ואופן הטיפול בהם, קראו את
מדריך העזר לתשובות שגיאה.
כדאי לנסות!
אתם יכולים לנסות שאילתות ב-Core Reporting API.
-
כדי לראות את השילובים החוקיים של מדדים ומאפיינים בשאילתה, מזינים ערכים לדוגמה לפרמטרים ב-Query Explorer. התוצאות של השאילתה לדוגמה מוצגות כטבלה עם ערכים לכל המדדים והמאפיינים שצוינו.
-
כדי לשלוח בקשה לנתונים בזמן אמת ולראות את התגובה בפורמט JSON, אפשר לנסות את השיטה
analytics.data.ga.get
ב-Google Data APIs Explorer.
דגימות
מערכת Google Analytics מחשבת שילובים מסוימים של מאפיינים ומדדים בזמן אמת. כדי להחזיר את הנתונים בזמן סביר, מערכת Google Analytics עשויה לעבד רק דגימה מהנתונים.
כדי לציין את רמת הדגימה לבקשה, מגדירים את הפרמטר samplingLevel.
אם התשובה מה-Core Reporting API מכילה נתונים שנדגמו, שדה התגובה containsSampledData
יהיה true
.
בנוסף, 2 נכסים יספקו מידע על רמת הדגימה לשאילתה: 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)