זהו מדריך למפתחים בנושא Analytics Reporting API v4. למידע מפורט על ה-API, ראו הפניית API.
דוחות
Analytics Reporting API v4 מספק את השיטה batchGet כדי לגשת למשאב Reports.
בקטעים הבאים מתוארים המבנה של גוף הבקשה עבור batchGet
ואת המבנה של גוף התגובה מ-batchGet
.
גוף הבקשה
כדי להשתמש ב-Analytics Reporting API v4 כדי לבקש נתונים, עליך ליצור אובייקט ReportRequest, שמכיל את הדרישות המינימליות הבאות:
- מזהה חוקי של תצוגה מפורטת לשדה viewId.
- לפחות ערך חוקי אחד בשדה dateRanges.
- לפחות רשומה חוקית אחת בשדה metrics.
כדי לאתר מזהה תצוגה מפורטת,
אפשר להריץ שאילתה על השיטה
סיכומי החשבון
או להשתמש ב-Account Explorer.
אם לא ציינת טווח תאריכים, טווח התאריכים המוגדר כברירת מחדל הוא: {"startDate": "7daysAgo", "endDate": "yesterday"}
.
הנה בקשה לדוגמה עם שדות החובה המינימליים:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
השיטה batchGet
מקבלת עד חמישה אובייקטים מסוג ReportRequest. כל הבקשות צריכות לכלול את אותם מאפייני
dateRange
,
viewId
,
segments
,
samplingLevel
וcohortGroup
.
גוף התשובה
גוף התגובה לבקשת ה-API הוא מערך של אובייקטים מסוג Report. מבנה הדוח מוגדר באובייקט ColumnHeader שמתאר את המאפיינים והמדדים ואת סוגי הנתונים שלהם בדוח. ערכי המאפיינים והמדדים מצוינים בשדה data.
הנה דוגמה לתגובה לבקשה לדוגמה שלמעלה:
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
מדדים
מדדים הם אומדנים כמותיים. לכל בקשה נדרש לפחות אובייקט Metric אחד.
בדוגמה הבאה, המדד Sessions
מסופק לשיטה batchGet
כדי לקבל את המספר הכולל של סשנים בטווח התאריכים שצוין:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
תוכל להשתמש בסייר המאפיינים והמדדים או ב-Metadata API כדי לקבל את רשימת המאפיינים והמדדים הזמינים.
סינון
כששולחים בקשה batchGet
, אפשר לבקש ממנה להחזיר רק מדדים שעומדים בקריטריונים ספציפיים. כדי לסנן מדדים, בגוף הבקשה צריך לציין MetricFilterClauses אחד או יותר ובכל MetricFilterClause
מגדירים MetricFilters אחד או יותר.
בכל MetricFilter
, צריך לציין את הערכים הבאים:
metricName
not
operator
comparisonValue
הפונקציה {metricName}
מייצגת את המדד, {operator}
את operator
ואת {comparisonValue}
ה-comparisonValue
. לאחר מכן המסנן פועל באופן הבא:
if {metricName} {operator} {comparisonValue}
return the metric
אם מציינים את הערך true
עבור not
, המסנן פועל באופן הבא:
if {metricName} {operator} {comparisonValue}
do not return the metric
בדוגמה הבאה, batchGet
מחזיר רק צפיות בדף שהערך שלהן גדול מ-2:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
ביטויים
ביטוי של מדד הוא ביטוי מתמטי שמגדירים במדדים קיימים. הוא פועל כמו מדדים מחושבים דינמיים. אפשר להגדיר כינוי לייצוג ביטוי המדד, לדוגמה:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
סידור הסרטונים
כדי למיין את התוצאות לפי ערך של מדד:
- מזינים את השם או את כתובת האימייל החלופית באמצעות השדה
fieldName
. - מציינים את סדר המיון (
ASCENDING
אוDESCENDING
) באמצעות השדהsortOrder
.
בדוגמה הבאה, batchGet
מחזירה את המדדים שממוינים תחילה לפי ביקורים ולאחר מכן לפי צפיות בדף בסדר יורד:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
מאפיינים
המאפיינים מתארים מאפיינים של המשתמשים שלך, הפעילויות שלהם באתר והפעולות שהם נקטו.
לדוגמה, המאפיין 'עיר' מתאר מאפיין של פעילויות באתר ומציין את העיר ('פריז' או 'ניו יורק') שממנה הגיעה כל פעילות באתר.
בבקשת batchGet
, ניתן לציין אפס אובייקטים של מאפיין או יותר, לדוגמה:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
סינון
כששולחים בקשה batchGet
, אפשר לבקש ממנה להחזיר רק מאפיינים שעומדים בקריטריונים ספציפיים. כדי לסנן מאפיינים, בגוף הבקשה מציינים DimensionsFilterClauses אחד או יותר ובכל DimensionsFilterClause
מגדירים DimensionsFilters אחד או יותר.
בכל DimensionsFilters
, צריך לציין את הערכים הבאים:
dimensionName
not
operator
expressions
caseSensitive
הפונקציה {dimensionName}
מייצגת את המאפיין, {operator}
את operator
ו-{expressions}
את expressions
. לאחר מכן המסנן פועל באופן הבא:
if {dimensionName} {operator} {expressions}
return the dimension
אם מציינים את הערך true
עבור not
, המסנן פועל באופן הבא:
if {dimensionName} {operator} {expressions}
do not return the dimension
בדוגמה הבאה, batchGet
מחזיר צפיות בדפים וסשנים בדפדפן Chrome:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
סידור הסרטונים
כדי למיין את התוצאות לפי ערך של מאפיין:
- מציינים את השם דרך השדה
fieldName
. - צריך לציין את סדר המיון (
ASCENDING
אוDESCENDING
) באמצעות השדהsortOrder
.
לדוגמה, השדה batchGet
הבא מחזיר את המאפיינים שממוינים לפי מדינה ואז לפי דפדפן:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
קטגוריות היסטוגרמה
למאפיינים עם ערכים במספרים שלמים, קל יותר להבין את המאפיינים שלהם על ידי סיווג הערכים שלהם לטווחים. משתמשים בשדה histogramBuckets
כדי להגדיר את הטווחים של הקטגוריות המתקבלות, ולציין את HISTOGRAM_BUCKET
כסוג ההזמנה. לדוגמה:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
טווחי תאריכים מרובים
ב-Google Analytics Reporting API v4 אפשר לקבל נתונים בכמה טווחי תאריכים בבקשה אחת. אם הבקשה מציינת טווח תאריכים אחד או שניים, הנתונים מוחזרים באובייקט dateRangeValue, לדוגמה:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
הזמנת דלתא
כשמבקשים ערכי מדדים בשני טווחי תאריכים, ניתן לך לסדר את התוצאות לפי ההפרש בין ערכי המדד בטווחי התאריכים, לדוגמה:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
התנהגות המאפיין 'תאריך'
אם מבקשים מאפיין שקשור ל-תאריך או שעה, האובייקט DateRangeValue יכיל רק ערכים של תאריכים שנמצאים בטווחים התואמים. כל שאר הערכים שאינם בטווחי התאריכים שצוינו יהיו 0
.
לדוגמה, נניח בקשה למאפיין ga:date
ולמדד ga:sessions
בשני טווחי תאריכים: ינואר ופברואר.
בתגובה לנתונים המבוקשים בינואר, הערכים בפברואר יהיו 0
, ובתגובה לנתונים המבוקשים בפברואר, הערכים בינואר יהיו 0
.
דוח לחודש ינואר
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
דוח לחודש פברואר
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
פלחים
על מנת לבקש קבוצת משנה של הנתונים ב-Analytics, צריך להשתמש בפלחים. לדוגמה, ניתן לך להגדיר משתמשים ממדינה או מעיר מסוימת בפלח אחד, ומשתמשים שביקרו בחלק ספציפי של האתר בפלח אחר. המסננים מחזירים רק שורות שעומדות בתנאי, ואילו הפלחים מחזירים קבוצת משנה של משתמשים, סשנים או אירועים שעומדים בתנאים שמכילים את הפלחים.
כששולחים בקשה באמצעות פלחים, צריך לוודא את הפרטים הבאים:
- כל ReportRequest בשיטת
batchGet
חייב להכיל הגדרות פלחים זהות. - מוסיפים את
ga:segment
לרשימת המאפיינים.
למשל:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
בקטע טעימות תוכלו לראות עוד בקשות לדוגמה עם פלחים.
מזהה הפלח
משתמשים בשדה segmentId
כדי לבקש פלחים.
לא ניתן להשתמש גם ב-segmentId
וגם ב-dynamicSegment
כדי לבקש פלחים.
למשל:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
דגימות
דגימה יכולה להשפיע על תוצאות הנתונים, וזו סיבה נפוצה לכך שהערכים שמוחזרים מה-API לא תואמים לממשק האינטרנט. משתמשים בשדה samplingLevel
כדי להגדיר את גודל הדגימה הרצוי.
- כדי לקבל תגובה מהירה עם דגימה קטנה יותר, צריך להגדיר את הערך
SMALL
. - יש להגדיר את הערך כ-
LARGE
לתגובה מדויקת יותר אבל איטית יותר. - צריך להגדיר את הערך
DEFAULT
בתגובה ששומרת על איזון בין המהירות לדיוק.
למשל:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
אם דוח מכיל נתונים שנדגמו, הגרסה 4 של Analytics Reporting API מחזירה את השדות samplesReadCounts
ו-samplingSpaceSizes
.
אם התוצאות לא נדגמו, השדות האלה לא יוגדרו.
למטה מוצגת תגובה לדוגמה שמכילה נתונים שנדגמו מבקשה עם שני טווחי תאריכים. התוצאות חושבו מכמעט 500,000 דגימות בשטח דגימה של כ-15 מיליון סשנים:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
חלוקה לדפים
ב-Analytics Reporting API v4, המערכת משתמשת בשדות pageToken
ו-pageSize
כדי לעבור לדפים עם תוצאות תשובות שמתפרשות על פני מספר דפים. מקבלים pageToken
מהפרמטר nextPageToken
בתגובה לבקשה של reports.batchGet
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
השלב הבא
אחרי שהסברתם את העקרונות הבסיסיים של יצירת דוח, נציג את התכונות המתקדמות של API v4.