这是 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 请求的响应正文是报告对象的数组。在 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
中,为以下各项指定值:
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"}
]
}
]
}
维度
维度用于描述用户及其会话和操作的特征。例如,City 维度说明会话的特征,并指明每个会话的发起城市(“Paris”或“New York”)。在 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"
]
}
]
},
...
细分
要请求 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 的高级功能。