本指南提供指南,協助您將 Core Reporting API v3 遷移至 Analytics Reporting API v4。
簡介
如要運用 Analytics (分析) Reporting API v4 新推出的功能,請遷移程式碼以使用 API。本指南顯示的是 Core Reporting API v3 中的要求,以及 Analytics Reporting API v4 中的同等要求,幫助您簡化遷移作業。
Python 遷移
如果您是 Python 開發人員,請使用 GitHub 上的 GAV4 輔助程式庫,將 Google Analytics Core Reporting API v3 要求轉換為 Analytics Reporting API v4 要求。
端點
Core Reporting API v3 和 Analytics Reporting API v4 有不同的端點和 HTTP 方法:
v3 端點
GET https://www.googleapis.com/analytics/v3/data/ga
v4 端點
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
以下範例會比較 v3 中的要求與 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&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"
}]
}]
}
用戶端程式庫與探索服務
如果您使用 Python、JavaScript 或其他需使用 Google Discovery 服務的用戶端程式庫,則必須提供探索文件的位置給 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 用戶端程式庫已預先建構,但您可以使用探索服務和 Google API 產生器來產生這類程式庫。
要求
API v4 參考資料詳細說明要求主體的結構。以下各節說明如何將 v3 要求參數遷移至 v4 要求參數。
資料檢視 ID
在第 3 版中,接受「資料表 ID」的 ids
參數格式為 ga:XXXX
,其中 XXXX
是資料檢視 (設定檔) ID。在 v4 中,資料檢視 (設定檔) ID 是在要求主體的 viewId
欄位中指定。
以下範例會比較 v3 要求中的 ids
參數和 v4 要求中的 viewId
欄位:
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
參數來指定要求的日期範圍。
以下範例會比較 v3 要求中的 start-date
和 end-date
參數與 v4 要求中的 dateRanges
欄位:
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"
}],
....
}]
}
指標
第 3 版 metrics
參數會對應至使用指標物件清單的 v4 metrics
欄位。
以下範例會比較 v3 要求中的 metrics
參數和 v4 要求中的 metrics
欄位:
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"
}],
...
}]
}
尺寸
第 3 版 dimensions
參數會對應至使用維度物件清單的 v4 dimensions
欄位。
以下範例會比較 v3 要求中的 dimensions
參數和 v4 要求中的 dimensions
欄位:
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"
}],
...
}]
}
排序
第 3 版 sort
參數相當於使用 OrderBy 物件清單的 v4 orderBys
欄位。
在第 4 版中,依照維度或指標值排序結果:
以下範例會比較 v3 要求中的 sort
參數和 v4 要求中的 orderBy
欄位,並且都會按照遞減順序和來源字母排序使用者:
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"
}],
}]
}
取樣層級
第 3 版 samplingLevel
參數對應至第 4 版 samplingLevel
欄位。在 v3 中,可接受的 samplingLevel
值為 FASTER
、HIGHER_PRECISION
和 DEFAULT
;在 v4 中,可接受的 samplingLevel
值為 SMALL
、LARGE
和 DEFAULT
。請注意,第 3 版中的 FASTER
已從 v4 版變更為 SMALL
,將 HIGHER_PRECISION
變更為 LARGE
。
以下範例會比較 v3 要求中的 samplingLevel
參數和 v4 要求中的 samplingLevel
欄位:
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"
}]
}
路段
第 3 版 segment
參數會對應至使用 Segment 物件清單的 v4 segments
欄位。
區隔 ID
在第 4 版中,如要透過區隔 ID 要求區隔,請建構 Segment 物件,並透過 segmentId 欄位提供其 ID。
以下範例會比較 v3 要求中的 segment
參數和 v4 要求中的 segments
欄位:
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"
}]
}]
}
動態區隔
在 v4 中,如要表達更複雜的區隔定義,請使用包含 DynamicSegment 物件的 segments
欄位。
以下範例會比較 v3 要求中的 segment
參數和 v4 要求中含有 DynamicSegment
物件的 segments
欄位:
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"]
}
}]
}]
}]
}
}]
}
}
}]
}]
第 4 版中的 v3 區隔語法
v4 API 中的 segmentId 欄位支援 v3 API 中的區隔語法。
以下範例說明 v4 中同等要求的 segmentId
欄位如何支援 v3 要求中的 segment
參數:
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 物件清單。
以下範例會比較 v3 要求中的 filters
參數和 v4 要求中的 dimensionFilterClauses
欄位:
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"]
}]
}]
}]
第 4 版中的 v3 篩選器語法
雖然第 4 版的 filtersExpression 欄位支援第 3 版中的 filters
語法,但請使用 dimensionFilterClauses
和 metricFilterClauses
來篩選維度和指標。
以下範例說明 v4 中同等要求的 filtersExpression
欄位如何支援 v3 要求中的 filters
參數:
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"
}]
}
空白列
第 3 版 include-empty-rows
參數對應到第 4 版中的 includeEmptyRows
欄位。v3 參數的預設值為 true,在 v4 中,欄位的預設值為 false。如果您未在 v3 中設定值,則需在 v4 中將值設為 true。
以下範例將比較 v3 要求中的 include-empty-rows
參數與 v4 要求中的 includeEmptyRows
欄位:
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",
}]
}
分頁
第 4 版會使用 pageToken
和 pageSize
欄位,將大量結果分頁。系統會從回應物件的 nextPageToken
屬性取得 pageToken
。
以下範例將 v3 要求中的 start-index
和 max-results
參數與 v4 要求中的 pageToken
和 pageSize
欄位進行比較:
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
參數除外。
以下範例將比較 v3 要求中的 quotaUser
參數與 v4 要求中的參數:
v3 端點
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
v4 端點
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
回應
由於 v4 可讓您在單一 HTTP 要求中提交多個 ReportRequest 物件,因此您會在回應中取得報表物件陣列。針對每個提交的 ReportRequest,您會在回應中收到對應的報告。
報表
v4 報表有三個頂層欄位:columnHeader
、data
和 nextPageToken
。
就 v3 回應而言,v4 回應主體不包含所有查詢參數的回應,因此如要取得特定查詢參數的回應,用戶端應用程式必須將該參數新增至 ReportRequest。
我們已處理「Pagination」區段中的 nextPageToken
,所以請先查看 columnHeader 物件。
欄標題
欄標題包含已命名維度和 MetricHeader 物件清單,其中含有 MetricHeaderEntry 物件清單。每個 MetricHeaderEntry 物件會指定指標 name
及其 type
(貨幣、百分比等),有助於設定輸出格式。
以下範例會比較 v3 回應中的 columnHeaders
欄位與 v4 回應中的 columnHeader
欄位:
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 會在資料列陣列中傳回報表資料,其中包含要求的維度和指標。
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
)。
如果資料經過取樣,Analytics Reporting API v4 不會傳回布林值,而是 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
下方的回應範例含有來自兩個日期範圍的要求取樣資料。結果是依據約 1,500 萬個工作階段的取樣空間大小從近 50 萬個樣本計算得出:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
剖析 v4 回應
下列程式碼範例會剖析並列印 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));
}
}
}
}
}
處理錯誤
由於第 4 版中的 error response 格式與第 3 版不同,因此請更新程式碼,以便處理 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.\" }"
}
]
}
}