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

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

Примечание. Клиентские библиотеки Objective-C можно найти в библиотеке Google API для Objective-C For Rest. Скачайте и установите ее с помощью CocoaPod.

Запросы

Структура запросов, принятая в 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"
    }],
    ....
  }]
}

Показатели

Параметр metrics в версии 3 соответствует полю metrics, в которое в версии 4 добавляется список объектов 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. Изменились только наименования этих значений: 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 версии 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"]
                    }
                  }]
                }]
              }]
            }
          }]
        }
      }
    }]
  }]

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

Поле 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",
  }]
}

Внимание! Значение, используемое по умолчанию для поля includeEmptyRows в версии 3, в API версии 4 было изменено. Если раньше вы пользовались установками по умолчанию, после перехода на новую версию нужно внести поправки.

Разбивка на страницы

В версии 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",
  }]
}

Примечание. Формально свойство nextPageToken может быть произвольной строкой, однако в большинстве случаев оно представляет собой индекс строки, отсчитываемый с нуля (в отличие от start-index, где индексация начинается с единицы). Чтобы обеспечить правильное разбиение на страницы, для поля pageToken рекомендуется использовать значение nextPageToken.

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

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

Примечание. Чтобы выяснить, содержит ли отчет выборочные данные, запрашивать значения samplesReadCounts и samplingSpaceSizes не требуется. Оба этих значения добавлены в пример в демонстрационных целях.

Ниже приведен пример ответа с выборкой, запрошенной по двум диапазонам дат. Для расчета результатов было проанализировано почти 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.\" }"
   }
  ]
 }
}