本文档提供了有关如何将现有代码从Google Analytics Reporting API v4迁移到Google Analytics Data API v1 的说明，并简要概述了这两个 API 之间的主要区别。
为什么我需要迁移
如果您的应用程序需要访问 Google Analytics 4 属性中的数据，则有必要更新代码以使用 Data API v1，因为 Reporting API v4 只能访问使用 Universal Analytics 创建的属性。
先决条件
请使用快速入门指南熟悉数据 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 数据 API v1使用客户端库
安装客户端库
如果您使用客户端库，则需要为您的编程语言安装 Data API v1 客户端库。
爪哇
Python
节点.js
。网
PHP
去
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 客户端库的代码片段。
爪哇
// 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()
。网
// 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();
节点.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 客户端实例。下面是用于通过在代码中显式传递凭据来初始化数据 API v1 客户端库的片段。
爪哇
// 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)
。网
/**
* 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;
}
节点.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，您仍然可以使用您的凭据。
您需要使用数据 API 提供的新 HTTP 端点和发现文档：
如果您的代码正在利用Discovery 文档，您需要将其更新为 Data API v1 提供的发现文档：
更新端点后，您需要熟悉数据 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 架构更改
报告 API 和数据 API 的报告功能主要取决于它们的架构，即报告查询中支持的维度和指标。由于 Universal Analytics 和 Google Analytics 4 之间的概念差异，这两个 API 的 API 架构存在显着差异。
- 熟悉数据 API 支持的当前维度和指标列表。目前，所有维度和指标都相互兼容，因此无需使用维度和指标资源管理器来确定兼容组合。这种行为将来会改变。
- 可以使用数据 API v1自定义维度语法访问 Google Analytics 4 中的自定义维度，应该使用它来代替 Reporting API v4 的ga:dimensionXX维度槽。
- 可以使用 Data API v1 custom metrics syntax访问 Google Analytics 4 中的自定义指标，应该使用它来代替 Reporting API v4 的ga:metricXX指标槽。
- Universal Analytics 中的某些维度和指标在 Google Analytics 4 中具有直接等效项。有关详细信息，请参阅UA/GA4 API 架构等效项图表。
- 维度和指标名称不再具有
ga:Google Analytics 4 中的前缀。 - Universal Analytics 中存在的某些功能在 GA4 中尚不可用（例如 Campaign Manager、DV360、Search Ads 360 集成）。在 Google Analytics 4 中实现此功能后，数据 API 将支持它，新的维度和指标将添加到 API 架构中。
实体
Google Analytics 4 没有在 Universal Analytics 中引入的视图（配置文件）概念。因此，Data API v1 报告请求中的任何地方都没有viewId参数。相反，在调用数据 API v1 方法时，应在请求 URL 路径中指定一个数字 Google Analytics 4 属性 ID 。此行为不同于 Reporting API v4，后者依赖视图（配置文件）ID来识别报告实体。
数据 API v1
对于数据 API v1，必须在 URL 路径中指定数字 Google Analytics 4 属性 ID。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
报告 API v4
Reporting API v4 要求在报告查询正文中指定 Universal Analytics 视图（配置文件）ID。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
如果您使用的是数据 API 客户端库之一，则无需手动操作请求 URL 路径。大多数 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 ，则会自动生成日期范围名称。
当在数据 API v1 请求中指定多个日期范围时，新的dateRange维度会自动添加到响应中，并且日期范围名称用作维度值。请注意，此行为与 Reporting API v4 不同，后者将日期范围内的数据作为每行中的一组指标值返回。
数据 API v1 请求
可选name字段用于请求中的每个dateRange值。此日期范围名称将用作响应中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"
}
]
}
数据 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"
}
]
},
....
报告 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"
}
]
}
]
}
报告 API v4 响应
在 Reporting API v4 中，每个日期范围的值都在metrics字段内分组：
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
排序
Data API v1 报告查询的排序行为可以使用orderBys字段进行控制，类似于Reporting API v4 的orderBys字段。
OrderBy规范在数据 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值。
数据 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
}
]
}
数据 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": {}
}
报告 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"
}
]
}
]
}
报告 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子句重写这些表达式。
数据 API v1 请求
此示例请求返回用户访问的某些页面路径的会话计数列表。
dimensionFilter子句用于仅返回pagePath维度值以/webstore/开头并包含字符串action=a12345 。
metricFilter子句要求runReport方法仅返回sessions量值大于 1,000 的行。
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"
}
]
}
报告 API v4 请求
此示例请求类似于数据 API v1 示例。它返回用户访问的某些页面路径的会话计数列表。
dimensionFilterClauses字段用于仅返回pagePath维度值以/webstore/开头并包含字符串action=a12345 。
metricFilterClauses字段用于仅返回ga:sessions指标值大于 1,000 的行。
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 请求，应使用Pivot对象的limit和offset字段分别为每个 pivot 实现分页。现在每个Pivot对象都需要limit字段。
默认情况下，Data API v1 最多返回前 10,000 行事件数据，而 Reporting API v4 的默认值为 1,000 行。
在 Data API v1 的响应中使用rowCount字段返回与查询匹配的总行数，这类似于 Reporting API v4。
数据 API v1 请求
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
数据 API v1 响应
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
报告 API v4 请求
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
报告 API v4 响应
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
指标聚合
只有在请求中指定了metricAggregations字段时，Data API v1 才会计算聚合值。相反，报告 API v4 默认返回每个指标的总计、最小值和最大值，除非hideTotals和hideValueRanges字段设置为true 。
数据 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"
}
]
}
数据 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"
}
]
}
],
....
}
报告 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"
}
],
}
]
}
报告 API v4 响应
totals 、 minimums和maximums字段默认存在于 Reporting API v4 响应中。
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
支点
Data API v1 支持runPivotReport和batchRunPivotReports报告方法中的数据透视功能。
Reporting API v4 允许使用batchGet方法在报告查询中包含数据透视表。
与报告 API v4 相比，数据 API v1 中的数据透视表的实现方式不同，每个响应行代表表格的单个单元格，而在报告 API v4 中，单个响应行代表完整的表格行。
数据 API v1
下面是对runPivotReport查询的数据 API v1 响应的片段。透视报告的每个单元格单独返回：
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
报告 API v4
下面是对batchGet查询的 Reporting API v4 响应的片段。单个响应行代表一个完整的表格行，其中包含pivotValueRegions中数据透视表的所有指标值：
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
在数据 API v1 中， runPivotReport或batchRunPivotReports查询的每个维度都必须在数据透视对象中定义。如果某个维度未在数据透视查询的任何数据透视表中使用，则该维度在报表中将不可见。
Data API v1 的透视列是使用fieldNames字段指定的，而不是 Reporting API v4 的dimensions字段。
如果数据 API v1 报告请求中需要维度过滤，则必须使用请求范围的维度过滤器。这与 Reporting API v4 不同，后者接受数据透视对象中的dimensionFilterClauses规范。
Data API v1 的offset字段在功能上类似于 Reporting API v4 的startGroup字段。
Data API v1 的limit字段类似于 Reporting API v4 的maxGroupCount ，应该用于限制报告基数。
Data API v1 支持多个主元，只要每个主元的limit参数的乘积不超过 100,000。 Reporting API v4 仅支持一个数据透视维度。
默认情况下，Data API v1 按照报告中的第一个指标对数据透视表中的维度进行排序。此行为不同于 Reporting API v4，其中数据透视顺序由请求的指标的“总计”的降序确定。要在数据 API v1 中指定排序顺序，请使用 Pivot 规范的orderBys字段。
数据 API v1 请求
此数据 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"
}
]
}
数据 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"
}
]
},
....
],
....
}
报告 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"
}
]
}
]
}
]
}
报告 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 仅允许在同类群组查询中使用特殊指标的子集。
在数据 API v1 同类群组请求中，指标cohortActiveUsers是必需的。
Data API v1 和 Reporting API v4 都允许在单个请求中最多包含 12 个同类群组。
Data API v1 当前不支持生命周期价值 (LTV) 指标。
队列指标等价
Reporting API v4 中定义的大多数同类群组指标都可以替换为表达式，以在 Data API v1 中实现等效结果，如下图所示。
| 报告 API v4 指标名称 | Data API v1 指标名称或表达式 |
|---|---|
| ga:cohortActiveUsers | 队列活跃用户 |
| ga:cohortTotalUsers | 队列总用户数 |
| ga:队列保留率 | “表达式”：“cohortActiveUsers/cohortTotalUsers” |
| ga:cohortRevenuePerUser | “表达式”：“totalRevenue/cohortActiveUsers” |
| ga:cohortVisitDurationPerUser | “表达式”：“userEngagementDuration/cohortActiveUsers” |
| ga:cohortAppviewsPerUser | “表达式”：“screenPageViews/cohortActiveUsers” |
| ga:cohortPageviewsPerUser | “表达式”：“screenPageViews/cohortActiveUsers” |
| ga:cohortSessionsPerUser | “表达式”：“会话/队列ActiveUsers” |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers", 除了按eventName对应于所需目标完成事件的维度过滤器。 |
数据 API v1 请求
配置一组用户的示例查询，其第一次会话发生在 2021-01-03 的一周。使用WEEKLY粒度计算 5 周内同类群组的活跃用户数和用户保留率。
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"
}
]
}
数据 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": {}
}
报告 API v4 请求
配置一组用户的示例查询，其第一次会话发生在 2021-01-03 的一周。使用WEEKLY粒度计算 5 周内同类群组的活跃用户数和用户保留率。
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"
}
}
]
}
}
]
}
报告 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 始终基于非抽样数据构建核心报告。 Reporting API v4 中没有与samplingLevel字段等效的字段。
数据新鲜度
数据 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 之间的概念差异，数据 API 实时报告架构不同于Analytics API v3 的实时报告架构。
数据 API v1 请求
在以下示例中，为了保留 Google Analytics API v3 的默认排序行为，将可选的orderBy元素添加到示例数据 API v1 查询中。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
数据 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 配额变更
核心和实时配额类别
出于配额的目的，数据 API 有两个请求类别：核心和实时。对核心报告方法（ runReport 、 getMetadata 、 runPivotReport 、 batchRunReports 、 batchRunPivotReports ）的 API 请求收取核心配额。对runRealtimeReport方法的 API 请求会收取实时配额。
令牌配额
除了项目配额之外，每个请求还会消耗属性令牌配额，这些配额根据查询的复杂性进行收费。有关 API 配额和限制的详细说明，请参阅数据 API v1 配额文档。
通过在核心或实时报告请求中将returnPropertyQuota设置为true ，可以获得分析属性的所有配额的当前状态。配额状态将在PropertyQuota中返回。
（不支持）基于资源的配额
由于 Google Analytics 4 中的所有核心报告均基于非抽样数据，因此 Reporting API v4 中引入的 Resource Based Quota不再适用，并且 Data API v1 报告请求中不存在与useResourceQuotas字段等效的字段。
（不支持）每天每个视图（配置文件）的请求配额
由于 Google Analytics 4 中没有视图，因此数据 API v1 中不存在requests per view (profile) per day配额，取而代之的是令牌配额。