이 문서에서는 기존 코드를 Google Analytics Management API v4에서 Google Analytics Admin API v1로 이전하는 방법을 안내하고 두 API 간 주요 차이점을 간략히 설명합니다.
이전해야 하는 이유
애플리케이션에서 Google 애널리틱스 4 속성의 데이터에 액세스해야 하는 경우 Reporting API v4에서는 유니버설 애널리틱스로 만든 속성에만 액세스할 수 있으므로 Data API v1을 사용하도록 코드를 업데이트해야 합니다.
기본 요건
빠른 시작 가이드를 사용하여 Data API v1의 기본 사항을 숙지하세요.
시작하기
시작하려면 Google 애널리틱스 4 속성을 준비하고 Data API v1을 사용 설정한 다음, 플랫폼에 적합한 API 클라이언트 라이브러리를 설정합니다.
Google 애널리틱스 4 속성 준비
Data API v1을 지원하기 위해 코드 이전을 시작하기 전에 Google 애널리틱스 4 속성을 사용하도록 웹사이트를 이전해야 합니다. Google 애널리틱스 4 속성을 유니버설 애널리틱스 속성의 이전 데이터로 백필할 수 없습니다.
API 사용 설정
선택한 Google Cloud 프로젝트에서 Data API v1을 자동으로 사용 설정하려면 이 버튼을 클릭합니다.
Google Analytics Data API v1 사용 설정클라이언트 라이브러리 사용
클라이언트 라이브러리 설치
클라이언트 라이브러리를 사용하는 경우 프로그래밍 언어에 사용할 Data API v1 클라이언트 라이브러리를 설치해야 합니다.
Java
Python
Node.js
.NET
2,399필리핀
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();
2,399필리핀
// 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();
2,399필리핀
/**
* @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에서 제공하는 검색 문서로 업데이트해야 합니다.
엔드포인트를 업데이트한 후 JSON 쿼리를 업데이트하려면 Data API의 새로운 요청 구조와 개념을 숙지해야 합니다.
핵심 보고
사용 가능한 보고 메서드
Reporting API v4는 핵심 보고 기능에 액세스하는 단일 메서드 batchGet을 제공했습니다. Data API v1은 다음과 같은 여러 핵심 보고 메서드를 제공합니다.
- runReport: Google 애널리틱스 이벤트 데이터의 맞춤 보고서를 반환합니다. 피봇 기능을 지원하지 않으며 단순 보고서 쿼리에 기본적으로 사용되는 방법입니다.
- runPivotReport: Google 애널리틱스 이벤트 데이터의 맞춤 피봇 보고서를 반환합니다. Reporting API v4의 피봇과 마찬가지로 각 피봇은 보고서 응답에 표시된 측정기준 열과 행을 설명합니다.
- batchRunReports: 단일 API 호출을 사용하여 여러 보고서를 생성할 수 있는
runReport메서드의 일괄 버전입니다. - batchRunPivotReports: 단일 API 호출을 사용하여 여러 보고서를 생성할 수 있는
runPivotReport메서드의 일괄 버전입니다.
여러 보고 메서드를 제공하는 목적은 대부분 편의를 제공하기 위한 것이며, 일부 메서드(피봇, 일괄 처리)는 다른 메서드보다 더 복잡한 기능을 지원하지만 그 외의 경우에는 유사한 요청 구조를 공유합니다.
API 스키마 변경사항
Reporting API와 Data API의 보고 기능은 주로 스키마, 즉 보고 쿼리에서 지원되는 측정기준과 측정항목에 따라 결정됩니다. 유니버설 애널리틱스와 Google 애널리틱스 4의 개념적 차이로 인해 두 API의 API 스키마에 큰 차이가 있습니다.
- Data API에서 지원하는 현재 측정기준 및 측정항목 목록을 숙지합니다. 현재 모든 측정기준과 측정항목은 서로 호환되므로 호환되는 조합을 결정하기 위해 측정기준 및 측정항목 탐색기를 사용할 필요가 없습니다. 이 동작은 향후 변경될 예정입니다.
- Google 애널리틱스 4의 맞춤 측정기준은 Reporting API v4의 ga:dimensionXX 측정기준 슬롯 대신 사용해야 하는 Data API v1 맞춤 측정기준 구문을 사용하여 액세스할 수 있습니다.
- Google 애널리틱스 4의 맞춤 측정항목은 Reporting API v4의 ga:metricXX 측정항목 슬롯 대신 사용해야 하는 Data API v1 맞춤 측정항목 구문을 사용하여 액세스할 수 있습니다.
- 유니버설 애널리틱스에 있는 일부 측정기준과 측정항목의 경우 Google 애널리틱스 4에 동등한 측정기준과 측정항목이 있습니다. 자세한 내용은 동등한 UA/GA4 API 스키마 차트를 참고하세요.
- Google 애널리틱스 4의 측정기준 및 측정항목 이름에는 더 이상
ga:접두어가 없습니다. - 유니버설 애널리틱스의 일부 기능은 아직 GA4에서 사용할 수 없습니다(예: Campaign Manager, DV360, Search Ads 360 통합). 이 기능이 Google 애널리틱스 4에서 구현되면 Data API에서 지원되며 새로운 측정기준과 측정항목이 API 스키마에 추가됩니다.
항목
Google 애널리틱스 4에는 유니버설 애널리틱스에 도입된 보기(프로필) 개념이 없습니다. 따라서 Data API v1 보고 요청에는 viewId 매개변수가 없습니다. 대신 Data API v1 메서드를 호출할 때 요청 URL 경로에 숫자 Google 애널리틱스 4 속성 ID를 지정해야 합니다.
이 동작은 보기(프로필) ID를 사용하여 보고 항목을 나타내는 Reporting API v4와 다릅니다.
Data API v1
Data API v1의 경우 URL 경로에 숫자 Google 애널리틱스 4 속성 ID를 지정해야 합니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
Reporting API v4
Reporting API v4를 사용하려면 보고서 쿼리 본문에 유니버설 애널리틱스 보기(프로필) ID를 지정해야 합니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
Data API 클라이언트 라이브러리 중 하나를 사용하는 경우 요청 URL 경로를 수동으로 조작할 필요가 없습니다. 대부분의 API 클라이언트는 properties/GA4_PROPERTY_ID 형식의 문자열을 예상하는 property 매개변수를 제공합니다. 클라이언트 라이브러리 사용 예는 빠른 시작 가이드를 참고하세요.
기간
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 요청
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"
}
]
}
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 보고서 쿼리의 정렬 동작은 Reporting API v4의 orderBys 필드와 유사한 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 필드는 각 피봇의 페이지 나누기를 개별적으로 구현하는 데 사용해야 합니다. 이제 모든 피봇 객체에 limit 필드가 필요합니다.
기본적으로 Data API v1은 이벤트 데이터의 처음 10,000개 이하의 행을 반환하지만 Reporting API v4의 기본값은 1,000행입니다.
Data API v1의 응답에서 Reporting API v4와 유사한 rowCount 필드를 사용하여 쿼리와 일치하는 총 행 수가 반환됩니다.
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"
}
]
}
측정항목 집계
Data API v1은 요청에 metricAggregations 필드가 지정된 경우에만 집계 값을 계산합니다. 반면에 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 쿼리의 모든 측정기준은 피봇 객체 내에 정의해야 합니다. 피봇 쿼리의 피봇에 사용되지 않는 측정기준은 보고서에 표시되지 않습니다.
Data API v1의 피봇 열은 Reporting API v4의 dimensions 필드 대신 fieldNames 필드를 사용하여 지정됩니다.
Data API v1 보고 요청에서 측정기준 필터링을 원하는 경우 요청 범위 측정기준 필터를 사용해야 합니다. 이는 피봇 객체에 dimensionFilterClauses 사양을 허용하는 Reporting API v4와 다릅니다.
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와 다릅니다. 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개의 동질 집단을 사용할 수 있습니다.
평생 가치(LTV) 측정항목은 현재 Data API v1에서 지원되지 않습니다.
동등한 동질 집단 측정항목
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에 Reporting API v4에 있던 samplingLevel 필드와 마찬가지로 상응하는 SamplingMetadata가 포함됩니다.
데이터 최신 상태
Data API는 보고서 내 모든 조회의 처리가 완료되는지 여부를 나타내는 데 사용되었던 Reporting API v4의 isDataGolden 필드와 동등한 필드를 제공하지 않습니다. 나중에 동일한 쿼리를 실행하면 추가 처리로 인해 동일한 보고서에서 다른 결과를 반환할 수 있습니다.
(지원되지 않음) 세그먼트
현재 Data API v1에서는 세그먼트가 지원되지 않습니다.
실시간 보고
Google 애널리틱스 4 속성에 대한 실시간 보고서를 생성하려면 Data API v1의 properties.runRealtimeReport 메서드를 사용합니다. 유니버설 애널리틱스 속성의 실시간 보고 기능은 Google 애널리틱스 API v3의 data.realtime.get 메서드에서 제공했습니다.
유니버설 애널리틱스와 Google 애널리틱스 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 애널리틱스 API v3 요청
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Google 애널리틱스 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로 설정하여 애널리틱스 속성에 대한 모든 할당량의 현재 상태를 가져올 수 있습니다. 할당량 상태는 PropertyQuota에 반환됩니다.
(지원되지 않음) 리소스 기반 할당량
Google 애널리틱스 4의 모든 핵심 보고서는 샘플링되지 않은 데이터를 기반으로 하므로 Reporting API v4에 도입된 리소스 기반 할당량은 더 이상 적용되지 않으며 Data API v1 보고 요청에는 useResourceQuotas 필드에 상응하는 필드가 없습니다.
(지원되지 않음) 일일 보기(프로필)당 요청수 할당량
Google 애널리틱스 4에는 보기가 없으므로 Data API v1에는 requests per view (profile) per day 할당량이 없으며 토큰 할당량으로 대체됩니다.