במסמך הזה תמצאו את ההנחיות המלאות לשאילתות ולתשובות בגרסה 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 | רמת הדגימה הרצויה. ערכים מותרים:
|
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 |
הצגת תוצאות שבהן הזמן בדף הוא 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).
- אורך מקסימלי של 128 תווים — ביטויים רגולריים שאורכם יותר מ-128 תווים יחזירו קוד סטטוס
שילוב מסננים
ניתן לשלב מסננים באמצעות לוגיקה בוליאנית 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
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
הזה ישירות עם תצוגות חזותיות של Google Graphs.
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.
{
"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 . |
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 |
מזהה טבלה לתצוגה מפורטת (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 = מספר המאפיינים + מספר המדדים. |
{
"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 . |
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 |
מזהה טבלה לתצוגה מפורטת (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)