راهنمای مهاجرت، راهنمای مهاجرت، راهنمای مهاجرت

این راهنما دستورالعمل هایی برای انتقال 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

مستندات مرجع 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

مستندات مرجع 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 ​​است که هر کدام شامل یک یا دو محدوده تاریخ است، همانطور که نمودار زیر نشان می‌دهد:

Report Rows

ردیف ها

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

اسناد مرجع 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

اسناد مرجع 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 ​​است که هر کدام شامل یک یا دو محدوده تاریخ است، همانطور که نمودار زیر نشان می‌دهد:

Report Rows

ردیف ها

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

مستندات مرجع 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

مستندات مرجع 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 ​​است که هر کدام شامل یک یا دو محدوده تاریخ است، همانطور که نمودار زیر نشان می‌دهد:

Report Rows

ردیف ها

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.\" }"
   }
  ]
 }
}