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

В этой статье приведены рекомендации по переходу с 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

Справочные материалы Core 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 Service, вам требуется указать местоположение документа 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, представленный в версии 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. Изменились только наименования этих значений: FASTER на SMALL и HIGHER_PRECISION на LARGE.

В примерах ниже сравниваются параметр 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 в версии 3 аналогичен полю segments, в которое в версии 4 загружается список объектов 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"]
                    }
                  }]
                }]
              }]
            }
          }]
        }
      }
    }]
  }]

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

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

В примере ниже показано, как перенести параметр segment из запроса версии 3 в поле segments в запросе версии 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"]
            }]
      }]
  }]

Поддержка синтаксиса фильтров версии 3 в новой версии

Несмотря на то что поле filtersExpression в версии 4 поддерживает синтаксис фильтров, принятый в параметре 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 в третьей версии полностью соответствует полю 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 V3 возвращает данные отчета в массиве строк, который включает запрошенные параметры и показатели.

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

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

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

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