這是 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 中，指定下列項目的值：
metricNamenotoperatorcomparisonValue
讓 {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 中，指定下列項目的值：
dimensionNamenotoperatorexpressionscaseSensitive
讓 {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 的進階功能。