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à một công cụ tóm tắt dữ liệu, giúp trực quan hoá dữ liệu bằng cách sắp xếp lại thông tin trong bảng thông qua việc tổng hợp (xoay) dữ liệu theo một hoặc nhiều phương diện.
Ví dụ: hãy xem xét bảng dữ liệu thô sau:
Khi sử dụng dữ liệu này, bạn có thể tạo một bảng tổng hợp, phân tích 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 các bảng tổng hợp bổ sung.
Các tính năng dùng chung với báo cáo Core
Yêu cầu báo cáo tổng hợp có cùng ngữ nghĩa với 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 nhau trong Báo cáo tổng hợp và 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 chính 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 về các trường hợp sử dụng nâng cao.
Phương thức 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ề một 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 bảng tổng hợp mô tả các cột và hàng phương diện hiển thị trong phản hồi báo cáo.
batchRunPivotReports Đây là phiên bản theo lô 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 một pháp nhân báo cáo
Tất cả phương thức của API Dữ liệu phiên bản 1 đều yêu cầu bạn chỉ định mã nhận dạng tài sản Google Analytics trong đường dẫn yêu cầu URL ở dạng properties/GA_PROPERTY_ID, chẳng hạn như:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Báo cáo thu được sẽ được tạo dựa trên dữ liệu sự kiện của Google Analytics được thu thập trong tài sản Google Analytics được chỉ định.
Nếu đang sử dụng một trong các thư viện ứng dụng Data API, bạn không cần phải thao tác với đường dẫn URL yêu cầu theo cách thủ công. Hầu hết ứng dụng API đều cung cấp tham số property yêu cầu một chuỗi ở dạng properties/GA_PROPERTY_ID. Xem Hướng dẫn bắt đầu nhanh để biết 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 một yêu cầu có bảng tổng hợp, hãy sử dụng phương thức runPivotReport hoặc batchRunPivotReports.
Để yêu cầu dữ liệu tổng hợp, bạn có thể tạo một đối tượng RunPivotReportRequest. Bạn nên bắt đầu bằng các tham số yêu cầu sau:
- Một mục hợp lệ trong trường dateRanges.
- Ít nhất một mục hợp lệ trong trường kích thước.
- Ít nhất một mục hợp lệ trong trường metrics.
- Ít nhất hai mục nhập bảng tổng hợp hợp lệ trong trường pivots.
Dưới đây là một yêu cầu mẫu có các trường được đề xuất:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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
}
]
}
Trục xoay
Sử dụng đối tượng Pivot trong trường pivot của nội dung yêu cầu để xác định bảng tổng hợp báo cáo. Mỗi Pivot mô tả các cột và hàng phương diện hiển thị trong phản hồi báo cáo.
Data API phiên bản 1 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.
Đoạn mã sau đây minh hoạ cách sử dụng pivots để tạo
báo cáo về số phiên theo quốc gia, được tổng hợp 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") nơi mỗi sự kiện bắt đầu. Trong yêu cầu báo cáo, bạn có thể chỉ định 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 dimensions của nội dung yêu cầu. Để xuất hiện 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 xuất hiện trong báo cáo nếu không được sử dụng trong bất kỳ
trục 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 thể sử dụng trong fieldNames của bất kỳ bảng tổng hợp nào.
Đoạn mã sau đây 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à số đo định lượng của 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ó thể được chỉ định trong 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ụ sau đây chỉ định số phiên được dùng làm giá trị chỉ số trong một báo cáo:
"metrics": [
{
"name": "sessions"
}
],
Tổng hợp chỉ số
Sử dụng trường metricAggregations của đối tượng Pivot để tính giá trị chỉ số tổng hợp cho mỗi bảng tổng hợp.
Các dữ liệu tổng hợp sẽ chỉ được tính nếu trường metricAggregations được chỉ định trong một yêu cầu.
Ví dụ sau đây là một đoạn mã của một truy vấn yêu cầu tổng số cho phương diện tổng hợp browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Các chỉ số được tính toán sẽ được trả về trong trường aggregates của đối tượng RunPivotReportResponse. Đối với các hàng chỉ số tổng hợp, trường dimensionValues chứa một 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 limit và offset 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 đối với mọi đối tượng Pivot để giới hạn số lượng giá trị riêng biệt trong báo cáo.
Data API phiên bản 1 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.
Đoạn mã sau đây minh hoạ cách sử dụng các trường offset và limit để truy xuất 5 phương diện 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, trong đó có danh sách các đối tượng OrderBy.
Mỗi OrderBy có thể chứa một trong những thông tin sau:
- DimensionOrderBy, sắp xếp kết quả theo giá trị của một phương diện.
- MetricOrderBy, sắp xếp kết quả theo giá trị của một chỉ số.
- PivotOrderBy, được dùng trong truy vấn tổng hợp và sắp xếp kết quả theo giá trị của 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 bảng tổng hợp, trong đó xoay báo cáo theo 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
}
]
}
Báo cáo câu trả lời
Phản hồi báo cáo tổng hợp của một yêu cầu API báo cáo tổng hợp chủ yếu là 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 liệt kê các cột trong báo cáo tổng hợp.
Ví dụ: một báo cáo có các phương diện tổng hợp browser, country và language cùng 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 đồ sau đây minh hoạ vai trò của từng thành phần trong Phản hồi báo cáo tổng hợp khi 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 các 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 ở chỗ mỗi hàng phản hồi báo cáo tổng hợp đại diện cho một ô của bảng, trong khi ở báo cáo thông thường, một hàng phản hồi đại diện cho một dòng hoàn chỉnh của bảng.
Ví dụ sau đây cho thấy một đoạn phản hồi 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 và 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 sau:
Thư viện ứng dụng
Hãy xem Hướng dẫn bắt đầu nhanh để biết thông tin 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ố lượng phiên theo quốc gia, được tổng hợp theo phương diện trình duyệt.
PHP
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 của Google Analytics API phiên bản 1 để biết ví dụ về cách tạo và hiển thị báo cáo tổng hợp bằng JavaScript.