本文說明如何將現有程式碼從 Google Analytics Reporting API v4 遷移至 Google Analytics Data API v1，並提供這兩種 API 主要差異的簡要說明。
為何需要遷移
如果您的應用程式需要存取 Google Analytics (分析) 4 資源中的資料，請務必將程式碼更新為使用 Data API v1，因為 Reporting API v4 只能存取使用通用 Analytics (分析) 建立的資源。
必要條件
請參閱快速入門指南，熟悉 Data API v1 的基本概念。
開始使用
請先備妥 Google Analytics (分析) 4 資源，啟用 Data API v1，然後設定適合您平台的 API 用戶端程式庫。
準備 Google Analytics (分析) 4 資源
開始遷移程式碼來支援 Data API v1 之前，請先遷移網站以使用 Google Analytics (分析) 4 資源。您無法以通用 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 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，仍然可以使用憑證。
您必須使用 Data API 提供的新 HTTP 端點與探索文件：
如果您的程式碼使用探索文件，則需要將其更新為 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 的報表功能主要取決於結構定義 (即報表查詢支援的維度和指標)。這兩個 API 的 API 結構定義有顯著差異，原因在於通用 Analytics (分析) 和 Google Analytics (分析) 4 的概念差異。
- 請熟悉 Data API 目前支援的維度和指標清單。目前所有維度和指標都彼此相容，因此不需要使用 Dimensions and Metrics Explorer 判斷相容的組合。這項行為日後會改變。
- 如要存取 Google Analytics (分析) 4 中的自訂維度，請使用 Data API v1 的自訂維度語法，該語法應取代 Reporting API v4 的 ga:dimensionXX 維度版位。
- 如要存取 Google Analytics (分析) 4 中的自訂指標，請使用 Data API v1 自訂指標語法。該語法應取代 Reporting API v4 的 ga:metricXX 指標運算單元。
- 通用 Analytics (分析) 中的部分維度和指標在 Google Analytics (分析) 4 中具有直接同等的功能。詳情請參閱 UA/GA4 API 結構定義等價圖表。
- 在 Google Analytics (分析) 4 中，維度和指標名稱不再有
ga:前置字元。 - GA4 目前仍不支援通用 Analytics (分析) 中的某些功能 (例如 Campaign Manager、DV360、Search Ads 360 整合)，Google Analytics (分析) 4 導入這項功能後，Data API 會支援此功能，並將新的維度和指標加入 API 結構定義中。
實體
Google Analytics (分析) 4 沒有通用 Analytics (分析) 中導入的「資料檢視 (設定檔)」概念。因此，Data API v1 報表要求中的任何位置都不會有 viewId 參數。呼叫 Data API v1 方法時，應改為在要求網址路徑中指定數字形式的 Google Analytics (分析) 4 資源 ID。此行為與 Reporting API v4 不同，後者仰賴資料檢視 (設定檔) ID 來識別報表實體。
Google Data API 第 1 版
如為 Data API v1，必須在網址路徑中指定數值的 Google Analytics (分析) 4 資源 ID。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
Reporting API 第 4 版
使用 Reporting API v4 時，必須在報表查詢的內文中指定通用 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"
]
}
]
},
排序
您可以使用 orderBys 欄位控制 Data API v1 報表查詢的排序行為，與 Reporting API v4 的 orderBys 欄位類似。
Data API v1 中的 OrderBy 規格已變更。每個 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 子句可用來只傳回 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"
}
]
}
Reporting API v4 要求
這個要求範例類似於 Data 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 的資料透視要求，則應使用資料透視物件的 limit 和 offset 欄位來個別實作每個資料透視的分頁。所有 Pivot 物件都必須提供 limit 欄位。
根據預設，Data API v1 最多只能傳回前 10,000 列的事件資料，而 Reporting API v4 的預設值是 1,000 列。
系統會傳回 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 才會計算匯總值。相反地，除非 hideTotals 和 hideValueRanges 欄位設為 true，否則 Reporting API v4 預設會傳回每個指標的總值、最小值和最大值。
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 中，資料透視的處理方式與報表 API v4 不同，每個回應列都代表資料表中的單一儲存格，而 Reporting API v4 中，單一回應列代表完整的表格行。
Google Data API 第 1 版
下方是 Data API v1 回應 runPivotReport 查詢的片段片段。系統會個別傳回資料透視報告中的每個儲存格：
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
Reporting API 第 4 版
以下是 Reporting API v4 回應 batchGet 查詢的片段片段。單一回應列代表完整的表格，其中包含 pivotValueRegions 中資料透視的所有指標值：
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
在 Data API v1 中，runPivotReport 或 batchRunPivotReports 查詢的每個維度都必須在資料透視物件中定義。如未用於資料透視查詢的任何維度，報表中就不會顯示該維度。
Data API v1 的樞紐分析資料欄使用 fieldNames 欄位 (而非 Reporting API v4 的 dimensions 欄位) 指定。
如需使用 Data API v1 報表要求使用維度篩選功能，則必須使用要求限定範圍的維度篩選器。這與 Reporting API v4 不同，後者接受資料透視物件中的 dimensionFilterClauses 規格。
Data API v1 的 offset 欄位與 Reporting API v4 的 startGroup 欄位類似。
Data API v1 的 limit 欄位與 Reporting API v4 的 maxGroupCount 相似，適用於限制報表基數。
只要每個資料透視的 limit 參數乘積不超過 100,000 個，Data API v1 即可支援多個資料透視。Reporting API v4 僅支援一個資料透視維度。
根據預設，Data API v1 會依報表中的第一個指標排序資料透視表中的排序維度。此行為與 Reporting API v4 不同，資料透視順序取決於要求指標的「總數」遞減順序。如要在 Data API v1 中指定排序順序，請使用資料透視規格的 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 日當週的使用者同類群組。系統會以 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"
}
]
}
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 日當週的使用者同類群組。系統會以 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"
}
}
]
}
}
]
}
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 第 4 版中的 samplingLevel 欄位。
資料更新間隔
Data API 不提供 Reporting API v4 的 isDataGolden 欄位對等欄位，可用來指出報表的所有命中是否處理完畢。至於後續日期進行查詢，同一報表仍有可能傳回不同的結果，因為其需要進行額外的處理。
(不支援) 區隔
Data API 第 1 版目前不支援區隔。
即時報表
使用 Data API 第 1 版的 properties.runRealtimeReport 方法，產生 Google Analytics (分析) 4 資源的即時報表。通用 Analytics (分析) 資源的即時報表功能由 Google Analytics (分析) API 第 3 版的 data.realtime.get 方法提供。
通用 Analytics (分析) 與 Google Analytics (分析) 4 之間的概念差異，因此 Data API 即時報表結構定義與 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 第 4 版 userActivity.search 方法)。
API 配額變更
核心和即時配額類別
針對配額，Data API 有兩種要求類別：「核心」和「即時」。傳送至 Core 報表方法 (runReport、getMetadata、runPivotReport、batchRunReports、batchRunPivotReports) 的 API 要求會收取核心配額。
傳送至 runRealtimeReport 方法的 API 要求會按即時配額收費。
權杖配額
除了專案配額以外，每個要求也會使用權杖配額，這些屬性會根據查詢的複雜度而收費。如要進一步瞭解 API 配額與限制，請參閱 Data API v1 配額說明文件。
如要取得 Analytics (分析) 資源所有配額的目前狀態，您可以在核心或即時報表要求中將 returnPropertyQuota 設為 true。配額狀態會在 PropertyQuota 中傳回。
(不支援) 以資源為基礎的配額
Google Analytics (分析) 4 中的所有核心報表都是以未取樣資料為基礎，因此 Reporting API v4 中引入的資源型配額已不適用，且 Data API v1 報表要求中沒有對等的 useResourceQuotas 欄位。
(不支援) 每日每個資料檢視 (設定檔) 的要求配額
由於 Google Analytics (分析) 4 中沒有任何資料檢視，因此 Data API v1 中不會顯示 requests per view (profile) per day 配額，且會由權杖配額取代。