Руководство по переходу

В этой статье приведены рекомендации по переходу с Core Reporting API версии 3 на Analytics Reporting API версии 4.

Введение

Если вы хотите пользоваться всеми преимуществами Analytics Reporting API версии 4, вам нужно изменить код. Чтобы упростить эту задачу, мы расскажем, как запросы к новому API соотносятся с запросами к Core Reporting API версии 3.

Переход для Python

Если вы применяете Python, воспользуйтесь вспомогательной библиотекой GAV4, которая доступна на GitHub. Она позволяет конвертировать запросы к Google Analytics Core Reporting API версии 3 в формат, приемлемый для Analytics Reporting API версии 4.

Конечные точки

В Core Reporting API версии 3 и Analytics Reporting API версии 4 разные конечные точки и методы HTTP.

Конечная точка версии 3

GET https://www.googleapis.com/analytics/v3/data/ga

Конечная точка версии 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet

Ниже приведены примеры запросов в версии 3 и их аналоги в версии 4.

Версия 3

Справочные материалы Analytics Reporting API версии 3

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

Версия 4

Справочные материалы Analytics Reporting API версии 4

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

Если вы используете Python, JavaScript или любую другую клиентскую библиотеку, которой для работы нужен сервис Google Discovery, вам требуется указать местоположение документа Discovery для Reporting API версии 4.

Python

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')

JavaScript

gapi.client.load(
  'https://analyticsreporting.googleapis.com/$discovery/rest',
  'v4'
).then(...)

Клиентские библиотеки Java и PHP обычно предустановлены. Также вы можете создать их с помощью сервиса Discovery и генератора Google API.

Запросы

Структура запросов, принятая в API версии 4, подробно описана в справочных материалах. Разделы ниже посвящены тому, что нужно изменить в параметрах запросов при переходе на эту версию с Core Reporting API версии 3.

Идентификаторы представления

В версии 3 параметр ids, который принимает значение table ID, имеет формат ga:XXXX, где XXXX – идентификатор представления (профиля). В версии 4 этот идентификатор указывается в поле viewId в теле запроса.

Ниже приведено сравнение параметра ids в запросе версии 3 и поля viewId в запросе версии 4.

Версия 3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    "viewId":"XXXX",
    ...
  }]
}

Диапазоны дат

В запросах Analytics Reporting API версии 4 можно указывать несколько диапазонов дат. Для этого достаточно добавить в поле dateRanges список объектов DateRange. В версии 3 для указания начала и конца диапазона дат используются параметры start-date и end-date соответственно.

Ниже приводится сравнение параметров start-date и end-date в запросе версии 3 и поля dateRanges в запросе версии 4.

Версия 3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
    &start-date=2015-11-01&end-date=2015-11-06 \
    ...

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    "viewId":"XXXX",
    "dateRanges":[
    {
      "startDate":"2015-11-01",
      "endDate":"2015-11-06"
    }],
    ....
  }]
}

Показатели

В версии 3 показатели задаются с помощью параметра metrics, а в версии 4 – с помощью поля metrics, в которое добавляется список объектов Metric.

В примере ниже параметры metrics в запросе версии 3 сравниваются с полем metrics в запросе версии 4.

Версия 3

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 \
    ...

Версия 4

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

Параметры

Параметр dimensions в версии 3 соответствует полю dimensions, в которое в версии 4 добавляется список объектов Dimension.

В примере ниже параметры dimensions в запросе версии 3 сравниваются с полем dimensions в запросе версии 4.

Версия 3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
  &dimensions=ga:country,ga:browser&... \

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    "dimensions": [
    {
      "name":"ga:country"
    },{
      "name":"ga:browser"
    }],
    ...
  }]
}

Сортировка

Параметру sort API версии 3 соответствует поле orderBys в версии 4, куда добавляется список объектов OrderBy.

В версии 4 результаты можно сортировать по параметру или значению показателя:

  • Укажите его имя или псевдоним в поле fieldName.
  • Укажите порядок сортировки – ASCENDING (по возрастанию) или DESCENDING (по убыванию) – в поле sortOrder.

В примере ниже сравнивается использование параметра sort в версии 3 и поля orderBy в версии 4. Представлена сортировка пользователей по убыванию и источников по алфавиту.

Версия 3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
  &sort=-ga:users,ga:source

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    "orderBys": [
    {
      "fieldName": "ga:users",
      "sortOrder": "DESCENDING"
    },{
      "fieldName": "ga:source"
    }],
  }]
}

Уровень выборки

Параметр samplingLevel в версии 3 соответствует полю samplingLevel в версии 4. В версии 3 у параметра samplingLevel три допустимых значения: FASTER, HIGHER_PRECISION и DEFAULT. В версии 4 поле samplingLevel также может принимать три значения: SMALL, LARGE и DEFAULT. Изменились только наименования этих значений: SMALL вместо FASTER и LARGE вместо HIGHER_PRECISION.

В примерах ниже сравниваются параметр samplingLevel в запросе версии 3 и поле samplingLevel в запросе версии 4.

Версия 3

https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    "samplingLevel": "LARGE"
  }]
}

Сегменты

Параметру segment API версии 3 в версии 4 соответствует поле segments, в которое добавляется список объектов Segment.

Идентификаторы сегментов

Если вы пользуетесь версией 4 и вам нужно включить сегмент в запрос по идентификатору, создайте объект Segment и укажите идентификатор в поле segmentId.

В примере ниже приведено сравнение параметра segment в запросе версии 3 и поля segments в запросе версии 4.

Версия 3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [{
    ...
    "viewId": "XXXX",
    "segments": [{
      "segmentId": "gaid::-11"
    }]
  }]
}

Динамические сегменты

В версии 4 проще выражать сложные параметры сегментов. Для этого используется поле segments с объектом DynamicSegment.

В примерах ниже приведено сравнение параметра segment в запросе версии 3 и поля segments, содержащего объект DynamicSegment, в запросе версии 4.

Версия 3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral

Версия 4

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

Условия и последовательности можно объединять в сегментах.

Версия 3

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

Версия 4

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

Синтаксис сегментов в новой версии

Поле segmentId в версии 4 поддерживает синтаксис сегментов, принятый в API версии 3.

Ниже приведены примеры параметра segment в версии 3 и его передачи с помощью поля segmentId в версии 4.

Версия 3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [{
    ...
    "viewId": "XXXX",
    "segments": [{
      "segmentId": "sessions::condition::ga:medium==referral"
    }]
  }]
}

Фильтры

В API версии 4 для фильтрации используются два поля: dimensionFilterClauses для параметров и metricFilterClauses для показателей. Поле dimensionFilterClauses содержит список объектов DimensionFilter, а поле metricFilterClauses – списки объектов MetricFilter.

В примере ниже приведено сравнение параметра filters в запросе версии 3 и поля dimensionFilterClauses в запросе версии 4.

Версия 3

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

Версия 4

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

Синтаксис фильтров в новой версии

Несмотря на то что поле filtersExpression в версии 4 поддерживает синтаксис фильтров версии 3, в котором используется параметр filters, для фильтрации все равно следует использовать поля dimensionFilterClauses и metricFilterClauses.

Ниже приведены примеры параметра filters в версии 3 и его передачи с помощью поля filtersExpression в версии 4.

Версия 3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [{
    ...
    "filtersExpression": "ga:browser==Firefox"
  }]
}

Пустые строки

Параметр include-empty-rows в версии 3 полностью соответствует полю includeEmptyRows в версии 4. Значение параметра по умолчанию в версии 3 – true, а значение поля по умолчанию в версии 4 – false. Если вы не установили значение параметра в версии 3, после перехода на версию 4 значения поля нужно изменить на true.

В примерах ниже можно сравнить параметр include-empty-rows в запросе 3 и поле includeEmptyRows в запросе версии 4.

Версия 3

https://www.googleapis.com/analytics/v3/data/ga? ...\
    &include-empty-rows=true

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    "includeEmptyRows": "true",
  }]
}

Разбиение на страницы

В версии 4 результаты разбиваются на страницы с помощью полей pageToken и pageSize. Значение поля pageToken берется из свойства nextPageToken объекта ответа.

В примерах ниже параметры start-index и max-results в запросе версии 3 сравниваются с полями pageToken и pageSize в запросе версии 4.

Версия 3

https://www.googleapis.com/analytics/v3/data/ga? ...\
    &start-index=10001&max-results=10000

Версия 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

Стандартные параметры

Analytics Reporting API версии 4 поддерживает большинство стандартных запросов, представленных в версии 3. Исключение составляют параметры userIp и callback.

В примере ниже приводится сравнение параметра quotaUser в версии 3 и версии 4.

Конечная точка версии 3

GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2

Конечная точка версии 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2

Ответы

Поскольку в версии 4 в одном HTTP-запросе можно отправить сразу несколько объектов ReportRequest, в ответе часто возвращается целый массив отчетов. Каждому отправленному объекту ReportRequest соответствует ответный объект Report.

Отчеты

В объекте Report версии 4 есть три поля верхнего уровня: columnHeader, data и nextPageToken.

Поскольку в тексте ответа версии 4 не возвращаются ответы на все параметры запроса (в отличие от ответа версии 3), интересующие вас параметры нужно указывать в объекте ReportRequest.

Использование поля nextPageToken описывалось в разделе Разбиение на страницы, поэтому теперь перейдем к объекту columnHeader.

Заголовок столбца

Заголовок столбца содержит список названий параметров и объект MetricHeader, который включает список объектов MetricHeaderEntry. Каждый объект MetricHeaderEntry задает название (name) показателя и его тип (type): валюта, проценты и т. п. Это позволяет точнее определить вывод.

В примере ниже сравнивается поле columnHeaders в ответе версии 3 и поле columnHeader в версии 4.

Версия 3

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

Версия 4

"columnHeader": {
    "dimensions": [
        "ga:source",
        "ga:city"
    ],
    "metricHeader": {
        "metricHeaderEntries": [
            {
                "name": "ga:pageviews",
                "type": "INTEGER"
            },
            {
                "name": "ga:sessions",
                "type": "INTEGER"
            }
        ]
    }
},

Строки в отчете

Core Reporting API версии 3 возвращает данные отчета в массиве строк, который включает запрошенные параметры и показатели.

Analytics Reporting API версии 4 возвращает данные в объекте ReportRow. Он содержит массив параметров и объектов DateRangeValues, каждый из которых включает один или два диапазона дат, как показано на схеме ниже.

Строки в отчете

Строки

Версия 3

"rows": [
    [
        "google",
        "Philadelphia",
        "60",
        "5"
    ],
    [
        "google",
        "Johnstown",
        "21",
        "1"
    ],
    [
        "google",
        "Progress",
        "7",
        "1"
    ]
],

Версия 4

"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 версии 3 возвращает поле containsSampledData с логическим значением true.

В Analytics Reporting API версии 4 вместо поля с логическим значением возвращаются поля samplesReadCounts и samplingSpaceSizes. Если выборки нет, эти поля не определяются. В примере с Python ниже указано, как выполняется расчет отчета с выборочными данными.

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"],
      }
    }
  ]
}

Синтаксический анализ ответа в версии 4

Код в примере ниже запускает синтаксический анализ и печать ответа Analytics Reporting API версии 4.

Python

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

Java

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));
        }
      }
    }
  }
}

Обработка ошибок

Формат ответов при ошибках в версии 4 отличается от формата в предыдущей версии, поэтому для его обработки вам потребуется обновить код.

Ниже приведены примеры аналогичных ответов при ошибках из версии 3 и версии 4.

Версия 3

{
 "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."
 }
}

Версия 4

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