Google Analytics Data API phiên bản 1 cho phép bạn tạo bảng tổng hợp. Bảng tổng hợp là công cụ tóm tắt dữ liệu trực quan hoá dữ liệu bằng cách sắp xếp lại thông tin trong bảng bằng cách tổng hợp (xoay) dữ liệu của bạn trên một hoặc nhiều phương diện.
Ví dụ: hãy xem xét bảng dữ liệu thô sau đây:
Khi sử dụng dữ liệu này, bạn có thể tạo bảng tổng hợp, chia nhỏ dữ liệu phiên theo trình duyệt, với các phương diện quốc gia và ngôn ngữ được chọn làm bảng tổng hợp bổ sung.
Các tính năng được chia sẻ với báo cáo chính
Các yêu cầu báo cáo tổng hợp có cùng ngữ nghĩa với các yêu cầu báo cáo chính cho nhiều tính năng dùng chung. Ví dụ: tính năng phân trang, Bộ lọc phương diện và Thuộc tính người dùng hoạt động giống như trong Báo cáo tổng hợp như Báo cáo chính. Hướng dẫn này tập trung vào các tính năng báo cáo tổng hợp. Để làm quen với chức năng Báo cáo cốt lõi của Data API phiên bản 1, hãy đọc hướng dẫn cơ bản về báo cáo cũng như hướng dẫn các trường hợp sử dụng nâng cao.
Phương pháp báo cáo tổng hợp
Data API phiên bản 1 hỗ trợ chức năng tổng hợp trong các phương thức báo cáo sau:
runPivotReport Phương thức này trả về báo cáo tổng hợp tuỳ chỉnh về dữ liệu sự kiện của bạn trên Google Analytics. Mỗi trung tâm mô tả các hàng và cột phương diện hiển thị trong nội dung phản hồi báo cáo.
batchRunPivotReports Đây là phiên bản hàng loạt của phương thức
runPivotReport
cho phép tạo nhiều báo cáo bằng một lệnh gọi API duy nhất.
Chọn đối tượng báo cáo
Tất cả các phương thức của Data API phiên bản 1 đều yêu cầu phải chỉ định giá trị nhận dạng thuộc tính Google Analytics 4
bên trong đường dẫn yêu cầu URL ở dạng
properties/GA4_PROPERTY_ID
, chẳng hạn như:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
Báo cáo thu được sẽ được tạo dựa trên dữ liệu sự kiện Google Analytics được thu thập trong tài sản Google Analytics 4 được chỉ định.
Nếu đang sử dụng một trong những thư viện ứng dụng Data API, bạn không cần phải thao tác trên đường dẫn URL yêu cầu theo cách thủ công. Hầu hết các ứng dụng API đều cung cấp tham số property
dự kiến sẽ có một chuỗi ở dạng properties/GA4_PROPERTY_ID
. Xem Hướng dẫn bắt đầu nhanh để biết các ví dụ về cách sử dụng thư viện ứng dụng.
Yêu cầu báo cáo tổng hợp
Để tạo yêu cầu bằng bảng tổng hợp, hãy sử dụng phương thức runPivotReport hoặc phương thức batchRunPivotReports.
Để yêu cầu dữ liệu được tổng hợp, bạn có thể tạo đối tượng RunPivotReportRequest. Bạn nên bắt đầu với các tham số yêu cầu sau:
- Mục nhập hợp lệ trong trường dateRanges.
- Ít nhất một mục nhập hợp lệ trong trường phương diện.
- Ít nhất một mục nhập hợp lệ trong trường metrics.
- Ít nhất hai mục tổng hợp hợp lệ trong trường thông tin tổng hợp.
Dưới đây là một yêu cầu mẫu có các trường đề xuất:
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
}
]
}
Tổng hợp
Sử dụng các đối tượng Pivot (Tổng hợp) trong trường pivot
của nội dung yêu cầu để xác định các tổng hợp báo cáo. Mỗi Pivot
mô tả các hàng và cột phương diện hiển thị trong nội dung phản hồi báo cáo.
Data API v1 hỗ trợ nhiều bảng tổng hợp,miễn là tích của tham số giới hạn cho mỗi bảng tổng hợp không vượt quá 100.000.
Dưới đây là đoạn mã minh hoạ cách sử dụng pivots
để tạo báo cáo về số phiên theo quốc gia, được chuyển hướng theo phương diện browser
. Lưu ý cách truy vấn sử dụng trường orderBys để sắp xếp, cũng như các trường limit và offset để triển khai tính năng phân trang.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Kích thước
Phương diện mô tả và nhóm dữ liệu sự kiện cho trang web hoặc ứng dụng của bạn. Ví dụ: phương diện city
cho biết thành phố ("Paris" hoặc "New York") mà mỗi sự kiện bắt nguồn. Trong yêu cầu báo cáo, bạn có thể
chỉ định số không hoặc nhiều phương diện.
Bạn phải xác định phương diện bên trong trường
phương diện
của nội dung yêu cầu. Để hiển thị trong báo cáo, các phương diện đó cũng phải được liệt kê trong trường fieldNames của đối tượng Pivot
.
Một phương diện sẽ không hiển thị trong báo cáo nếu không được dùng trong bất kỳ trung tâm nào của truy vấn tổng hợp. Không phải phương diện nào cũng phải có trong fieldNames
của bảng tổng hợp. Bạn chỉ có thể sử dụng phương diện trong bộ lọc, chứ không phải trong fieldNames
của bất kỳ bảng tổng hợp nào.
Dưới đây là đoạn mã minh hoạ cách sử dụng các trường dimension
và fieldNames
cho một bảng có các bảng tổng hợp browser
, country
và language
:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Chỉ số
Chỉ số là các phép đo định lượng dữ liệu sự kiện cho trang web hoặc ứng dụng của bạn. Trong yêu cầu báo cáo, bạn có thể chỉ định một hoặc nhiều chỉ số. Hãy xem phần Chỉ số API để biết danh sách đầy đủ các tên Chỉ số API có sẵn để chỉ định trong các yêu cầu.
Trong các yêu cầu báo cáo tổng hợp, các chỉ số được xác định bằng trường metrics
của nội dung yêu cầu, tương tự như các phương thức Báo cáo chính.
Ví dụ bên dưới chỉ định số phiên sẽ được sử dụng làm giá trị chỉ số trong báo cáo:
"metrics": [
{
"name": "sessions"
}
],
Tổng hợp các chỉ số
Sử dụng trường metricAggregations của đối tượng Tổng hợp để tính toán các giá trị chỉ số tổng hợp cho mỗi bảng tổng hợp.
Hệ thống sẽ chỉ tính toán dữ liệu tổng hợp nếu trường metricAggregations được chỉ định trong một yêu cầu.
Dưới đây là đoạn mã của truy vấn yêu cầu tổng số cho thứ nguyên tổng hợp browser
:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Các chỉ số đã tính được trả về trong trường aggregate
(tổng hợp) của đối tượng RunPivotReportResponse. Đối với các hàng chỉ số tổng hợp, trường dimensionValues
chứa giá trị đặc biệt là RESERVED_TOTAL
, RESERVED_MAX
hoặc 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"
}
]
},
....
}
Phân trang
Tương tự như phương thức Báo cáo chính, yêu cầu tổng hợp cho phép bạn chỉ định các trường giới hạn và bồi thường trong đối tượng Pivot để triển khai tính năng phân trang.
Chế độ cài đặt phân trang được áp dụng riêng cho từng bảng tổng hợp.
Trường limit
là bắt buộc cho mọi đối tượng Pivot
để giới hạn số lượng giá trị riêng biệt của báo cáo.
Data API v1 hỗ trợ nhiều bảng tổng hợp miễn là tích của tham số limit
cho mỗi bảng tổng hợp không vượt quá 100.000.
Dưới đây là đoạn mã minh hoạ cách sử dụng các trường offset
và limit
để truy xuất 5 kích thước language
tiếp theo với độ lệch là 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Lọc
Tương tự như chức năng Báo cáo chính, bạn phải sử dụng bộ lọc phương diện trong phạm vi yêu cầu nếu muốn lọc phương diện trong yêu cầu báo cáo tổng hợp.
Sắp xếp
Bạn có thể kiểm soát hành vi sắp xếp của các truy vấn báo cáo tổng hợp cho từng bảng tổng hợp bằng cách sử dụng trường orderBys của đối tượng Pivot (Trục), trong đó có chứa danh sách các đối tượng OrderBy.
Mỗi OrderBy
có thể chứa một trong các nội dung sau:
- DimensionOrderBy, sắp xếp kết quả theo giá trị của một phương diện.
- MetricOrderBy sẽ sắp xếp kết quả theo giá trị của một chỉ số.
- PivotOrderBy, dùng trong truy vấn tổng hợp và sắp xếp kết quả theo giá trị của một chỉ số trong một nhóm cột tổng hợp.
Ví dụ này cho thấy một đoạn mã cho định nghĩa tổng hợp làm xoay vòng báo cáo trên phương diện browser
, sắp xếp kết quả theo chỉ số sessions
theo thứ tự giảm dần.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Phản hồi báo cáo
Phản hồi báo cáo tổng hợp của yêu cầu API báo cáo tổng hợp chủ yếu là một tiêu đề và các hàng.
Tiêu đề phản hồi
Tiêu đề báo cáo tổng hợp bao gồm PivotHeaders, DimensionHeaders và MetricHeaders. Các cột này liệt kê các cột trong báo cáo tổng hợp.
Ví dụ: báo cáo có thứ nguyên tổng hợp browser
, country
và language
và chỉ số sessions
sẽ tạo ra các tiêu đề như sau:
{
"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"
}
],
...
}
Biểu đồ bên dưới minh hoạ vai trò của từng thành phần của Phản hồi báo cáo tổng hợp trong việc hiển thị báo cáo tổng hợp:
Hàng phản hồi
Phản hồi báo cáo tổng hợp của phương thức runPivotReport và batchRunPivotReports khác với phản hồi cho các phương thức Báo cáo chính như runReport và batchRunReports trong đó mỗi hàng phản hồi của báo cáo tổng hợp đại diện cho một ô của bảng, trong khi trong báo cáo thông thường, chỉ có một hàng phản hồi biểu thị một dòng bảng hoàn chỉnh.
Dưới đây là một mảnh của phản hồi trong báo cáo tổng hợp cho một truy vấn có các phương diện tổng hợp browser
, country
và language
cũng như chỉ số sessions
. Mỗi ô của báo cáo tổng hợp được trả về riêng lẻ:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Dữ liệu này tương ứng với hai ô được đánh dấu trong bảng dưới đây:
Thư viện ứng dụng
Hãy xem Hướng dẫn bắt đầu nhanh để được giải thích về cách cài đặt và định cấu hình thư viện ứng dụng.
Các ví dụ sau đây sử dụng thư viện ứng dụng để chạy một truy vấn tổng hợp nhằm tạo báo cáo về số phiên theo quốc gia, được tổng hợp theo phương diện của trình duyệt.
1.199
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient; use Google\Analytics\Data\V1beta\DateRange; use Google\Analytics\Data\V1beta\Dimension; use Google\Analytics\Data\V1beta\Metric; use Google\Analytics\Data\V1beta\OrderBy; use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy; use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy; use Google\Analytics\Data\V1beta\Pivot; use Google\Analytics\Data\V1beta\RunPivotReportRequest; use Google\Analytics\Data\V1beta\RunPivotReportResponse; /** * Runs a pivot query to build a report of session counts by country, * pivoted by the browser dimension. * @param string $propertyId Your GA-4 Property ID */ function run_pivot_report(string $propertyId) { // Create an instance of the Google Analytics Data API client library. $client = new BetaAnalyticsDataClient(); // Make an API call. $request = (new RunPivotReportRequest()) ->setProperty('properties/' . $propertyId) ->setDateRanges([new DateRange([ 'start_date' => '2021-01-01', 'end_date' => '2021-01-30', ]), ]) ->setPivots([ new Pivot([ 'field_names' => ['country'], 'limit' => 250, 'order_bys' => [new OrderBy([ 'dimension' => new DimensionOrderBy([ 'dimension_name' => 'country', ]), ])], ]), new Pivot([ 'field_names' => ['browser'], 'offset' => 3, 'limit' => 3, 'order_bys' => [new OrderBy([ 'metric' => new MetricOrderBy([ 'metric_name' => 'sessions', ]), 'desc' => true, ])], ]), ]) ->setMetrics([new Metric(['name' => 'sessions'])]) ->setDimensions([ new Dimension(['name' => 'country']), new Dimension(['name' => 'browser']), ]); $response = $client->runPivotReport($request); printPivotReportResponse($response); } /** * Print results of a runPivotReport call. * @param RunPivotReportResponse $response */ function printPivotReportResponse(RunPivotReportResponse $response) { print 'Report result: ' . PHP_EOL; foreach ($response->getRows() as $row) { printf( '%s %s' . PHP_EOL, $row->getDimensionValues()[0]->getValue(), $row->getMetricValues()[0]->getValue() ); } }
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)
Node.js
// TODO(developer): Uncomment this variable and replace with your // Google Analytics 4 property ID before running the sample. // propertyId = 'YOUR-GA4-PROPERTY-ID'; // Imports the Google Analytics Data API client library. const {BetaAnalyticsDataClient} = require('@google-analytics/data'); // Initialize client that will be used to send requests. This client only // needs to be created once, and can be reused for multiple requests. const analyticsDataClient = new BetaAnalyticsDataClient(); // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension. async function runPivotReport() { const [response] = await analyticsDataClient.runPivotReport({ property: `properties/${propertyId}`, 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', }, ], }); printPivotReportResponse(response); } runPivotReport(); // Prints results of a runReport call. function printPivotReportResponse(response) { console.log('Report result:'); response.rows.forEach(row => { row.dimensionValues.forEach(dimensionValue => { console.log(dimensionValue.value); }); row.metricValues.forEach(metricValue => { console.log(metricValue.value); }); }); }
Ứng dụng minh hoạ
Hãy xem ứng dụng minh hoạ báo cáo tổng hợp API phiên bản 1 của Google Analytics để biết ví dụ về cách tạo và hiển thị báo cáo tổng hợp bằng JavaScript.