這是 Analytics Reporting API 第 4 版的開發人員指南,如需 API 的詳細參考資料,請參閱 API 參考資料。
報表
Analytics Reporting API v4 提供 batchGet 方法,用來存取「報表」資源。以下各節說明 batchGet
的要求主體結構以及 batchGet
的回應主體結構。
要求主體
如要使用 Analytics Reporting API v4 要求資料,您必須建構 ReportRequest 物件,其最低需求如下:
- viewId 欄位的有效資料檢視 ID。
- 在 dateRanges 欄位中至少包含一個有效項目。
- 在 metrics 欄位中至少有一個有效項目。
如要查看資料檢視 ID,請使用帳戶摘要方法查詢或使用 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
如果您將 not
指定為 true
,則篩選器的運作方式如下:
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"
}
]
}
]
}
排序方式
如要按照指標值排序結果,請按照以下步驟操作:
在以下範例中,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
如果您將 not
指定為 true
,則篩選器的運作方式如下:
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"]
}
]
}
]
}
]
}
排序方式
如何依維度值排序結果:
舉例來說,下列 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
。
例如,假設在 1 月和 2 月兩個日期範圍內收到 ga:date
維度和 ga:sessions
指標的要求。一月中要求資料的回應,2 月的值會是 0
;若是 2 月的要求資料,則 1 月的值會是 0
。
一月份報告
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
2 月報告
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
路段
如要要求部分 Analytics (分析) 資料,請使用區隔。例如,您可以在一個區隔中定義來自特定國家/地區或城市的使用者,以及在另一個區隔中瀏覽網站特定部分的使用者。篩選器只會傳回滿足特定條件的資料列,而區隔會傳回符合包含區隔條件的使用者、工作階段或事件子集。
使用區隔發出要求時,請確認下列事項:
batchGet
方法中的每個 ReportRequest 都必須包含相同的區隔定義。- 您將「
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"]
}
}]
}]
}
}]
}
}
}]
}]
}
如需更多包含區隔的要求範例,請參閱範例。
區隔 ID
使用 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"
}
]
}
如果報表包含取樣資料,Analytics (分析) Reporting API v4 就會傳回 samplesReadCounts
和 samplingSpaceSizes
欄位。如果結果未經過取樣,就不會定義這些欄位。
下方的回應範例含有來自兩個日期範圍的要求取樣資料。結果是依據約 1,500 萬個工作階段的取樣空間大小從近 50 萬個樣本計算得出:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
分頁
Analytics Reporting API v4 會使用 pageToken
和 pageSize
欄位,分頁橫跨多頁的回應結果。您可以從 nextPageToken
參數取得 reports.batchGet
要求的回應中的 pageToken
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
後續步驟
現在您已瞭解建立報表的基本概念,請參閱 API v4 的進階功能。