Google Analytics Data API v1을 사용하면 피벗 테이블을 생성할 수 있습니다. 피벗 테이블은 하나 이상의 측정기준을 기준으로 데이터를 피벗 (순환)하여 테이블의 정보를 재정렬하여 데이터를 시각화하는 데이터 요약 도구입니다.
예를 들어 다음과 같은 원시 데이터 테이블을 생각해 보세요.
이 데이터를 사용하여 국가 및 언어 측정기준을 추가 피벗으로 선택하여 브라우저별로 세션 데이터를 분류한 피벗 테이블을 구성할 수 있습니다.
핵심 보고서와 함께 제공되는 기능
피벗 보고 요청은 여러 공유 기능에 대한 핵심 보고서 요청과 동일한 의미 체계를 갖습니다. 예를 들어 페이지로 나누기, 측정기준 필터, 사용자 속성은 피벗 보고서에서 핵심 보고서와 동일하게 작동합니다. 이 가이드에서는 피벗 보고 기능을 중점적으로 설명합니다. Data API v1의 핵심 보고 기능을 숙지하려면 보고 기본사항 가이드와 고급 사용 사례 가이드를 참고하세요.
피벗 보고 방법
Data API v1은 다음 보고 메서드에서 피봇 기능을 지원합니다.
runPivotReport: Google 애널리틱스 이벤트 데이터의 맞춤설정된 피벗 보고서를 반환합니다. 각 피벗은 보고서 응답에 표시되는 측정기준 열과 행을 설명합니다.
batchRunPivotReports: 단일 API 호출을 사용하여 여러 보고서를 생성할 수 있는
runPivotReport메서드의 일괄 버전입니다.
보고 항목 선택
Data API v1의 모든 메서드는 다음과 같이 properties/GA4_PROPERTY_ID 형식의 URL 요청 경로 내에 Google 애널리틱스 4 속성 식별자를 지정해야 합니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
결과 보고서는 지정된 Google 애널리틱스 4 속성에서 수집된 Google 애널리틱스 이벤트 데이터를 기반으로 생성됩니다.
Data API 클라이언트 라이브러리 중 하나를 사용하는 경우 요청 URL 경로를 수동으로 조작할 필요가 없습니다. 대부분의 API 클라이언트는 properties/GA4_PROPERTY_ID 형식의 문자열을 예상하는 property 매개변수를 제공합니다. 클라이언트 라이브러리 사용 예는 빠른 시작 가이드를 참고하세요.
피벗 보고서 요청
피벗 테이블로 요청을 작성하려면 runPivotReport 또는 batchRunPivotReports 메서드를 사용합니다.
피벗된 데이터를 요청하려면 RunPivotReportRequest 객체를 구성하면 됩니다. 먼저 다음 요청 매개변수로 시작하는 것이 좋습니다.
- dateRanges 필드의 유효한 항목.
- 측정기준 필드에 유효한 항목이 1개 이상 있어야 합니다.
- metrics 입력란에 유효한 항목이 하나 이상 있어야 합니다.
- pivots 필드에 2개 이상의 유효한 피봇 항목이 있어야 합니다.
다음은 권장 필드가 포함된 샘플 요청입니다.
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
피봇
요청 본문의 pivot 필드에 있는 피봇 객체를 사용하여 보고서 피봇을 정의합니다. 각 Pivot은 보고서 응답에 표시되는 측정기준 열과 행을 설명합니다.
Data API v1은 각 피봇의 limit 매개변수의 곱이 100,000을 초과하지 않는 한 여러 피봇을 지원합니다.
다음은 pivots를 사용하여 browser 측정기준으로 피봇팅된 국가별 세션수 보고서를 작성하는 방법을 보여주는 스니펫입니다. 쿼리에서 정렬에 orderBys 필드를 사용하고 limit 및 offset 필드를 사용하여 페이지 나누기를 구현하는 방법을 확인하세요.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
크기
측정기준은 웹사이트 또는 앱의 이벤트 데이터를 설명하고 그룹화합니다. 예를 들어 city 측정기준은 각 이벤트가 발생한 도시 ('파리' 또는 '뉴욕')를 나타냅니다. 보고서 요청에서 측정기준을 0개 이상 지정할 수 있습니다.
측정기준은 요청 본문의 dimensions 필드 내에서 정의해야 합니다. 보고서에 표시되려면 이러한 측정기준이 Pivot 객체의 fieldNames 필드에도 나열되어야 합니다.
피봇 쿼리의 피봇에 사용되지 않은 측정기준은 보고서에 표시되지 않습니다. 피봇의 fieldNames에는 일부 측정기준이 포함되어서는 안 됩니다. 측정기준은 필터에서만 사용할 수 있고 피봇의 fieldNames에서는 사용할 수 없습니다.
다음은 browser, country, language 피벗이 있는 테이블의 dimension 및 fieldNames 필드 사용법을 보여주는 스니펫입니다.
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
측정항목
측정항목은 웹사이트 또는 앱의 이벤트 데이터의 양적 측정값입니다. 보고서 요청에서 하나 이상의 측정항목을 지정할 수 있습니다. 요청에 지정할 수 있는 API 측정항목 이름의 전체 목록은 API 측정항목을 참조하세요.
피벗 보고서 요청에서 측정항목은 요청 본문의 metrics 필드를 사용하여 정의되며, 이는 핵심 보고 방법과 유사합니다.
다음 예에서는 보고서에서 측정항목 값으로 사용할 세션 수를 지정합니다.
"metrics": [
{
"name": "sessions"
}
],
측정항목 집계
피봇 객체의 metricAggregations 필드를 사용하여 각 피봇에 대해 집계된 측정항목 값을 계산합니다.
집계는 요청에 metricAggregations 필드가 지정된 경우에만 계산됩니다.
다음은 browser 피벗 측정기준의 합계를 요청하는 쿼리의 스니펫입니다.
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
계산된 측정항목은 RunPivotReportResponse 객체의 aggregates 필드에 반환됩니다. 집계된 측정항목 행의 경우 dimensionValues 필드에 RESERVED_TOTAL, RESERVED_MAX 또는 RESERVED_MIN라는 특수한 값이 포함됩니다.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
페이지로 나누기
핵심 보고 메서드와 마찬가지로 피벗 요청을 사용하면 피벗 객체에서 한도 및 오프셋 필드를 지정하여 페이지로 나누기를 구현할 수 있습니다.
페이지로 나누기 설정은 각 피벗에 개별적으로 적용됩니다.
보고서 카디널리티를 제한하려면 모든 Pivot 객체에 limit 필드가 필요합니다.
Data API v1은 각 피봇의 limit 매개변수 곱이 100,000을 초과하지 않는 한 여러 피봇을 지원합니다.
다음은 offset 및 limit 필드를 사용하여 오프셋이 10인 다음 5개의 language 측정기준을 검색하는 방법을 보여주는 스니펫입니다.
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
필터링
핵심 보고 기능과 마찬가지로 피벗 보고 요청에서 측정기준 필터링이 필요한 경우 요청 범위 측정기준 필터를 사용해야 합니다.
정렬
피벗 보고서 쿼리의 순서 지정 동작은 OrderBy 객체 목록이 포함된 피봇 객체의 orderBys 필드를 사용하여 각 피벗별로 개별적으로 제어할 수 있습니다.
모든 OrderBy에는 다음 중 하나가 포함될 수 있습니다.
- DimensionOrderBy: 측정기준의 값을 기준으로 결과를 정렬합니다.
- MetricOrderBy: 측정항목 값을 기준으로 결과를 정렬합니다.
- 피벗 쿼리에서 사용되는 PivotOrderBy이며 피벗 열 그룹 내의 측정항목 값을 기준으로 결과를 정렬합니다.
이 예에서는 browser 측정기준을 기준으로 보고서를 피봇팅하여 sessions 측정항목을 기준으로 결과를 내림차순으로 정렬하는 피벗 정의의 스니펫을 보여줍니다.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
응답 신고
피벗 보고서 API 요청의 피벗 보고서 응답은 주로 헤더와 행입니다.
응답 헤더
피벗 보고서 헤더는 피벗 보고서의 열을 나열하는 PivotHeaders, DimensionHeaders, MetricHeaders로 구성됩니다.
예를 들어 browser, country, language 피봇 측정기준과 sessions 측정항목이 포함된 보고서는 다음과 같은 헤더를 생성합니다.
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
아래 차트는 피벗 보고서 렌더링에서 피벗 보고서 응답의 각 구성요소가 담당하는 역할을 보여줍니다.
응답 행
runPivotReport 및 batchRunPivotReports 메서드의 피벗 보고서 응답은 runReport 및 batchRunReports와 같은 핵심 보고 메서드의 응답과 다릅니다. 즉, 각 피벗 보고서 응답 행은 테이블의 단일 셀을 나타내지만 일반 보고서에서는 단일 응답 행이 테이블 행 전체를 나타냅니다.
다음은 browser, country, language 피봇 측정기준과 sessions 측정항목이 포함된 쿼리에 대한 피벗 보고서 응답의 일부입니다. 피벗 보고서의 각 셀이 개별적으로 반환됩니다.
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
이 데이터는 아래 표에서 강조 표시된 두 셀에 해당합니다.
클라이언트 라이브러리
클라이언트 라이브러리를 설치하고 구성하는 방법에 대한 설명은 빠른 시작 가이드를 참고하세요.
다음은 피벗 쿼리를 실행하여 브라우저 측정기준으로 피봇팅된 국가별 세션수 보고서를 작성하는 Python 클라이언트 라이브러리를 사용하는 예입니다.
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
데모 애플리케이션
자바스크립트를 사용하여 피벗 보고서를 작성하고 표시하는 방법의 예는 Google Analytics API v1 피벗 보고서 데모 애플리케이션을 참고하세요.