Google Analytics Data API v1 به شما امکان می‌دهد جدول‌های محوری ایجاد کنید. جدول‌های محوری ابزاری برای خلاصه کردن داده‌ها هستند که با بازآرایی اطلاعات در جدول ازطریق محور قرار دادن (چرخاندن) داده‌ها در یک یا چند بعد، داده‌ها را تجسم می‌کنند.
به‌عنوان مثال، جدول داده‌های خام زیر را درنظر بگیرید:
بااستفاده از این داده‌ها می‌توان جدول محوری ساخت و داده‌های جلسه را براساس مرورگر تفکیک کرد و ابعاد کشور و زبان را به‌عنوان محورهای اضافی انتخاب کرد.
ویژگی‌های مشترک با گزارش‌های «اصلی»
درخواست‌های گزارش Pivot برای بسیاری از ویژگی‌های مشترک، معناشناسی یکسانی با درخواست‌های گزارش Core دارند. برای مثال، صفحه‌بندی، فیلترهای بُعد، و ویژگی‌های کاربر در «گزارش‌های محوری» و «گزارش‌های اصلی» رفتار یکسانی دارند. این راهنما بر ویژگی‌های گزارش‌دهی محوری تمرکز دارد. برای آشنایی با عملکرد Core Reporting در Data API v1، راهنمای اصول گزارش‌دهی و همچنین راهنمای موارد استفاده پیشرفته را بخوانید.
روش‌های گزارش‌دهی محوری
Data API v1 از عملکرد محوری در روش‌های گزارش‌دهی زیر پشتیبانی می‌کند:
runPivotReport این روش گزارش محوری سفارشی‌شده‌ای از داده‌های رویداد Google Analytics شما برمی‌گرداند. هر محور ستون‌ها و ردیف‌های بُعد قابل‌مشاهده را در پاسخ گزارش شرح می‌دهد.
batchRunPivotReports این نسخه دسته‌ای از روش
runPivotReportاست که امکان تولید چند گزارش را بااستفاده از یک فراخوانی API فراهم می‌کند.
انتخاب نهاد گزارش‌دهنده
همه روش‌های Data API v1 نیاز دارند که
شناسه دارایی Google Analytics در داخل
مسیر درخواست نشانی وب به‌شکل properties/GA_PROPERTY_ID مشخص شود، مانند:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
گزارش حاصل براساس داده‌های رویداد Google Analytics که در دارایی Google Analytics مشخص‌شده جمع‌آوری شده است، تولید خواهد شد.
اگر از یکی از کتابخانه‌های کارخواه Data 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 از چند محور پشتیبانی می‌کند، به‌شرطی که حاصل‌ضرب پارامتر limit برای هر محور از ۱۰۰٬۰۰۰ بیشتر نشود.
تکه‌کد زیر نحوه استفاده از 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 نشان‌دهنده شهری («پاریس» یا «نیویورک») است که هر رویداد از آن نشئت گرفته است. در درخواست گزارش، می‌توانید
صفر یا چند بُعد را مشخص کنید.
ابعاد باید در فیلد
dimensions
در متن درخواست تعریف شود. برای اینکه آن ابعاد در گزارش قابل‌مشاهده باشند، باید در فیلد fieldNames شیء Pivot نیز فهرست شوند.
اگر از بُعدی در هیچ‌یک از محورهای پُرسمان محوری استفاده نشود، آن بُعد در گزارش قابل‌مشاهده نخواهد بود. لازم نیست همه بُعدها در
fieldNames محوری وجود داشته باشند. از ابعاد می‌توان منحصراً در فیلترها استفاده کرد و نه در
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
}
],
سنجه‌ها
سنجه‌ها اندازه‌گیری‌های کمی داده‌های رویداد برای وب‌سایت یا برنامه شما هستند. در درخواست گزارش، می‌توانید یک یا چند سنجه را مشخص کنید. برای فهرست کامل نام‌های «سنجه میانای برنامه‌سازی کاربردی» که می‌توان در درخواست‌ها مشخص کرد، سنجه‌های میانای برنامه‌سازی کاربردی را ببینید.
در درخواست‌های گزارش محوری، سنجه‌ها بااستفاده از فیلد metrics در متن درخواست تعریف می‌شوند که مشابه روش‌های گزارش‌دهی اصلی است.
مثال زیر تعداد جلسه‌ها را برای استفاده به‌عنوان مقدار سنجه در گزارش مشخص می‌کند:
"metrics": [
{
"name": "sessions"
}
],
انبوهش‌های سنجه
از فیلد metricAggregations شیء Pivot برای محاسبه مقادیر سنجه انبوهشی برای هر محور استفاده کنید.
انبوهش‌ها فقط درصورتی محاسبه می‌شوند که فیلد metricAggregations در درخواست مشخص شده باشد.
مثال زیر قطعه‌ای از پُرسمانی است که مجموع را برای بُعد محوری browser درخواست می‌کند:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
سنجه‌های محاسبه‌شده در فیلد aggregates
شیء 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"
}
]
},
....
}
شماره‌گذاری صفحات
مشابه روش‌های گزارش‌دهی اصلی، درخواست‌های محوری به شما امکان می‌دهند
فیلدهای limit
و offset را در
شیء Pivot برای پیاده‌سازی صفحه‌بندی مشخص کنید.
تنظیمات صفحه‌بندی به‌طور جداگانه برای هر محور اعمال می‌شود.
فیلد limit برای هر شیء Pivot الزامی است تا بتوان
کاردینالیتی گزارش را محدود کرد.
Data API v1 از چند محور پشتیبانی می‌کند، به‌شرطی که حاصل‌ضرب پارامتر limit
برای هر محور از ۱۰۰٬۰۰۰ بیشتر نشود.
تکه‌کد زیر نحوه استفاده از فیلدهای offset و limit را برای بازیابی پنج بُعد language بعدی با انحراف ۱۰ نشان می‌دهد:
{
"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
}
]
}
گزارش کردن پاسخ
Pivot Report Response از درخواست 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"
}
],
...
}
نمودار زیر نقش هر مؤلفه از Pivot Report Response را در ارائه گزارش محوری نشان می‌دهد:
ردیف‌های پاسخ
پاسخ گزارش محوری روش‌های 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() ); } }
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); }); }); }
برنامه نمایشی
برای دیدن نمونه‌ای از نحوه ساخت و نمایش گزارش محوری بااستفاده از JavaScript، به برنامه نمایشی گزارش محوری Google Analytics API v1 مراجعه کنید.