Google Analytics Data API v1 به شما امکان می دهد جداول محوری ایجاد کنید. جداول محوری ابزاری برای خلاصه‌سازی داده‌ها هستند که داده‌ها را با مرتب کردن مجدد اطلاعات در جدول با چرخش (چرخش) داده‌های شما در یک یا چند بعد، تجسم می‌کنند.
به عنوان مثال، جدول داده های خام زیر را در نظر بگیرید:
با استفاده از این داده ها می توان یک جدول محوری ایجاد کرد، داده های جلسات را بر اساس مرورگر تجزیه کرد، با ابعاد کشور و زبان به عنوان محورهای اضافی انتخاب شده است.
ویژگی های مشترک با گزارش های اصلی
درخواست های گزارش محوری برای بسیاری از ویژگی های مشترک معنایی مشابه با درخواست های گزارش اصلی دارند. برای مثال صفحه‌بندی، فیلترهای ابعاد و ویژگی‌های کاربر، در گزارش‌های محوری مانند گزارش‌های اصلی رفتار می‌کنند. این راهنما بر ویژگی های گزارش محوری تمرکز دارد. برای آشنایی با عملکرد اصلی گزارش‌دهی Data API v1، راهنمای اصول گزارش‌دهی و همچنین راهنمای موارد استفاده پیشرفته را بخوانید.
روش های گزارش محوری
Data API v1 از عملکرد محوری در روش های گزارش زیر پشتیبانی می کند:
runPivotReport این روش یک گزارش محوری سفارشی از داده‌های رویداد Google Analytics شما را برمی‌گرداند. هر محور، ستون‌ها و ردیف‌های بعد قابل مشاهده را در پاسخ گزارش توصیف می‌کند.
batchRunPivotReports این یک نسخه دسته ای از روش
runPivotReportاست که امکان تولید چندین گزارش با استفاده از یک فراخوانی API را فراهم می کند.
انتخاب یک نهاد گزارشگر
همه روش‌های Data API v1 نیاز دارند که شناسه ویژگی Google Analytics در یک مسیر درخواست URL به شکل properties/GA_PROPERTY_ID مشخص شود، مانند:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
گزارش حاصل بر اساس داده‌های رویداد Google Analytics جمع‌آوری‌شده در ویژگی Google Analytics مشخص شده ایجاد می‌شود.
اگر از یکی از کتابخانه های سرویس گیرنده Data API استفاده می کنید، نیازی به دستکاری مسیر URL درخواست به صورت دستی نیست. اکثر کلاینت‌های API یک پارامتر property ارائه می‌کنند که انتظار رشته‌ای به شکل properties/GA_PROPERTY_ID را دارد. برای مثال هایی از استفاده از کتابخانه های سرویس گیرنده ، راهنمای شروع سریع را ببینید.
درخواست گزارش محوری
برای ساخت یک درخواست با جدول محوری، از روش runPivotReport یا batchRunPivotReports استفاده کنید.
برای درخواست داده های محوری، می توانید یک شی RunPivotReportRequest بسازید. توصیه می کنیم با این پارامترهای درخواست شروع کنید:
- یک ورودی معتبر در قسمت dateRanges .
- حداقل یک ورودی معتبر در قسمت ابعاد .
- حداقل یک ورودی معتبر در قسمت معیارها .
- حداقل دو ورودی معتبر محوری در قسمت محورها .
در اینجا یک نمونه درخواست با فیلدهای توصیه شده وجود دارد:
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
}
]
}
محورها
از اشیاء Pivot در فیلد pivot بدنه درخواست برای تعریف محورهای گزارش استفاده کنید. هر Pivot ستون‌ها و ردیف‌های بعد قابل مشاهده را در پاسخ گزارش توصیف می‌کند.
Data API v1 از چندین محور پشتیبانی می کند تا زمانی که حاصلضرب پارامتر حد برای هر محور از 100000 تجاوز نکند.
در زیر قطعه ای وجود دارد که استفاده از pivots را برای ایجاد گزارشی از تعداد جلسات بر اساس کشور، با محوریت بعد browser نشان می دهد. توجه داشته باشید که پرس و جو چگونه از فیلد orderBys برای مرتب سازی و از فیلدهای محدود و افست برای پیاده سازی صفحه بندی استفاده می کند.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
ابعاد
ابعاد، داده‌های رویداد را برای وب‌سایت یا برنامه شما توصیف و گروه‌بندی می‌کند. برای مثال، بعد city ، شهری ("پاریس" یا "نیویورک") را نشان می دهد که هر رویداد از آن سرچشمه گرفته است. در یک درخواست گزارش، می توانید ابعاد صفر یا بیشتر را مشخص کنید.
ابعاد باید در قسمت ابعاد بدنه درخواستی تعریف شود. برای اینکه در یک گزارش قابل مشاهده باشند، آن ابعاد باید در فیلد Names یک شی Pivot نیز فهرست شوند. یک بعد در صورتی که در هیچ محوری از پرس و جوی محوری استفاده نشود در گزارش قابل مشاهده نخواهد بود. هر بعد نباید در fieldNames محوری وجود داشته باشدNames . ابعاد را می توان منحصراً در فیلترها استفاده کرد و نه در fieldNames هر محوری.
در زیر قطعه ای وجود دارد که استفاده از فیلدهای dimension و fieldNames را برای یک جدول با محورهای browser ، country و language نشان می دهد:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
معیارها
معیارها اندازه گیری کمی داده های رویداد برای وب سایت یا برنامه شما هستند. در یک درخواست گزارش، می توانید یک یا چند معیار را مشخص کنید. برای فهرست کامل نام‌های API Metric موجود برای مشخص شدن در درخواست‌ها، به معیارهای API مراجعه کنید.
در درخواست‌های گزارش محوری، معیارها با استفاده از فیلد metrics بدنه درخواست تعریف می‌شوند که مشابه روش‌های گزارش اصلی است.
مثال زیر تعداد جلسات را برای استفاده به عنوان یک مقدار متریک در گزارش مشخص می کند:
"metrics": [
{
"name": "sessions"
}
],
تجمعات متریک
از فیلد metricAggregations یک شی Pivot برای محاسبه مقادیر متریک انبوه برای هر محور استفاده کنید.
تجمیع‌ها تنها در صورتی محاسبه می‌شوند که فیلد metricAggregations در یک درخواست مشخص شده باشد.
در زیر قطعه ای از یک پرس و جو است که مجموع ها را برای بعد محوری browser درخواست می کند:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
معیارهای محاسبه شده در فیلد مجموعات شی RunPivotReportResponse برگردانده می شوند. برای ردیف‌های متریک انبوه، فیلد 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 برای هر شی Pivot لازم است تا کاردینالیته گزارش محدود شود.
Data API v1 از چندین محور پشتیبانی می کند تا زمانی که حاصلضرب پارامتر limit برای هر محور از 100000 تجاوز نکند.
در زیر قطعه ای وجود دارد که استفاده از فیلدهای offset و limit را برای بازیابی پنج بعد language بعدی با افست 10 نشان می دهد:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
فیلتر کردن
مشابه عملکرد گزارش اصلی ، اگر فیلتر ابعاد در درخواست گزارش محوری مورد نظر باشد، باید از فیلتر ابعاد با محدوده درخواست استفاده شود.
مرتب سازی
رفتار ترتیب کوئری های گزارش محوری را می توان برای هر محور به صورت جداگانه با استفاده از فیلد orderBys یک شی Pivot که حاوی لیستی از اشیاء OrderBy است، کنترل کرد.
هر OrderBy می تواند شامل یکی از موارد زیر باشد:
- DimensionOrderBy ، نتایج را بر اساس مقادیر یک بعد مرتب می کند.
- MetricOrderBy ، نتایج را بر اساس مقادیر یک متریک مرتب می کند.
- PivotOrderBy ، در جستارهای محوری استفاده می شود و نتایج را بر اساس مقادیر یک متریک در یک گروه ستون محوری مرتب می کند.
این مثال قطعه‌ای را برای تعریف محوری نشان می‌دهد که گزارش را در بعد browser محوری می‌کند و نتایج را بر اساس متریک sessions به ترتیب نزولی مرتب می‌کند.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
گزارش پاسخ
پاسخ گزارش محوری درخواست API گزارش محوری در درجه اول یک سرصفحه و ردیف است.
سرصفحه های پاسخ
سرصفحه گزارش محوری شامل PivotHeaders ، DimensionHeaders و MetricHeader است که ستون‌های گزارش محوری را فهرست می‌کند.
به عنوان مثال، گزارشی با ابعاد محوری 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"
}
]
},
...
]
این داده مربوط به دو سلول مشخص شده در جدول زیر است:
کتابخانه های مشتری
برای توضیح نحوه نصب و پیکربندی کتابخانه های سرویس گیرنده، به راهنمای شروع سریع مراجعه کنید.
مثال‌های زیر از کتابخانه مشتری برای اجرای یک پرس و جو محوری برای ایجاد گزارشی از تعداد جلسات بر اساس کشور، با محوریت بعد مرورگر استفاده می‌کند.
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()
);
}
}
پایتون
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);
});
});
}
برنامه آزمایشی
برای مثالی از نحوه ساخت و نمایش یک گزارش محوری با استفاده از جاوا اسکریپت، به برنامه آزمایشی Google Analytics API v1 Pivot Report مراجعه کنید.