این راهنما دستورالعمل هایی برای انتقال Core Reporting API v3 به Analytics Reporting API v4 ارائه می دهد.
معرفی
برای استفاده از ویژگی های جدید معرفی شده در Analytics Reporting API v4، کد خود را برای استفاده از API انتقال دهید. این راهنما درخواستها را در Core Reporting API v3 و درخواستهای معادل آن در Analytics Reporting API v4 نشان میدهد تا مهاجرت شما را آسانتر کند.
مهاجرت پایتون
اگر توسعهدهنده پایتون هستید، از کتابخانه کمکی GAV4 در GitHub برای تبدیل درخواستهای Google Analytics Core Reporting API v3 به درخواستهای Analytics Reporting API v4 استفاده کنید.
نقاط پایانی
Core Reporting API v3 و Analytics Reporting API v4 نقاط پایانی و روشهای HTTP متفاوتی دارند:
v3 نقطه پایانی
GET https://www.googleapis.com/analytics/v3/data/ga
v4 نقطه پایانی
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
مثالهای زیر یک درخواست در v3 و درخواست معادل آن در v4 را مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
کتابخانه های مشتری و خدمات کشف
اگر از پایتون، جاوا اسکریپت یا کتابخانه سرویس گیرنده دیگری استفاده میکنید که به Google Discovery Service متکی است، باید مکان سند کشف را برای Reporting API v4 ارائه کنید.
پایتون
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
جاوا اسکریپت
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
کتابخانههای کلاینت جاوا و PHP از پیش ساخته شدهاند، اما میتوانید از سرویس کشف و تولیدکننده APIهای Google برای تولید آنها استفاده کنید.
درخواست ها
مرجع API v4 با جزئیات ساختار بدنه درخواست را توضیح می دهد. بخشهای زیر انتقال پارامترهای درخواست v3 به پارامترهای درخواست v4 را شرح میدهند.
مشاهده شناسه ها
در نسخه 3، یک پارامتر ids
، که یک "ID جدول" را می پذیرد، در قالب ga:XXXX
است، که در آن XXXX
شناسه نمایش (نمایه) است. در نسخه 4، شناسه view (پروفایل) در قسمت viewId
در بدنه درخواست مشخص شده است.
مثالهای زیر پارامتر ids
در درخواست v3 و فیلد viewId
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
محدوده تاریخ
Analytics Reporting API v4 به شما امکان می دهد چندین محدوده تاریخ را در یک درخواست مشخص کنید. فیلد dateRanges
لیستی از اشیاء DateRange را می گیرد. در نسخه 3، شما از پارامترهای start-date
و end-date
برای تعیین محدوده تاریخ در یک درخواست استفاده می کنید.
مثالهای زیر پارامترهای start-date
و end-date
در یک درخواست v3 و قسمت dateRanges
در یک درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
معیارهای
پارامتر v3 metrics
مربوط به قسمت v4 metrics
است که لیستی از اشیاء متریک را می گیرد.
مثالهای زیر پارامترهای metrics
را در درخواست v3 و فیلد metrics
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
ابعاد
پارامتر v3 dimensions
مربوط به قسمت v4 dimensions
است که لیستی از اشیاء Dimension را می گیرد.
مثالهای زیر پارامترهای dimensions
در درخواست v3 و فیلد dimensions
در درخواست v4 را مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
مرتب سازی
پارامتر sort
v3 معادل فیلد v4 orderBys
است که لیستی از اشیاء OrderBy را می گیرد.
در v4، برای مرتب کردن نتایج بر اساس یک بعد یا مقدار متریک:
- نام یا نام مستعار آن را از طریق قسمت
fieldName
وارد کنید. - ترتیب مرتب سازی (
ASCENDING
یاDESCENDING
) را از طریق قسمتsortOrder
مشخص کنید.
مثالهای زیر پارامتر sort
را در درخواست v3 و فیلد orderBy
در درخواست v4 مقایسه میکنند. آنها هر دو کاربران را به ترتیب نزولی و منابع را بر اساس حروف الفبا مرتب می کنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
سطح نمونه برداری
پارامتر v3 samplingLevel
با فیلد v4 samplingLevel
مطابقت دارد. در نسخه 3، مقادیر samplingLevel
پذیرفته شده FASTER
، HIGHER_PRECISION
، و DEFAULT
هستند. و در v4، مقادیر samplingLevel
پذیرفته شده SMALL
، LARGE
و DEFAULT
هستند. توجه داشته باشید که FASTER
در نسخه 3 به SMALL
در نسخه 4، HIGHER_PRECISION
به LARGE
تغییر کرده است.
مثالهای زیر پارامتر samplingLevel
در یک درخواست v3 و فیلد samplingLevel
در یک درخواست v4 مقایسه میکنند:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
بخش ها
پارامتر segment
v3 مربوط به قسمت v4 segments
است که لیستی از اشیاء Segment را می گیرد.
شناسه های بخش
در نسخه 4، برای درخواست بخش به بخش شناسه، یک شی Segment بسازید و شناسه آن را از طریق قسمت segmentId عرضه کنید.
مثالهای زیر پارامتر segment
را در درخواست v3 و فیلد segments
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
بخش های دینامیک
در نسخه 4، برای بیان تعاریف بخش پیچیده تر، از فیلد segments
استفاده کنید که شامل یک شی DynamicSegment است.
مثالهای زیر پارامتر segment
را در درخواست v3 و فیلد segments
حاوی یک شی DynamicSegment
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
می توانید شرایط و دنباله ها را در یک بخش ترکیب کنید:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
v3 Segments Syntax در نسخه 4
فیلد segmentId در v4 API از نحو قطعه در v3 API پشتیبانی می کند.
مثالهای زیر نشان میدهند که چگونه پارامتر segment
در یک درخواست v3 توسط فیلد segmentId
در درخواست معادل در v4 پشتیبانی میشود:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
فیلترها
v4 از dimensionFilterClauses
برای فیلتر کردن ابعاد و metricFilterClauses
برای فیلتر کردن معیارها استفاده میکند. یک dimensionFilterClauses
حاوی لیستی از اشیاء DimensionFilter است. و یک metricFilterClauses
حاوی لیستی از اشیاء MetricFilter است.
مثالهای زیر پارامتر filters
در درخواست v3 و فیلد dimensionFilterClauses
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
v3 نحو را در نسخه 4 فیلتر می کند
اگرچه فیلد filtersExpression در v4 از نحو filters
در v3 پشتیبانی می کند، از dimensionFilterClauses
و metricFilterClauses
برای فیلتر کردن ابعاد و معیارها استفاده کنید.
مثالهای زیر نشان میدهند که چگونه پارامتر filters
در یک درخواست v3 توسط فیلد filtersExpression
در درخواست معادل در v4 پشتیبانی میشود:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
ردیف های خالی
پارامتر v3 include-empty-rows
با فیلد includeEmptyRows
در v4 مطابقت دارد. پارامتر v3 به طور پیش فرض درست است، در حالی که در v4 فیلد پیش فرض نادرست است. اگر مقدار تنظیم شده در v3 را ندارید، باید مقدار را در v4 روی true تنظیم کنید.
مثالهای زیر پارامتر include-empty-rows
در یک درخواست v3 با فیلد includeEmptyRows
در یک درخواست v4 مقایسه میکنند:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
صفحه بندی
v4 از فیلدهای pageToken
و pageSize
برای صفحه بندی در تعداد زیادی از نتایج استفاده می کند. pageToken
از ویژگی nextPageToken
یک شی پاسخ به دست می آید.
مثالهای زیر پارامترهای start-index
و max-results
را در یک درخواست v3 با فیلدهای pageToken
و pageSize
در یک درخواست v4 مقایسه میکنند:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
پارامترهای استاندارد
Analytics Reporting API v4 از اکثر پارامترهای پرس و جوی استاندارد در API v3 پشتیبانی می کند، به جز پارامترهای userIp
و callback
.
مثالهای زیر پارامتر quotaUser
را در درخواست v3 با درخواست v4 مقایسه میکنند:
v3 نقطه پایانی
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
v4 نقطه پایانی
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
پاسخ
از آنجایی که v4 به شما امکان میدهد چندین شی ReportRequest را در یک درخواست HTTP ارسال کنید، آرایهای از اشیاء گزارش را در پاسخ دریافت میکنید. برای هر ReportRequest ارسال شده، یک گزارش مربوطه را در پاسخ دریافت می کنید.
گزارش ها
گزارش v4 دارای سه فیلد سطح بالا است: columnHeader
، data
و nextPageToken
.
از آنجایی که بدنه پاسخ v4 مانند پاسخ v3 شامل پاسخ به تمام پارامترهای پرس و جو نمی شود، برای دریافت پاسخ به یک پارامتر کوئری خاص، برنامه مشتری باید آن پارامتر را به ReportRequest اضافه کند.
ما قبلاً به nextPageToken
در بخش Pagination پرداختهایم، بنابراین اجازه دهید ابتدا به شی ستون Header نگاه کنیم.
سربرگ ستون
سربرگ ستون حاوی لیستی از ابعاد نامگذاری شده و یک شی MetricHeader است که حاوی لیستی از اشیاء MetricHeaderEntry است. هر شی MetricHeaderEntry name
متریک و type
آن (ارز، درصد و غیره) را مشخص می کند، که به شما کمک می کند خروجی را فرمت کنید.
مثالهای زیر فیلد columnHeaders
در پاسخ v3 را با فیلد columnHeader
در پاسخ v4 مقایسه میکند:
v3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
گزارش ردیف ها
Core Reporting API v3 دادههای گزارش را در آرایه ردیفها برمیگرداند که حاوی ابعاد و معیارهای درخواستی است.
Analytics Reporting API v4 دادههای گزارش را در یک شی ReportRow برمیگرداند که شامل آرایهای از ابعاد و آرایهای از اشیاء DateRangeValues است که هر کدام شامل یک یا دو محدوده تاریخ است، همانطور که نمودار زیر نشان میدهد:
ردیف ها
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
داده های نمونه برداری شده
اگر از نتایج نمونه برداری شود Core Reporting API v3 فیلد بولی containsSampledData
برمی گرداند که روی true
تنظیم شده است.
اگر داده ها نمونه برداری شوند، Analytics Reporting API v4 یک Boolean بر نمی گرداند. بلکه API فیلدهای samplesReadCounts
و samplingSpaceSizes
را برمی گرداند. اگر از نتایج نمونه برداری نشود، این فیلدها تعریف نمی شوند. مثال پایتون زیر نحوه محاسبه اگر یک گزارش حاوی داده های نمونه برداری شده است را نشان می دهد:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
در زیر یک نمونه پاسخ است که حاوی داده های نمونه برداری شده از یک درخواست با دو محدوده تاریخ است. نتایج از تقریباً 500 هزار نمونه از فضای نمونه برداری تقریباً 15 میلیون جلسه محاسبه شد:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
تجزیه پاسخ v4
کد نمونه زیر پاسخ Analytics Reporting API v4 را تجزیه و چاپ می کند:
پایتون
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
جاوا
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
رسیدگی به خطا
از آنجایی که فرمت پاسخ خطا در v4 با فرمت v3 متفاوت است، کد خود را برای رسیدگی به پاسخ های خطای v4 به روز کنید.
مثالهای زیر یک پاسخ خطا را در v3 و پاسخ خطای معادل آن را در v4 مقایسه میکنند:
v3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
v4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}
این راهنما دستورالعمل هایی برای انتقال Core Reporting API v3 به Analytics Reporting API v4 ارائه می دهد.
معرفی
برای استفاده از ویژگی های جدید معرفی شده در Analytics Reporting API v4، کد خود را برای استفاده از API انتقال دهید. این راهنما درخواستها را در Core Reporting API v3 و درخواستهای معادل آن در Analytics Reporting API v4 نشان میدهد تا مهاجرت شما را آسانتر کند.
مهاجرت پایتون
اگر توسعهدهنده پایتون هستید، از کتابخانه کمکی GAV4 در GitHub برای تبدیل درخواستهای Google Analytics Core Reporting API v3 به درخواستهای Analytics Reporting API v4 استفاده کنید.
نقاط پایانی
Core Reporting API v3 و Analytics Reporting API v4 نقاط پایانی و روشهای HTTP متفاوتی دارند:
v3 نقطه پایانی
GET https://www.googleapis.com/analytics/v3/data/ga
v4 نقطه پایانی
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
مثالهای زیر یک درخواست در v3 و درخواست معادل آن در v4 را مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
کتابخانه های مشتری و خدمات کشف
اگر از پایتون، جاوا اسکریپت یا کتابخانه سرویس گیرنده دیگری استفاده میکنید که به Google Discovery Service متکی است، باید مکان سند کشف را برای Reporting API v4 ارائه کنید.
پایتون
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
جاوا اسکریپت
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
کتابخانههای کلاینت جاوا و PHP از پیش ساخته شدهاند، اما میتوانید از سرویس کشف و تولیدکننده APIهای Google برای تولید آنها استفاده کنید.
درخواست ها
مرجع API v4 با جزئیات ساختار بدنه درخواست را توضیح می دهد. بخشهای زیر انتقال پارامترهای درخواست v3 به پارامترهای درخواست v4 را شرح میدهند.
مشاهده شناسه ها
در نسخه 3، یک پارامتر ids
، که یک "ID جدول" را می پذیرد، در قالب ga:XXXX
است، که در آن XXXX
شناسه نمایش (نمایه) است. در نسخه 4، شناسه view (پروفایل) در قسمت viewId
در بدنه درخواست مشخص شده است.
مثالهای زیر پارامتر ids
در درخواست v3 و فیلد viewId
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
محدوده تاریخ
Analytics Reporting API v4 به شما امکان می دهد چندین محدوده تاریخ را در یک درخواست مشخص کنید. فیلد dateRanges
لیستی از اشیاء DateRange را می گیرد. در نسخه 3، شما از پارامترهای start-date
و end-date
برای تعیین محدوده تاریخ در یک درخواست استفاده می کنید.
مثالهای زیر پارامترهای start-date
و end-date
در یک درخواست v3 و قسمت dateRanges
در یک درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
معیارهای
پارامتر v3 metrics
مربوط به قسمت v4 metrics
است که لیستی از اشیاء متریک را می گیرد.
مثالهای زیر پارامترهای metrics
را در درخواست v3 و فیلد metrics
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
ابعاد
پارامتر v3 dimensions
مربوط به قسمت v4 dimensions
است که لیستی از اشیاء Dimension را می گیرد.
مثالهای زیر پارامترهای dimensions
در درخواست v3 و فیلد dimensions
در درخواست v4 را مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
مرتب سازی
پارامتر sort
v3 معادل فیلد v4 orderBys
است که لیستی از اشیاء OrderBy را می گیرد.
در v4، برای مرتب کردن نتایج بر اساس یک بعد یا مقدار متریک:
- نام یا نام مستعار آن را از طریق قسمت
fieldName
وارد کنید. - ترتیب مرتب سازی (
ASCENDING
یاDESCENDING
) را از طریق قسمتsortOrder
مشخص کنید.
مثالهای زیر پارامتر sort
را در درخواست v3 و فیلد orderBy
در درخواست v4 مقایسه میکنند. آنها هر دو کاربران را به ترتیب نزولی و منابع را بر اساس حروف الفبا مرتب می کنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
سطح نمونه برداری
پارامتر v3 samplingLevel
با فیلد v4 samplingLevel
مطابقت دارد. در نسخه 3، مقادیر samplingLevel
پذیرفته شده FASTER
، HIGHER_PRECISION
، و DEFAULT
هستند. و در v4، مقادیر samplingLevel
پذیرفته شده SMALL
، LARGE
و DEFAULT
هستند. توجه داشته باشید که FASTER
در نسخه 3 به SMALL
در نسخه 4، HIGHER_PRECISION
به LARGE
تغییر کرده است.
مثالهای زیر پارامتر samplingLevel
در یک درخواست v3 و فیلد samplingLevel
در یک درخواست v4 مقایسه میکنند:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
بخش ها
پارامتر segment
v3 مربوط به قسمت v4 segments
است که لیستی از اشیاء Segment را می گیرد.
شناسه های بخش
در نسخه 4، برای درخواست بخش به بخش شناسه، یک شی Segment بسازید و شناسه آن را از طریق قسمت segmentId عرضه کنید.
مثالهای زیر پارامتر segment
را در درخواست v3 و فیلد segments
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
بخش های دینامیک
در نسخه 4، برای بیان تعاریف بخش پیچیده تر، از فیلد segments
استفاده کنید که شامل یک شی DynamicSegment است.
مثالهای زیر پارامتر segment
را در درخواست v3 و فیلد segments
حاوی یک شی DynamicSegment
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
می توانید شرایط و دنباله ها را در یک بخش ترکیب کنید:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
v3 Segments Syntax در نسخه 4
فیلد segmentId در v4 API از نحو قطعه در v3 API پشتیبانی می کند.
مثالهای زیر نشان میدهند که چگونه پارامتر segment
در یک درخواست v3 توسط فیلد segmentId
در درخواست معادل در v4 پشتیبانی میشود:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
فیلترها
v4 از dimensionFilterClauses
برای فیلتر کردن ابعاد و metricFilterClauses
برای فیلتر کردن معیارها استفاده میکند. یک dimensionFilterClauses
حاوی لیستی از اشیاء DimensionFilter است. و یک metricFilterClauses
حاوی لیستی از اشیاء MetricFilter است.
مثالهای زیر پارامتر filters
در درخواست v3 و فیلد dimensionFilterClauses
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
v3 نحو را در نسخه 4 فیلتر می کند
اگرچه فیلد filtersExpression در v4 از نحو filters
در v3 پشتیبانی می کند، از dimensionFilterClauses
و metricFilterClauses
برای فیلتر کردن ابعاد و معیارها استفاده کنید.
مثالهای زیر نشان میدهند که چگونه پارامتر filters
در یک درخواست v3 توسط فیلد filtersExpression
در درخواست معادل در v4 پشتیبانی میشود:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
ردیف های خالی
پارامتر v3 include-empty-rows
با فیلد includeEmptyRows
در v4 مطابقت دارد. پارامتر v3 به طور پیش فرض درست است، در حالی که در v4 فیلد پیش فرض نادرست است. اگر مقدار تنظیم شده در v3 را ندارید، باید مقدار را در v4 روی true تنظیم کنید.
مثالهای زیر پارامتر include-empty-rows
در یک درخواست v3 با فیلد includeEmptyRows
در یک درخواست v4 مقایسه میکنند:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
صفحه بندی
v4 از فیلدهای pageToken
و pageSize
برای صفحه بندی در تعداد زیادی از نتایج استفاده می کند. pageToken
از ویژگی nextPageToken
یک شی پاسخ به دست می آید.
مثالهای زیر پارامترهای start-index
و max-results
را در یک درخواست v3 با فیلدهای pageToken
و pageSize
در یک درخواست v4 مقایسه میکنند:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
پارامترهای استاندارد
Analytics Reporting API v4 از اکثر پارامترهای پرس و جوی استاندارد در API v3 پشتیبانی می کند، به جز پارامترهای userIp
و callback
.
مثالهای زیر پارامتر quotaUser
را در درخواست v3 با درخواست v4 مقایسه میکنند:
v3 نقطه پایانی
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
v4 نقطه پایانی
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
پاسخ
از آنجایی که v4 به شما امکان میدهد چندین شی ReportRequest را در یک درخواست HTTP ارسال کنید، آرایهای از اشیاء گزارش را در پاسخ دریافت میکنید. برای هر ReportRequest ارسال شده، یک گزارش مربوطه را در پاسخ دریافت می کنید.
گزارش ها
گزارش v4 دارای سه فیلد سطح بالا است: columnHeader
، data
و nextPageToken
.
از آنجایی که بدنه پاسخ v4 مانند پاسخ v3 شامل پاسخ به تمام پارامترهای پرس و جو نمی شود، برای دریافت پاسخ به یک پارامتر کوئری خاص، برنامه مشتری باید آن پارامتر را به ReportRequest اضافه کند.
ما قبلاً به nextPageToken
در بخش Pagination پرداختهایم، بنابراین اجازه دهید ابتدا به شی ستون Header نگاه کنیم.
سربرگ ستون
سربرگ ستون حاوی لیستی از ابعاد نامگذاری شده و یک شی MetricHeader است که حاوی لیستی از اشیاء MetricHeaderEntry است. هر شی MetricHeaderEntry name
متریک و type
آن (ارز، درصد و غیره) را مشخص می کند، که به شما کمک می کند خروجی را فرمت کنید.
مثالهای زیر فیلد columnHeaders
در پاسخ v3 را با فیلد columnHeader
در پاسخ v4 مقایسه میکند:
v3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
گزارش ردیف ها
Core Reporting API v3 دادههای گزارش را در آرایه ردیفها برمیگرداند که حاوی ابعاد و معیارهای درخواستی است.
Analytics Reporting API v4 دادههای گزارش را در یک شی ReportRow برمیگرداند که شامل آرایهای از ابعاد و آرایهای از اشیاء DateRangeValues است که هر کدام شامل یک یا دو محدوده تاریخ است، همانطور که نمودار زیر نشان میدهد:
ردیف ها
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
داده های نمونه برداری شده
اگر از نتایج نمونه برداری شود Core Reporting API v3 فیلد بولی containsSampledData
برمی گرداند که روی true
تنظیم شده است.
اگر داده ها نمونه برداری شوند، Analytics Reporting API v4 یک Boolean بر نمی گرداند. بلکه API فیلدهای samplesReadCounts
و samplingSpaceSizes
را برمی گرداند. اگر از نتایج نمونه برداری نشود، این فیلدها تعریف نمی شوند. مثال پایتون زیر نحوه محاسبه اگر یک گزارش حاوی داده های نمونه برداری شده است را نشان می دهد:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
در زیر یک نمونه پاسخ است که حاوی داده های نمونه برداری شده از یک درخواست با دو محدوده تاریخ است. نتایج از تقریباً 500 هزار نمونه از فضای نمونه برداری تقریباً 15 میلیون جلسه محاسبه شد:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
تجزیه پاسخ v4
کد نمونه زیر پاسخ Analytics Reporting API v4 را تجزیه و چاپ می کند:
پایتون
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
جاوا
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
رسیدگی به خطا
از آنجایی که فرمت پاسخ خطا در v4 با فرمت v3 متفاوت است، کد خود را برای رسیدگی به پاسخ های خطای v4 به روز کنید.
مثالهای زیر یک پاسخ خطا را در v3 و پاسخ خطای معادل آن را در v4 مقایسه میکنند:
v3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
v4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}
این راهنما دستورالعمل هایی برای انتقال Core Reporting API v3 به Analytics Reporting API v4 ارائه می دهد.
معرفی
برای استفاده از ویژگی های جدید معرفی شده در Analytics Reporting API v4، کد خود را برای استفاده از API انتقال دهید. این راهنما درخواستها را در Core Reporting API v3 و درخواستهای معادل آن در Analytics Reporting API v4 نشان میدهد تا مهاجرت شما را آسانتر کند.
مهاجرت پایتون
اگر توسعهدهنده پایتون هستید، از کتابخانه کمکی GAV4 در GitHub برای تبدیل درخواستهای Google Analytics Core Reporting API v3 به درخواستهای Analytics Reporting API v4 استفاده کنید.
نقاط پایانی
Core Reporting API v3 و Analytics Reporting API v4 نقاط پایانی و روشهای HTTP متفاوتی دارند:
v3 نقطه پایانی
GET https://www.googleapis.com/analytics/v3/data/ga
v4 نقطه پایانی
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
مثالهای زیر یک درخواست در v3 و درخواست معادل آن در v4 را مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
کتابخانه های مشتری و خدمات کشف
اگر از پایتون، جاوا اسکریپت یا کتابخانه سرویس گیرنده دیگری استفاده میکنید که به Google Discovery Service متکی است، باید مکان سند کشف را برای Reporting API v4 ارائه کنید.
پایتون
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
جاوا اسکریپت
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
کتابخانههای کلاینت جاوا و PHP از پیش ساخته شدهاند، اما میتوانید از سرویس کشف و تولیدکننده APIهای Google برای تولید آنها استفاده کنید.
درخواست ها
مرجع API v4 با جزئیات ساختار بدنه درخواست را توضیح می دهد. بخشهای زیر انتقال پارامترهای درخواست v3 به پارامترهای درخواست v4 را شرح میدهند.
مشاهده شناسه ها
در نسخه 3، یک پارامتر ids
، که یک "ID جدول" را می پذیرد، در قالب ga:XXXX
است، که در آن XXXX
شناسه نمایش (نمایه) است. در نسخه 4، شناسه view (پروفایل) در قسمت viewId
در بدنه درخواست مشخص شده است.
مثالهای زیر پارامتر ids
در درخواست v3 و فیلد viewId
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
محدوده تاریخ
Analytics Reporting API v4 به شما امکان می دهد چندین محدوده تاریخ را در یک درخواست مشخص کنید. فیلد dateRanges
لیستی از اشیاء DateRange را می گیرد. در نسخه 3، شما از پارامترهای start-date
و end-date
برای تعیین محدوده تاریخ در یک درخواست استفاده می کنید.
مثالهای زیر پارامترهای start-date
و end-date
در یک درخواست v3 و قسمت dateRanges
در یک درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
معیارهای
پارامتر v3 metrics
مربوط به قسمت v4 metrics
است که لیستی از اشیاء متریک را می گیرد.
مثالهای زیر پارامترهای metrics
را در درخواست v3 و فیلد metrics
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
ابعاد
پارامتر v3 dimensions
مربوط به قسمت v4 dimensions
است که لیستی از اشیاء Dimension را می گیرد.
مثالهای زیر پارامترهای dimensions
در درخواست v3 و فیلد dimensions
در درخواست v4 را مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
مرتب سازی
پارامتر sort
v3 معادل فیلد v4 orderBys
است که لیستی از اشیاء OrderBy را می گیرد.
در v4، برای مرتب کردن نتایج بر اساس یک بعد یا مقدار متریک:
- نام یا نام مستعار آن را از طریق قسمت
fieldName
وارد کنید. - ترتیب مرتب سازی (
ASCENDING
یاDESCENDING
) را از طریق قسمتsortOrder
مشخص کنید.
مثالهای زیر پارامتر sort
را در درخواست v3 و فیلد orderBy
در درخواست v4 مقایسه میکنند. آنها هر دو کاربران را به ترتیب نزولی و منابع را بر اساس حروف الفبا مرتب می کنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
سطح نمونه برداری
پارامتر v3 samplingLevel
با فیلد v4 samplingLevel
مطابقت دارد. در نسخه 3، مقادیر samplingLevel
پذیرفته شده FASTER
، HIGHER_PRECISION
، و DEFAULT
هستند. و در v4، مقادیر samplingLevel
پذیرفته شده SMALL
، LARGE
و DEFAULT
هستند. توجه داشته باشید که FASTER
در نسخه 3 به SMALL
در نسخه 4، HIGHER_PRECISION
به LARGE
تغییر کرده است.
مثالهای زیر پارامتر samplingLevel
در یک درخواست v3 و فیلد samplingLevel
در یک درخواست v4 مقایسه میکنند:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
بخش ها
پارامتر segment
v3 مربوط به قسمت v4 segments
است که لیستی از اشیاء Segment را می گیرد.
شناسه های بخش
در نسخه 4، برای درخواست بخش به بخش شناسه، یک شی Segment بسازید و شناسه آن را از طریق قسمت segmentId عرضه کنید.
مثالهای زیر پارامتر segment
را در درخواست v3 و فیلد segments
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
بخش های دینامیک
در نسخه 4، برای بیان تعاریف بخش پیچیده تر، از فیلد segments
استفاده کنید که شامل یک شی DynamicSegment است.
مثالهای زیر پارامتر segment
را در درخواست v3 و فیلد segments
حاوی یک شی DynamicSegment
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
می توانید شرایط و دنباله ها را در یک بخش ترکیب کنید:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
v3 Segments Syntax در نسخه 4
فیلد segmentId در v4 API از نحو قطعه در v3 API پشتیبانی می کند.
مثالهای زیر نشان میدهند که چگونه پارامتر segment
در یک درخواست v3 توسط فیلد segmentId
در درخواست معادل در v4 پشتیبانی میشود:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
فیلترها
v4 از dimensionFilterClauses
برای فیلتر کردن ابعاد و metricFilterClauses
برای فیلتر کردن معیارها استفاده میکند. یک dimensionFilterClauses
حاوی لیستی از اشیاء DimensionFilter است. و یک metricFilterClauses
حاوی لیستی از اشیاء MetricFilter است.
مثالهای زیر پارامتر filters
در درخواست v3 و فیلد dimensionFilterClauses
در درخواست v4 مقایسه میکنند:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
v3 نحو را در نسخه 4 فیلتر می کند
اگرچه فیلد filtersExpression در v4 از نحو filters
در v3 پشتیبانی می کند، از dimensionFilterClauses
و metricFilterClauses
برای فیلتر کردن ابعاد و معیارها استفاده کنید.
مثالهای زیر نشان میدهند که چگونه پارامتر filters
در یک درخواست v3 توسط فیلد filtersExpression
در درخواست معادل در v4 پشتیبانی میشود:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
ردیف های خالی
پارامتر v3 include-empty-rows
با فیلد includeEmptyRows
در v4 مطابقت دارد. پارامتر v3 به طور پیش فرض درست است، در حالی که در v4 فیلد پیش فرض نادرست است. اگر مقدار تنظیم شده در v3 را ندارید، باید مقدار را در v4 روی true تنظیم کنید.
مثالهای زیر پارامتر include-empty-rows
در یک درخواست v3 با فیلد includeEmptyRows
در یک درخواست v4 مقایسه میکنند:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
صفحه بندی
v4 از فیلدهای pageToken
و pageSize
برای صفحه بندی در تعداد زیادی از نتایج استفاده می کند. pageToken
از ویژگی nextPageToken
یک شی پاسخ به دست می آید.
مثالهای زیر پارامترهای start-index
و max-results
را در یک درخواست v3 با فیلدهای pageToken
و pageSize
در یک درخواست v4 مقایسه میکنند:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
پارامترهای استاندارد
Analytics Reporting API v4 از اکثر پارامترهای پرس و جوی استاندارد در API v3 پشتیبانی می کند، به جز پارامترهای userIp
و callback
.
مثالهای زیر پارامتر quotaUser
را در درخواست v3 با درخواست v4 مقایسه میکنند:
v3 نقطه پایانی
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
v4 نقطه پایانی
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
پاسخ
از آنجایی که v4 به شما امکان میدهد چندین شی ReportRequest را در یک درخواست HTTP ارسال کنید، آرایهای از اشیاء گزارش را در پاسخ دریافت میکنید. برای هر ReportRequest ارسال شده، یک گزارش مربوطه را در پاسخ دریافت می کنید.
گزارش ها
گزارش v4 دارای سه فیلد سطح بالا است: columnHeader
، data
و nextPageToken
.
از آنجایی که بدنه پاسخ v4 مانند پاسخ v3 شامل پاسخ به تمام پارامترهای پرس و جو نمی شود، برای دریافت پاسخ به یک پارامتر کوئری خاص، برنامه مشتری باید آن پارامتر را به ReportRequest اضافه کند.
ما قبلاً به nextPageToken
در بخش Pagination پرداختهایم، بنابراین اجازه دهید ابتدا به شی ستون Header نگاه کنیم.
سربرگ ستون
سربرگ ستون حاوی لیستی از ابعاد نامگذاری شده و یک شی MetricHeader است که حاوی لیستی از اشیاء MetricHeaderEntry است. هر شی MetricHeaderEntry name
متریک و type
آن (ارز، درصد و غیره) را مشخص می کند، که به شما کمک می کند خروجی را فرمت کنید.
مثالهای زیر فیلد columnHeaders
در پاسخ v3 را با فیلد columnHeader
در پاسخ v4 مقایسه میکند:
v3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
گزارش ردیف ها
Core Reporting API v3 دادههای گزارش را در آرایه ردیفها برمیگرداند که حاوی ابعاد و معیارهای درخواستی است.
Analytics Reporting API v4 دادههای گزارش را در یک شی ReportRow برمیگرداند که شامل آرایهای از ابعاد و آرایهای از اشیاء DateRangeValues است که هر کدام شامل یک یا دو محدوده تاریخ است، همانطور که نمودار زیر نشان میدهد:
ردیف ها
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
داده های نمونه برداری شده
اگر از نتایج نمونه برداری شود Core Reporting API v3 فیلد بولی containsSampledData
برمی گرداند که روی true
تنظیم شده است.
اگر داده ها نمونه برداری شوند، Analytics Reporting API v4 یک Boolean بر نمی گرداند. بلکه API فیلدهای samplesReadCounts
و samplingSpaceSizes
را برمی گرداند. اگر از نتایج نمونه برداری نشود، این فیلدها تعریف نمی شوند. مثال پایتون زیر نحوه محاسبه اگر یک گزارش حاوی داده های نمونه برداری شده است را نشان می دهد:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
در زیر یک نمونه پاسخ است که حاوی داده های نمونه برداری شده از یک درخواست با دو محدوده تاریخ است. نتایج از تقریباً 500 هزار نمونه از فضای نمونه برداری تقریباً 15 میلیون جلسه محاسبه شد:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
تجزیه پاسخ v4
کد نمونه زیر پاسخ Analytics Reporting API v4 را تجزیه و چاپ می کند:
پایتون
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
جاوا
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
رسیدگی به خطا
از آنجایی که فرمت پاسخ خطا در v4 با فرمت v3 متفاوت است، کد خود را برای رسیدگی به پاسخ های خطای v4 به روز کنید.
مثالهای زیر یک پاسخ خطا را در v3 و پاسخ خطای معادل آن را در v4 مقایسه میکنند:
v3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
v4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}