این یک راهنمای توسعه دهنده برای Analytics Reporting API v4 است. برای مرجع دقیق API، به مرجع API مراجعه کنید.
گزارش ها
Analytics Reporting API v4 متد batchGet را برای دسترسی به منبع Reports فراهم می کند. بخشهای زیر ساختار بدنه درخواست برای batchGet
و ساختار بدنه پاسخ از batchGet
را توضیح میدهند.
درخواست بدن
برای استفاده از Analytics Reporting API v4 برای درخواست داده، باید یک شی ReportRequest بسازید که حداقل شرایط زیر را دارد:
- شناسه نمای معتبر برای قسمت viewId .
- حداقل یک ورودی معتبر در قسمت dateRanges .
- حداقل یک ورودی معتبر در قسمت معیارها .
برای یافتن شناسه نمایش ، روش خلاصه حساب را جستجو کنید یا از Account Explorer استفاده کنید. اگر محدوده تاریخ ارائه نشده باشد، محدوده تاریخ پیشفرض این است: {"startDate": "7daysAgo", "endDate": "yesterday"}
.
در اینجا یک نمونه درخواست با حداقل فیلدهای مورد نیاز آمده است:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
متد batchGet
حداکثر پنج شی ReportRequest را می پذیرد. همه درخواست ها باید dateRange
, viewId
, segments
, samplingLevel
و cohortGroup
یکسان داشته باشند .
بدنه پاسخگویی
بدنه پاسخ درخواست API آرایه ای از اشیاء گزارش است. ساختار گزارش در شی ColumnHeader تعریف شده است که ابعاد و معیارها و انواع داده های آنها را در گزارش توصیف می کند. مقادیر ابعاد و معیارها در قسمت داده مشخص می شود.
در اینجا یک نمونه پاسخ برای درخواست نمونه بالا آمده است:
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
معیارهای
متریک ها اندازه گیری های کمی هستند. هر درخواست حداقل به یک شی متریک نیاز دارد.
در مثال زیر، متریک Sessions
به متد batchGet
ارائه میشود تا تعداد کل جلسات را در محدوده تاریخ مشخص شده به دست آورد:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
میتوانید از کاوشگر ابعاد و معیارها یا API فراداده برای دریافت فهرست ابعاد و معیارهای موجود استفاده کنید.
فیلتر کردن
هنگام ارسال درخواست batchGet
، میتوانید از آن بخواهید که تنها معیارهایی را که دارای معیارهای خاص هستند، برگرداند. برای فیلتر کردن معیارها، در متن درخواست، یک یا چند MetricFilterClause و در هر MetricFilterClause
، یک یا چند MetricFilter را مشخص کنید. در هر MetricFilter
، مقادیر زیر را مشخص کنید:
-
metricName
-
not
-
operator
-
comparisonValue
اجازه دهید {metricName}
معیار، {operator}
operator
، و {comparisonValue}
comparisonValue
نشان دهد. سپس فیلتر به صورت زیر عمل می کند:
if {metricName} {operator} {comparisonValue}
return the metric
اگر true
برای not
مشخص کنید، فیلتر به صورت زیر عمل می کند:
if {metricName} {operator} {comparisonValue}
do not return the metric
در مثال زیر، batchGet
فقط بازدیدهایی از صفحه را برمیگرداند که مقدار آنها بیشتر از 2 باشد:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
اصطلاحات
یک عبارت متریک یک عبارت ریاضی است که شما بر روی معیارهای موجود تعریف می کنید. مانند معیارهای محاسبه شده پویا عمل می کند. شما می توانید یک نام مستعار برای نمایش عبارت متریک تعریف کنید، به عنوان مثال:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
مرتب سازی
برای مرتب کردن نتایج بر اساس یک مقدار متریک:
- نام یا نام مستعار آن را از طریق قسمت
fieldName
وارد کنید. - ترتیب مرتب سازی (
ASCENDING
یاDESCENDING
) را از طریق قسمتsortOrder
مشخص کنید.
در مثال زیر، batchGet
معیارهایی را که ابتدا بر اساس جلسات و سپس بر اساس بازدید از صفحه به ترتیب نزولی مرتب شده اند، برمی گرداند:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
ابعاد
ابعاد ویژگی های کاربران شما، جلسات و اقدامات آنها را توصیف می کند. برای مثال، بعد شهر، ویژگی جلسات را توصیف می کند و شهری ("پاریس" یا "نیویورک") را که هر جلسه از آن سرچشمه می گیرد، نشان می دهد. در یک درخواست batchGet
، می توانید اشیاء با ابعاد صفر یا بیشتر را مشخص کنید، به عنوان مثال:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
فیلتر کردن
هنگام ارسال درخواست batchGet
، میتوانید از آن بخواهید که فقط ابعادی را که دارای معیارهای خاص هستند، بازگرداند. برای فیلتر کردن ابعاد، در بدنه درخواست، یک یا چند DimensionsFilterClause و در هر DimensionsFilterClause
، یک یا چند DimensionsFilter را مشخص کنید. در هر DimensionsFilters
، مقادیر زیر را مشخص کنید:
-
dimensionName
-
not
-
operator
-
expressions
-
caseSensitive
اجازه دهید {dimensionName}
بعد، {operator}
operator
و {expressions}
expressions
نشان دهد. سپس فیلتر به صورت زیر عمل می کند:
if {dimensionName} {operator} {expressions}
return the dimension
اگر true
برای not
مشخص کنید، فیلتر به صورت زیر عمل می کند:
if {dimensionName} {operator} {expressions}
do not return the dimension
در مثال زیر، batchGet
بازدید از صفحات و جلسات را در مرورگر کروم برمیگرداند:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
مرتب سازی
برای مرتب کردن نتایج بر اساس مقدار ابعاد:
- نام آن را از طریق قسمت
fieldName
وارد کنید. - ترتیب مرتب سازی (
ASCENDING
یاDESCENDING
) را از طریق قسمتsortOrder
مشخص کنید.
به عنوان مثال، batchGet
زیر ابعاد مرتب شده بر اساس کشور و سپس بر اساس مرورگر را برمی گرداند:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
سطل های هیستوگرام
برای ابعاد با مقادیر صحیح، درک ویژگی های آنها با سطل کردن مقادیر آنها در محدوده آسان تر است. از فیلد histogramBuckets
برای تعریف محدوده برای سطل های حاصل استفاده کنید و HISTOGRAM_BUCKET
به عنوان نوع سفارش مشخص کنید، به عنوان مثال:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
محدوده تاریخ چندگانه
Google Analytics Reporting API v4 به شما این امکان را میدهد که دادهها را در بازههای تاریخ متعدد در یک درخواست دریافت کنید. چه درخواست شما یک یا دو محدوده تاریخ را مشخص کند، داده ها در شی dateRangeValue برگردانده می شوند، به عنوان مثال:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
سفارش دلتا
هنگام درخواست مقادیر متریک در دو محدوده تاریخ، می توانید نتایج را بر اساس تفاوت بین مقادیر متریک در محدوده تاریخ ترتیب دهید، به عنوان مثال:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
رفتار بعد تاریخ
اگر یک بعد مربوط به تاریخ یا زمان را درخواست کنید، شیء DateRangeValue فقط مقادیری را برای تاریخ هایی که در محدوده های مربوطه قرار می گیرند نگه می دارد. تمام مقادیر دیگر که در محدوده تاریخ مشخص شده نیستند 0
خواهند بود.
برای مثال، درخواستی برای بعد ga:date
و متریک ga:sessions
در دو محدوده تاریخ در نظر بگیرید: ژانویه و فوریه. در پاسخ برای داده های درخواستی در ژانویه، مقادیر در فوریه 0
خواهد بود. و در پاسخ برای داده های درخواستی در ماه فوریه، مقادیر در ژانویه 0
خواهد بود.
گزارش ژانویه
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
گزارش فوریه
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
بخش ها
برای درخواست زیرمجموعه ای از داده های Analytics خود، از بخش ها استفاده کنید. به عنوان مثال، میتوانید کاربرانی را از یک کشور یا شهر خاص در یک بخش و کاربرانی که از بخش خاصی از سایت شما بازدید میکنند، در بخش دیگر تعریف کنید. فیلترها فقط ردیفهایی را برمیگردانند که یک شرط را برآورده میکنند، در حالی که بخشها زیرمجموعهای از کاربران، جلسات یا رویدادهایی را برمیگردانند که شرایط حاوی بخشها را برآورده میکنند.
هنگام درخواست با بخش ها، اطمینان حاصل کنید که:
- هر ReportRequest در متد
batchGet
باید شامل تعاریف بخش یکسان باشد. - شما
ga:segment
را به لیست ابعاد اضافه می کنید.
مثلا:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
برای نمونه درخواست های بیشتر با بخش ها به نمونه ها مراجعه کنید.
شناسه بخش
از قسمت segmentId
برای درخواست بخش ها استفاده کنید. برای درخواست بخش ها نمی توانید از هر دو segmentId
و dynamicSegment
استفاده کنید.
مثلا:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
نمونه برداری
نمونهگیری میتواند بر نتایج دادههای شما تأثیر بگذارد و دلیل رایجی است که چرا مقادیر بازگشتی از API با رابط وب مطابقت ندارند. از فیلد samplingLevel
برای تنظیم اندازه نمونه مورد نظر استفاده کنید.
- برای پاسخ سریع با اندازه نمونه کوچکتر، مقدار را روی
SMALL
تنظیم کنید. - مقدار را برای پاسخ دقیق تر اما کندتر روی
LARGE
تنظیم کنید. - برای پاسخی که سرعت و دقت را متعادل می کند، مقدار را روی
DEFAULT
قرار دهید.
مثلا:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
اگر گزارشی حاوی داده های نمونه برداری شده باشد، Analytics Reporting API v4 فیلدهای samplesReadCounts
و samplingSpaceSizes
را برمی گرداند. اگر از نتایج نمونه برداری نشود، این فیلدها تعریف نمی شوند.
در زیر یک نمونه پاسخ است که حاوی داده های نمونه برداری شده از یک درخواست با دو محدوده تاریخ است. نتایج از تقریباً 500 هزار نمونه از فضای نمونه برداری تقریباً 15 میلیون جلسه محاسبه شد:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
صفحه بندی
Analytics Reporting API v4 از فیلدهای pageToken
و pageSize
برای صفحه بندی از طریق نتایج پاسخ که چندین صفحه را در بر می گیرد، استفاده می کند. شما pageToken
از پارامتر nextPageToken
در پاسخ به درخواست reports.batchGet
دریافت می کنید:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
گام بعدی
اکنون که اصول ایجاد گزارش را پوشش داده اید، به ویژگی های پیشرفته API v4 نگاهی بیندازید.