這份 Analytics (分析) Reporting API v4 開發人員指南如需 API 的詳細參考資料,請參閱 API 參考資料。
報表
Analytics Reporting API v4 提供 batchGet 方法,用於存取 Reports 資源。
以下各節說明 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 物件。
在以下範例中,batchGet
方法會提供 Sessions
指標,以取得指定日期範圍內的工作階段總數:
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
指標的要求。針對 1 月要求的資料,2 月的值為 0
;在 2 月針對要求資料的回應中,1 月的值為 0
。
1 月份報表
{
"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 中的取樣資料,則 Analytics (分析) Reporting API v4 會傳回 samplesReadCounts
和 samplingSpaceSizes
欄位。如果結果沒有取樣,這些欄位就不會定義。
以下回應範例包含來自兩個日期範圍的要求取樣資料。結果計算依據為約 1,500 萬個工作階段的取樣空間大小將近 50 萬個樣本:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
分頁
Analytics Reporting API v4 會使用 pageToken
和 pageSize
欄位來分頁,查看橫跨多個頁面的回應結果。您可以從 reports.batchGet
要求回應中的 nextPageToken
參數取得 pageToken
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
後續步驟
現在您已經瞭解建立報表的基本知識,現在請參閱 API v4 的進階功能。