במדריך הזה מפורטות הנחיות להעברת ה-Core Reporting API גרסה 3 אל Analytics Reporting API v4.
מבוא
כדי לנצל את התכונות החדשות שהושקו ב-Analytics Reporting API v4, עליך להעביר את הקוד לשימוש ב-API. כדי להקל על ההעברה, במדריך הזה מוצגות בקשות ב-Core Reporting API v3, ובקשות מקבילות ב-Analytics Reporting API v4.
העברה ל-Python
אם אתם מפתחי Python, תוכלו להשתמש בספריית העזרה של GAV4 ב-GitHub כדי להמיר בקשות של Google Analytics Core Reporting API v3 לבקשות של Analytics Reporting API v4
נקודות קצה (endpoints)
ל-Core Reporting API v3 ול-Analytics Reporting API v4 יש נקודות קצה ושיטות HTTP שונות:
נקודת קצה 3, גרסה 3
GET https://www.googleapis.com/analytics/v3/data/ga
נקודת קצה (endpoint) גרסה 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
בדוגמאות הבאות משווים בין בקשה בגרסה 3 לבקשה המקבילה בגרסה 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
ספריות לקוח ושירות Discovery
אם אתם משתמשים ב-Python, ב-JavaScript או בספריית לקוח אחרת שמסתמכת על Google Discovery Service, עליכם לספק את המיקום של מסמך הגילוי של ה-Reporting API v4.
Python
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
JavaScript
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
ספריות הלקוח של Java ו-PHP מוכנות מראש, אבל אפשר ליצור אותן באמצעות שירות הגילוי ומחולל ממשקי ה-API של Google.
בקשות
בחומר העזר בנושא API v4 מתואר בפירוט המבנה של גוף הבקשה. בקטעים הבאים מתוארת ההעברה של פרמטרים של בקשה ב-v3 לפרמטרים של בקשה בגרסה 4.
הצגת המזהים
בגרסה 3, פרמטר ids
שמקבל 'מזהה טבלה' הוא בפורמט ga:XXXX
, כאשר XXXX
הוא מזהה התצוגה המפורטת (הפרופיל). בגרסה 4, מזהה התצוגה המפורטת (הפרופיל) מצוין בשדה viewId
בגוף הבקשה.
בדוגמאות הבאות משווים בין הפרמטר ids
בבקשת v3 לבין השדה viewId
בבקשה בגרסה v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
טווחי תאריכים
ב-Analytics Reporting API v4 אפשר לציין כמה טווחי תאריכים בבקשה אחת. השדה dateRanges
מציג רשימה של אובייקטים מסוג DateRange.
בגרסה 3, משתמשים בפרמטרים start-date
ו-end-date
כדי לציין טווח תאריכים בבקשה.
בדוגמאות הבאות משווים בין הפרמטרים start-date
ו-end-date
בבקשת v3 לבין השדה dateRanges
בבקשה של v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
מדדים
הפרמטר metrics
בגרסה 3 תואם לשדה metrics
בגרסה 4, שכולל רשימה של אובייקטים Metric.
בדוגמאות הבאות משווים בין הפרמטרים metrics
בבקשת v3 לבין השדה metrics
בבקשת v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
מאפיינים
הפרמטר dimensions
v3 תואם לשדה dimensions
v4, שמקבל רשימה של אובייקטים מסוג מאפיינים.
בדוגמאות הבאות משווים בין הפרמטרים dimensions
בבקשת v3 לבין השדה dimensions
בבקשת v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
מיון
הפרמטר sort
בגרסה 3 מקביל לשדה v4 של orderBys
, שמקבל רשימה של אובייקטים מסוג OrderBy.
בגרסה 4, כדי למיין את התוצאות לפי ערך של מאפיין או מדד:
- מספקים את השם או הכינוי שלו דרך השדה
fieldName
. - מציינים את סדר המיון (
ASCENDING
אוDESCENDING
) באמצעות השדהsortOrder
.
בדוגמאות הבאות משווים בין הפרמטר sort
בבקשה ב-v3 לבין השדה orderBy
בבקשת v4. שתיהן ממיינות את המשתמשים בסדר יורד וגם מקורות לפי סדר אלפביתי:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
רמת הדגימה
הפרמטר samplingLevel
של גרסה 3 תואם לשדה v4 samplingLevel
. בגרסה 3, ערכי samplingLevel
הקבילים הם FASTER
, HIGHER_PRECISION
ו-DEFAULT
. בגרסה 4, ערכי samplingLevel
הקבילים הם SMALL
, LARGE
ו-DEFAULT
.
חשוב לשים לב: FASTER
בגרסה 3 השתנה ל-SMALL
בגרסה 4, HIGHER_PRECISION
ל-LARGE
.
בדוגמאות הבאות משווים בין הפרמטר samplingLevel
בבקשת v3 לבין השדה samplingLevel
בבקשת v4:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
פלחים
הפרמטר segment
בגרסה 3 תואם לשדה segments
בגרסה 4, שכולל רשימה של אובייקטים Segment.
מזהי פלחים
בגרסה 4, כדי לבקש פלח לפי מזהה פלח, יוצרים אובייקט Segment ומציינים את המזהה שלו דרך השדה segmentId.
בדוגמאות הבאות משווים בין הפרמטר segment
בבקשת v3 לבין השדה segments
בבקשה של v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
פלחים דינמיים
בגרסה 4, כדי להגדיר הגדרות מורכבות יותר של פלחים, צריך להשתמש בשדה segments
שכולל אובייקט DynamicSegment.
בדוגמאות הבאות משווים בין הפרמטר segment
בבקשת v3 לבין השדה segments
שמכיל אובייקט DynamicSegment
בבקשת v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
אפשר לשלב בין תנאים ורצפים לפלח:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
תחביר פלחים v3 בגרסה 4
השדה segmentId ב-v4 API תומך בתחביר הפלחים ב-v3 API.
הדוגמאות הבאות מראות איך השדה segment
בבקשת v3 נתמך על ידי השדה segmentId
בבקשה המקבילה בגרסה 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
מסננים
גרסה 4 משתמשת ב-dimensionFilterClauses
כדי לסנן מאפיינים וב-metricFilterClauses
כדי לסנן מדדים. השדה dimensionFilterClauses
מכיל רשימה של אובייקטים ב-DimensionFilter ו-metricFilterClauses
מכיל רשימה של אובייקטים MetricFilter.
בדוגמאות הבאות משווים בין הפרמטר filters
בבקשת v3 לבין השדה dimensionFilterClauses
בבקשה של v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
תחביר של מסנני v3 ב-v4
למרות שהשדה filtersExpression בגרסה 4 תומך בתחביר filters
בגרסה 3, כדאי להשתמש ב-dimensionFilterClauses
וב-metricFilterClauses
כדי לסנן מאפיינים ומדדים.
הדוגמאות הבאות מראות איך השדה filters
בבקשת v3 נתמך על ידי השדה filtersExpression
בבקשה המקבילה בגרסה 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
שורות ריקות
הפרמטר v3 include-empty-rows
תואם לשדה includeEmptyRows
ב-v4. ערך ברירת המחדל של הפרמטר v3 הוא true, ובגרסה 4 הערך שמוגדר בשדה הוא false. אם לא הגדרתם את הערך ב-v3, תצטרכו להגדיר את הערך כ-true בגרסה 4.
בדוגמאות הבאות מוצגת השוואה בין הפרמטר include-empty-rows
בבקשת v3 לבין השדה includeEmptyRows
בבקשת גרסה 4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
חלוקה לדפים
v4 משתמשת בשדות pageToken
ו-pageSize
כדי לעבור בין מספר גדול של תוצאות. השדה pageToken
מתקבל מהמאפיין nextPageToken
של אובייקט תגובה.
בדוגמאות הבאות משווים בין הפרמטרים start-index
ו-max-results
בבקשת v3 לשדות pageToken
ו-pageSize
בבקשת v4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
פרמטרים רגילים
ב-Analytics Reporting API v4 יש תמיכה ברוב הפרמטרים הרגילים של שאילתות ב-v3 API, מלבד הפרמטרים userIp
ו-callback
.
בדוגמאות הבאות משווים בין הפרמטר quotaUser
בבקשת v3 לבין הפרמטר הזה בבקשת v4:
נקודת קצה 3, גרסה 3
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
נקודת קצה (endpoint) גרסה 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
תשובות
מכיוון שגרסה 4 מאפשרת לשלוח מספר אובייקטים מסוג ReportRequest בבקשת HTTP אחת, מקבלים בתגובה מערך של אובייקטים מהדוח. על כל ReportRequest שנשלח, אתם מקבלים דיווח תואם.
דוחות
דוח של גרסה 4 כולל שלושה שדות ברמה העליונה: columnHeader
, data
ו-nextPageToken
.
מכיוון שגוף התגובה v4 לא כולל תגובות לכל הפרמטרים של השאילתה כמו בתגובה ב-v3, על מנת לקבל תשובה לפרמטר ספציפי של שאילתה, אפליקציית הלקוח צריכה להוסיף את הפרמטר הזה ל-ReportRequest.
התייחסנו כבר ל-nextPageToken
בקטע עימוד, אז נתחיל לבחון את האובייקט columnHeader.
כותרת עמודה
כותרת העמודה מכילה רשימה של מאפיינים בעלי שם ואובייקט MetricHeader, שמכיל רשימה של אובייקטים MetricHeaderEntry. כל אובייקט MetricHeaderEntry מציין את המדד name
ואת type
שלו (מטבע, אחוז וכו')
, שעוזרת לעצב את הפלט.
בדוגמאות הבאות משווים את השדה columnHeaders
בתגובה v3 לשדה columnHeader
בתגובה של v4:
v3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
שורות בדוח
ה-Core Reporting API v3 מחזיר את נתוני הדוח במערך rows, שמכיל את המאפיינים והמדדים המבוקשים.
ב-Analytics Reporting API v4 מחזיר את נתוני הדוח באובייקט ReportRow, שמכיל מערך של מאפיינים ומערך של אובייקטים מסוג DateRangeValues, שכל אחד מהם מכיל טווח תאריכים אחד או שניים, כפי שמתואר בתרשים הבא:
שורות
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
הנתונים שנדגמו
במקרה שהתוצאות נדגמו, Core Reporting API v3 מחזיר את השדה הבוליאני containsSampledData
, שמוגדר ל-true
.
גרסה 4 של Analytics Reporting API לא מחזירה ערך בוליאני אם הנתונים נדגמו. במקום זאת, ה-API מחזיר את השדות samplesReadCounts
ו-samplingSpaceSizes
.
אם התוצאות לא נדגמו, השדות האלה לא יוגדרו.
הדוגמה הבאה של Python מראה איך לחשב אם דוח מכיל נתונים שנדגמו:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
למטה מוצגת תגובה לדוגמה שמכילה נתונים שנדגמו מבקשה עם שני טווחי תאריכים. התוצאות חושבו מכמעט 500,000 דגימות בשטח דגימה של כ-15 מיליון סשנים:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
ניתוח התגובה של גרסה 4
הקוד לדוגמה הבא מנתח ומדפיס את התגובה של Analytics Reporting API v4:
Python
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
Java
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
טיפול בשגיאות
מכיוון שהפורמט של תגובת שגיאה ב-v4 שונה מזה שב-v3, עליכם לעדכן את הקוד כך שיטפל בתגובות לשגיאות v4.
בדוגמאות הבאות משווים בין תגובת שגיאה ב-v3 לתגובת השגיאה המקבילה ב-v4:
v3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
v4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}