本文档提供了有关如何将现有代码从 Google Analytics（分析）Reporting API v4 迁移到 Google Analytics（分析）Data API v1 的说明，还简要介绍了这两种 API 之间的主要区别。
为什么需要迁移
如果您的应用需要访问 Google Analytics（分析）4 媒体资源中的数据，则必须更新代码使之采用 Data API v1，因为 Reporting API v4 只能访问使用 Universal Analytics 创建的媒体资源。
前提条件
请参阅快速入门指南，熟悉 Data API v1 的基础知识。
使用入门
首先，您需要准备一项 Google Analytics（分析）4 媒体资源，启用 Data API v1，然后设置一个适合您平台的 API 客户端库。
准备 Google Analytics（分析）4 媒体资源
在开始迁移代码以使之支持 Data API v1 之前，您需要将网站改为使用 Google Analytics（分析）4 媒体资源。您无法使用 Universal Analytics 媒体资源中的历史数据回填 Google Analytics（分析）4 媒体资源。
启用该 API
点击下面的按钮可自动在您选择的 Google Cloud 项目中启用 Data API v1。
启用 Google Analytics（分析）Data API v1使用客户端库
安装客户端库
如果您使用客户端库，则需要安装适用于您所用编程语言的 Data API v1 客户端库。
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
初始化客户端库
Data API v1 客户端库旨在帮助您快速上手使用。默认情况下，客户端库会尝试自动查找您的服务账号凭据。
若要提供服务账号凭据，一种简单的方法是设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量，API 客户端会使用此变量的值查找服务账号密钥 JSON 文件。
例如，您可以通过运行以下命令并使用服务账号 JSON 文件的路径来设置服务账号凭据：
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
下面是常用于初始化 Data API v1 客户端库的代码段。
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
您也可以在初始化期间将凭据信息明确传递到 API 客户端实例，而非使用环境变量。下面是用于初始化 Data API v1 客户端库的代码段，采取的方式是在代码中明确传递凭据。
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
未使用客户端库
如果您在使用 Reporting API v4 时未使用客户端库，并且也希望以此方式使用 Data API v1，则仍然可以使用原来的凭据。
您需要使用新的 HTTP 端点和 Data API 提供的发现文档：
如果您的代码目前使用发现文档，您需要将其更新为 Data API v1 提供的发现文档：
更新端点后，您需要熟悉一下 Data API 新的请求结构和概念，以便更新您的 JSON 查询。
核心报告
可用的报告方法
Reporting API v4 只提供了一个 batchGet 方法来访问其核心报告功能。Data API v1 提供了以下几个核心报告方法供您选择：
- runReport：此方法会返回包含 Google Analytics（分析）事件数据的自定义报告。此方法是用于简单报告查询的首选方法，但不支持数据透视功能。
- runPivotReport：此方法会返回包含 Google Analytics（分析）事件数据的自定义数据透视报告。与 Reporting API v4 中的数据透视类似，各个数据透视描述了报告响应中的可见维度列和行。
- batchRunReports：此方法是
runReport方法的批处理版本，允许使用单个 API 调用生成多个报告。 - batchRunPivotReports：此方法是
runPivotReport方法的批处理版本，允许使用单个 API 调用生成多个报告。
提供多个报告方法的目的主要是为了方便，其中一些方法支持的功能（数据透视、批量处理）比另外一些方法更为复杂，但除此之外各个方法都采用类似的请求结构。
API 架构变更
Reporting API 和 Data API 的报告功能主要取决于各自的架构（即在报告查询中支持使用的维度和指标）。由于 Universal Analytics 与 Google Analytics（分析）4 在概念上存在一定差异，因此这两种 API 在 API 架构方面存在显著差异。
- 请熟悉 Data API 支持的维度和指标的最新列表。目前，所有维度和指标都相互兼容，因此无需使用维度和指标浏览器来确定兼容的组合。这一特点在将来会发生变化。
- 可以使用 Data API v1 的自定义维度语法来访问 Google Analytics（分析）4 中的自定义维度，而不应再使用 Reporting API v4 的 ga:dimensionXX 维度序号。
- 可以使用 Data API v1 的自定义指标语法来访问 Google Analytics（分析）4 中的自定义指标，而不应再使用 Reporting API v4 的 ga:metricXX 指标序号。
- Universal Analytics 中的某些维度和指标在 Google Analytics（分析）4 中有直接对等项。如需了解详情，请参阅 UA/GA4 API 架构等效项图表。
- Google Analytics（分析）4 中的维度和指标名称不再具有
ga:前缀。 - Universal Analytics 中的某些功能尚未在 GA4 中提供（例如 Campaign Manager、DV360、Search Ads 360 集成）。在 Google Analytics（分析）4 中实现这些功能后，Data API 便会支持使用它们，届时也会向 API 架构中添加新的维度和指标。
实体
Universal Analytics 中引入了数据视图（配置文件），而 Google Analytics（分析）4 中则没有这一概念。因此，Data API v1 报告请求中的任何位置都没有 viewId 参数。相反，在调用 Data API v1 方法时，应在请求网址路径中指定 Google Analytics（分析）4 媒体资源的数字 ID。此行为与 Reporting API v4 不同，后者依靠数据视图（配置文件）ID 来识别报告实体。
Data API v1
如果是 Data API v1，则必须在网址路径中指定 Google Analytics（分析）4 媒体资源的数字 ID。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
Reporting API v4
Reporting API v4 要求在报告查询的正文中指定 Universal Analytics 数据视图（配置文件）ID。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
如果您使用的是 Data API 客户端库之一，则无需手动操作请求网址路径。大多数 API 客户端都会提供一个 property 参数，该参数需要 properties/GA4_PROPERTY_ID 形式的字符串。如需查看有关如何使用客户端库的示例，请参阅快速入门指南。
日期范围
Reporting API v4 和 Data API v1 均支持在报告请求中使用 dateRanges 字段指定的多个日期范围。这两种 API 采用相同的日期输入格式，都接受 YYYY-MM-DD 形式的绝对日期值或 yesderday、today、7daysAgo 等相对日期。
Data API v1 请求最多只能包含 4 个日期范围，而 Reporting API v4 允许在单个报告请求中包含 2 个日期范围。
Data API v1 中的每个 dateRange 都可以包含一个可选的 name 字段，该字段可用于引用响应中的相应日期范围。如果未提供 name，系统会自动生成日期范围名称。
在 Data API v1 请求中指定多个日期范围时，新的 dateRange 维度会自动添加到响应中且日期范围名称会用作维度值。请注意，此行为与 Reporting API v4 不同，后者会在每一行中以一组指标值的形式返回日期范围的数据。
Data API v1 请求
请求中的每个 dateRange 值都可以使用一个可选的 name 字段。此日期范围名称将用作响应中 dateRange 维度的值。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Data API v1 响应
响应中会自动包含一个额外的 dateRange 维度。dateRange 维度值包含日期范围的名称，该名称来自 dateRange.name 字段或由系统自动生成。
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Reporting API v4 请求
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Reporting API v4 响应
在 Reporting API v4 中，每个日期范围的值都会划分到 metrics 字段内：
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
排序
Data API v1 报告查询的排序行为可使用 orderBys 字段进行控制，该字段类似于 Reporting API v4 的 orderBys 字段。
OrderBy 规范在 Data API v1 中有所更改。每个 OrderBy 都可以包含以下各项之一：
- DimensionOrderBy，按维度值对结果进行排序。
- MetricOrderBy，按指标值对结果进行排序。
- PivotOrderBy，用于数据透视查询，并按数据透视列组中的指标值对结果进行排序。
Reporting API v4 支持的 DELTA、SMART、HISTOGRAM_BUCKET 排序类型尚未在 Data API v1 中实现。
Data API v1 的 OrderType.NUMERIC 排序类型等效于 Reporting API v4 的 OrderType.DIMENSION_AS_INTEGER 值。
Data API v1 请求
以下示例展示了一个示例查询，该查询按国家/地区报告会话数，然后按 sessions 指标依降序对行进行排序。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Data API v1 响应
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Reporting API v4 请求
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Reporting API v4 响应
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
过滤
Data API v1 的 dimensionFilter 和 metricFilter 子句可用于请求该 API 仅返回特定维度或指标值的数据。这类似于 Reporting API v4 的 dimensionFilterClauses 和 metricFilterClauses。
Data API v1 不支持过滤条件表达式字符串，例如 Reporting API v4 的 filtersExpression 子句。应使用 dimensionFilter 和 metricFilter 子句重写这些表达式。
Data API v1 请求
此示例请求会返回用户访问的特定网页路径对应的会话数列表。
dimensionFilter 子句用于仅返回具有以 /webstore/ 开头且包含字符串 action=a12345 的 pagePath 维度值的行。
metricFilter 子句请求 runReport 方法仅返回 sessions 指标值大于 1000 的行。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Reporting API v4 请求
此示例请求类似于 Data API v1 示例。该请求会返回用户访问的特定网页路径对应的会话数列表。
dimensionFilterClauses 字段用于仅返回具有以 /webstore/ 开头且包含字符串 action=a12345 的 pagePath 维度值的行。
metricFilterClauses 字段用于仅返回 ga:sessions 指标值大于 1000 的行。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
分页
Data API v1 使用 limit 和 offset 字段对跨多个网页的响应结果进行分页，而 Reporting API v4 使用的是 pageToken 和 pageSize。
对于 Data API v1 的数据透视请求，应使用 Pivot 对象的 limit 和 offset 字段为每个数据透视分别实现分页。现在，每个 Pivot 对象都需要 limit 字段。
默认情况下，Data API v1 最多返回前 10000 行事件数据，而 Reporting API v4 的默认值为 1000 行。
在 Data API v1 中，系统通过响应中的 rowCount 字段返回与查询匹配的总行数，类似于 Reporting API v4。
Data API v1 请求
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Data API v1 响应
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Reporting API v4 请求
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Reporting API v4 响应
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
指标聚合
只有在请求中指定 metricAggregations 字段时，Data API v1 才会计算聚合值。相比之下，Reporting API v4 会默认返回每个指标的总计值、最小值和最大值，除非 hideTotals 和 hideValueRanges 字段设置为 true。
Data API v1 请求
只有在请求中指定 metricAggregations 字段时，系统才会计算聚合值。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Data API v1 响应
聚合指标行在响应的 totals、minimum 和 maximum 字段中返回。对于聚合指标行，dimensionValues 字段包含特殊值 RESERVED_TOTAL、RESERVED_MAX 或 RESERVED_MIN。
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Reporting API v4 请求
按国家/地区返回会话数的示例请求。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Reporting API v4 响应
Reporting API v4 响应中默认显示 totals、minimums 和 maximums 字段。
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
数据透视
Data API v1 的 runPivotReport 和 batchRunPivotReports 报告方法支持数据透视功能。
Reporting API v4 允许使用 batchGet 方法在报告查询中添加数据透视。
数据透视在 Data API v1 和 Reporting API v4 中的实现方式有所不同：在 Data API v1 中，每一个响应行表示表中的一个单元格，而在 Reporting API v4 中，一个响应行表示表中完整的一行。
Data API v1
以下是针对 runPivotReport 查询的 Data API v1 响应的片段。系统会单独返回数据透视报告的每个单元格：
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
Reporting API v4
以下是针对 batchGet 查询的 Reporting API v4 响应的片段。一个响应行表示表中完整的一行，其中 pivotValueRegions 中包含数据透视的所有指标值：
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
在 Data API v1 中，runPivotReport 或 batchRunPivotReports 查询的每个维度都必须在 Pivot 对象中定义。如果某个维度未用于数据透视查询的任何数据透视，则将不会显示在报告中。
Data API v1 的数据透视列是使用 fieldNames 字段（而不是 Reporting API v4 的 dimensions 字段）指定的。
如果 Data API v1 报告请求中需要进行维度过滤，则必须使用请求范围的维度过滤条件。这与 Reporting API v4 不同，后者接受 Pivot 对象中的 dimensionFilterClauses 规范。
Data API v1 的 offset 字段在功能上类似于 Reporting API v4 的 startGroup 字段。
Data API v1 的 limit 字段类似于 Reporting API v4 的 maxGroupCount 字段，并且应该用于限制报告基数。
只要每个数据透视的 limit 参数的乘积不超过 100000，Data API v1 便可支持多个数据透视。Reporting API v4 仅支持一个数据透视维度。
默认情况下，Data API v1 按报告中的第一个指标对数据透视中的维度进行排序。此行为与 Reporting API v4 不同，在 Reporting API v4 中，数据透视排序取决于所请求指标的“总计”值的降序顺序。如需在 Data API v1 中指定排序顺序，请使用 Pivot 规范的 orderBys 字段。
Data API v1 请求
此 Data API v1 数据透视查询按国家/地区生成会话数报告，并按 browser 维度透视数据。请注意查询如何使用 orderBys、limit、offset 字段来重现类似 Reporting API v4 查询的行为，从而保留排序和分页设置。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
},
{
"name": "browser"
}
]
}
Data API v1 响应
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Reporting API v4 请求
此 Reporting API v4 数据透视查询按国家/地区生成会话数报告，并按 ga:browser 维度透视数据。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Reporting API v4 响应
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
同类群组
Data API v1 根据 CohortSpec 规范来配置同类群组报告。这类似于 Reporting API v4 的 CohortGroup 规范。
Data API v1 中所有的可用指标目前都与同类群组查询兼容，而 Reporting API v4 仅允许在同类群组查询中使用部分特殊指标。
在 Data API v1 同类群组请求中，必须提供指标 cohortActiveUsers。
Data API v1 和 Reporting API v4 在单个请求中所允许的同类群组上限均为 12 个。
Data API v1 目前不支持生命周期价值 (LTV) 指标。
同类群组指标等效性
Reporting API v4 中定义的大多数同类群组指标都可替换为表达式，从而在 Data API v1 中取得等效结果，如下图所示。
| Reporting API v4 指标名称 | Data API v1 指标名称或表达式 |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers"，除了与所需的目标达成事件相对应的维度过滤条件（按 eventName 过滤）之外。 |
Data API v1 请求
一个示例查询，用于为在 2021 年 1 月 3 日这一周发生第一次会话的用户配置同类群组。同类群组 5 周内的活跃用户数和用户留存率是使用 WEEKLY 粒度计算得出的。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Data API v1 响应
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Reporting API v4 请求
一个示例查询，用于为在 2021 年 1 月 3 日这一周发生第一次会话的用户配置同类群组。同类群组 5 周内的活跃用户数和用户留存率是使用 WEEKLY 粒度计算得出的。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Reporting API v4 响应
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
采样
如果 Data API v1 预计基数限制会降低数据质量，会自动使用数据抽样。如果对某个日期范围的结果进行抽样，RunReportResponse 的 metadata 将包含相应的 SamplingMetadata，类似于 Reporting API v4 中的samplingLevel 字段。
数据新鲜度
Data API 中没有提供与 Reporting API v4 的 isDataGolden 字段等效的字段，该字段用于指明报告的所有命中是否均已处理完毕。如果在日后执行查询，由于要额外进行处理，同一报告仍可能返回不同的结果。
（不支持）细分
Data API v1 目前不支持细分。
实时报告
使用 Data API v1 的 properties.runRealtimeReport 方法为 Google Analytics（分析）4 媒体资源生成实时报告。Universal Analytics 媒体资源的实时报告功能由 Google Analytics（分析）API v3 的 data.realtime.get 方法提供。
由于 Universal Analytics 与 Google Analytics（分析）4 在概念上存在一定差异，因此 Data API 实时报告架构与 Google Analytics（分析）API v3 的实时报告架构有所不同。
Data API v1 请求
在以下示例中，为了保留 Google Analytics（分析）API v3 的默认排序行为，我们在示例 Data API v1 查询中添加了一个可选的 orderBy 元素。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Data API v1 响应
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Google Analytics（分析）API v3 请求
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Google Analytics（分析）API v3 响应
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
（不支持）用户活动报告
Data API v1 目前不支持报告单个用户活动的功能（类似于 Reporting API v4 的 userActivity.search 方法）。
API 配额变更
“核心”和“实时”配额类别
对于配额而言，Data API 提供了两种请求类别：核心和实时。向核心报告方法（runReport、getMetadata、runPivotReport、batchRunReports、batchRunPivotReports）发出的 API 请求会消耗核心配额。向 runRealtimeReport 方法发出的 API 请求会消耗实时配额。
令牌配额
除了项目配额之外，每个请求还会消耗媒体资源令牌配额（具体消耗多少配额取决于查询的复杂性）。如需详细了解 API 配额和限制，请参阅 Data API v1 配额文档。
您可以通过在核心或实时报告请求中将 returnPropertyQuota 设置为 true 来获取 Google Analytics（分析）媒体资源的所有配额的当前状态。配额状态将在 PropertyQuota 中返回。
（不支持）基于资源的配额
由于 Google Analytics（分析）4 中的所有核心报告均基于非抽样数据，因此 Reporting API v4 中引入的基于资源的配额不再适用，并且 Data API v1 报告请求中没有等效的 useResourceQuotas 字段。
（不支持）“每个数据视图（配置文件）的每日请求数”配额
由于 Google Analytics（分析）4 中没有数据视图，因此 Data API v1 中没有 requests per view (profile) per day 配额，取而代之的是令牌配额。