这是 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
中,为以下各项指定值:
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"
]
}
]
},
...
路段
要请求 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 的高级功能。