Google Analytics Data API v1 cho phép bạn tạo bảng tổng hợp. Xoay vòng bảng 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 xoay vòng (xoay vòng) dữ liệu của bạn trên một hoặc nhiều thứ nguyên.
Ví dụ: hãy xem xét bảng dữ liệu thô sau:
Bằng cách sử dụng dữ liệu này, bạn có thể xây dựng một bảng tổng hợp, chia nhỏ dữ liệu phiên theo trình duyệt, trong đó phương diện quốc gia và ngôn ngữ được chọn là các trục khác.
Các tính năng được chia sẻ với báo cáo cốt lõi
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 được chia sẻ. Ví dụ về tính năng phân trang, Bộ lọc phương diện và Người dùng Tài sản hoạt động giống nhau trong Báo cáo tổng hợp dưới dạng Báo cáo chính. Chiến dịch 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 Core Chức năng báo cáo 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 pháp báo cáo tổng hợp
Data API v1 hỗ trợ chức năng tổng hợp trong các phương thức báo cáo sau đây:
runPivotReport Phương pháp này sẽ trả về một báo cáo tổng hợp tuỳ chỉnh về dữ liệu sự kiện Google Analytics của bạn. Một Bảng tổng hợp 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à là phiên bản lô của phương thức
runPivotReportcho 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 giá trị nhận dạng tài sản Google Analytics
được chỉ định bên trong đường dẫn yêu cầu URL dưới 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 kết quả 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 được chỉ định.
Nếu bạn đang sử dụng một trong các thư viện ứng dụng Data API,
không cần thao tác đường dẫn URL yêu cầu theo cách thủ công. Hầu hết ứng dụng API
cung cấp tham số property mong đợi một chuỗi ở dạng
properties/GA_PROPERTY_ID Xem Hướng dẫn bắt đầu nhanh
để xem 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 runPivotReport hoặc batchRunPivotReports .
Để yêu cầu dữ liệu được tổng hợp, bạn có thể tạo RunPivotReportRequest . Bạn nên bắt đầu với các thông số yêu cầu sau:
- Giá trị 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.
- Có ít nhất một mục hợp lệ trong trường chiso (chỉ số).
- Ít nhất hai mục nhập tổng hợp hợp lệ trong trường tổng hợp.
Dưới đây là yêu cầu mẫu với 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
}
]
}
Xoay vòng
Sử dụng các đối tượng Pivot (Tổng hợp) trong trường pivot của yêu cầu
nội dung để xác định các trụ báo cáo. Mỗi Pivot mô tả phương diện hiển thị
các cột và hàng trong phản hồi báo cáo.
Data API v1 hỗ trợ nhiều bảng tổng hợp miễn là sản phẩm của giới hạn này 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 tổng hợp theo phương diện browser. Lưu ý cách
sử dụng trường orderBys cho
sắp xếp, giới hạn và
Trường phần bù để 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 bắt nguồn từng sự kiện. 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 thứ nguyên bên trong
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 fieldNames
của đối tượng Pivot.
Một phương diện sẽ không xuất hiện trong một báo cáo nếu không được sử dụng trong bất kỳ
bảng tổng hợp truy vấn. Không phải mọi phương diện đều phải hiển thị trong
fieldNames. Bạn chỉ có thể sử dụng thứ nguyê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 bảng có trụ 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 lường đị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 bài viết Chỉ số API để biết danh sách đầy đủ tên các chỉ số API có sẵn để chỉ định trong các yêu cầu.
Trong yêu cầu báo cáo tổng hợp, các chỉ số được xác định bằng cách sử dụng trường metrics của
nội dung yêu cầu, tương tự như Phương thức báo cáo chính.
Ví dụ bên dưới chỉ định số phiên để sử dụng làm giá trị chỉ số trong báo cáo:
"metrics": [
{
"name": "sessions"
}
],
Tổng hợp chỉ số
Sử dụng metricAggregations trường của đối tượng Pivot (Tổng hợp) để tính toán chỉ số tổng hợp cho mỗi bảng tổng hợp.
Các số liệu tổng hợp sẽ chỉ được tính nếu các metricAggregations được chỉ định trong yêu cầu.
Dưới đây là một đoạn mã của truy vấn yêu cầu tổng số cho
browser phương diện tổng hợp:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Các chỉ số đã tính toán được trả về dưới dạng dữ liệu tổng hợp
trường của RunPivotReportResponse
. Đối với các hàng chỉ số tổng hợp, trường dimensionValues
chứa giá trị đặc biệt của 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ư các phương pháp báo cáo chính, yêu cầu tổng hợp cho phép bạn
để xác định giới hạn
và phần bù trong trường
Đối tượng Tổng hợp để triển khai tính năng phân trang.
Các 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à trường bắt buộc cho mọi đối tượng Pivot để giới hạn
báo cáo lượng số.
Data API v1 hỗ trợ nhiều bảng tổng hợp, miễn là sản phẩm của 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 năm thứ nguyê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ộ lọc phương diện trong phạm vi yêu cầu phải được sử dụng nếu muốn lọc phương diện trong báo cáo tổng hợp của bạn.
Sắp xếp
Có thể kiểm soát hành vi sắp xếp theo thứ tự của các truy vấn báo cáo tổng hợp cho mỗi bảng tổng hợp bằng cách sử dụng hàm orderBys trường của đối tượng Pivot, chứa danh sách Đố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ắp xếp kết quả theo giá trị của chỉ số.
- PivotOrderBy, được sử dụng trong tổng hợp truy vấn và sắp xếp kết quả theo giá trị của một chỉ số trong nhóm cột tổng hợp.
Ví dụ này hiển thị một đoạn mã cho định nghĩa bảng tổng hợp xoay quanh báo cáo
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 trong báo cáo tổng hợp của một bảng tổng hợp yêu cầu API báo cáo 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 các cột trong báo cáo tổng hợp.
Ví dụ: báo cáo có các phương diện tổng hợp browser, country và language
và chỉ số sessions sẽ tạo ra 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 Báo cáo tổng hợp Phản hồi khi hiển thị báo cáo tổng hợp:
Hàng phản hồi
Phản hồi cho báo cáo tổng hợp của 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 ô duy nhất của , trong khi trong báo cáo thông thường, một hàng phản hồi đơn lẻ thể hiện đầy đủ dòng trong bảng.
Dưới đây là phân đoạn của phản hồi trong báo cáo tổng hợp cho một
với các phương diện tổng hợp browser, country và language cùng với phương diện
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 làm nổi bật trong bảng bên dưới:
Thư viện ứng dụng
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 một báo cáo về số 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ạ
Xem Bản minh hoạ báo cáo tổng hợp của API Google Analytics phiên bản 1 ứng dụng để xem ví dụ về cách tạo và hiển thị báo cáo tổng hợp bằng JavaScript.