这是 Analytics Reporting API v4 的开发者指南。有关该 API 的详细参考信息，请参阅 API 参考。
报告
Analytics Reporting API v4 提供了用于访问报告资源的 batchGet 方法。以下各部分介绍了 batchGet 请求正文的结构以及 batchGet 中响应正文的结构。
请求正文
要使用 Analytics Reporting API v4 请求数据，您必须构建 ReportRequest 对象，该对象需要满足这些最低要求：
- 用于 viewId 字段的有效数据视图 ID。
- dateRanges 字段中至少有一个有效条目。
- metrics 字段中至少有一个有效条目。
要查找数据视图 ID，请查询帐号摘要方法或使用帐号浏览器。如果未提供日期范围，则默认日期范围为：{"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 对象中定义报告结构，其中说明了报告中的维度和指标及其数据类型。在数据字段中指定维度和指标的值。
以下是上文示例请求的示例响应：
{
"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"
]
}
]
}
}
]
}
指标
指标是定量测量；每个请求至少需要一个指标对象。
在以下示例中，系统会向 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 中，为以下各项指定值：
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 指标的请求。在 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"
]
}
]
},
...
路段
要请求 Google 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 字段。如果未对结果进行抽样，将不会定义这些字段。
下例中的响应所包含的抽样数据来自有两个日期范围的请求。这些结果计算自约 1500 万个会话的抽样空间中的约 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 的高级功能。