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

В этом руководстве представлены рекомендации по переходу с Core Reporting API v3 на Analytics Reporting API v4.

Введение

Чтобы воспользоваться преимуществами новых функций , представленных в Analytics Reporting API v4, перенесите свой код на использование API. В этом руководстве показаны запросы в Core Reporting API v3 и эквивалентные запросы в Analytics Reporting API v4, чтобы упростить миграцию.

Миграция Python

Если вы разработчик Python, используйте вспомогательную библиотеку 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

В следующих примерах сравнивается запрос в версии 3 и эквивалентный запрос в версии 4:

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

Клиентские библиотеки и служба обнаружения

Если вы используете Python, JavaScript или другую клиентскую библиотеку, основанную на 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')

JavaScript

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

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

Запросы

В справочнике API v4 подробно описана структура тела запроса. В следующих разделах описывается миграция параметров запроса версии 3 в параметры запроса версии 4.

Посмотреть идентификаторы

В версии 3 параметр ids , который принимает «идентификатор таблицы», имеет формат ga:XXXX , где XXXX — идентификатор представления (профиля). В версии 4 идентификатор представления (профиля) указывается в поле viewId тела запроса.

В следующих примерах сравниваются параметр ids в запросе версии 3 и поле viewId в запросе версии 4:

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

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

API отчетов Analytics версии 4 позволяет указывать несколько диапазонов дат в одном запросе. Поле dateRanges принимает список объектов DateRange . В версии 3 вы используете параметры start-date и end-date чтобы указать диапазон дат в запросе.

В следующих примерах сравниваются параметры start-date и end-date в запросе версии 3 и поле dateRanges в запросе версии 4:

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

Метрики

Параметр metrics v3 соответствует полю metrics v4, которое принимает список объектов Metric .

В следующих примерах сравниваются параметры metrics в запросе версии 3 и поле metrics в запросе версии 4:

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

Размеры

Параметр dimensions v3 соответствует полю dimensions v4, которое принимает список объектов измерения .

В следующих примерах сравниваются параметры dimensions в запросе версии 3 и поле dimensions в запросе версии 4:

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 версии 3 эквивалентен полю orderBys версии 4, которое принимает список объектов OrderBy .

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

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

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

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

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

Параметр samplingLevel v3 соответствует полю samplingLevel v4. В версии 3 принятые значения samplingLevel — FASTER , HIGHER_PRECISION и DEFAULT ; а в версии 4 принятые значения samplingLevel — SMALL , LARGE и DEFAULT . Обратите внимание, что FASTER в v3 изменено на SMALL в v4, HIGHER_PRECISION на LARGE .

В следующих примерах сравнивается параметр samplingLevel в запросе версии 3 и поле samplingLevel в запросе версии 4:

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 соответствует полю segments версии 4, которое принимает список объектов сегмента .

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

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

В следующих примерах сравниваются параметр segment в запросе версии 3 и поле segments в запросе версии 4:

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 в запросе версии 3 и поле segments , содержащее объект DynamicSegment , в запросе версии 4:

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 в v4

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

В следующих примерах показано, как параметр segment в запросе версии 3 поддерживается полем segmentId в эквивалентном запросе в версии 4:

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

Фильтры

Версия 4 использует dimensionFilterClauses для фильтрации измерений и metricFilterClauses для фильтрации показателей. dimensionFilterClauses содержит список объектов DimensionFilter ; а metricFilterClauses содержит список объектов MetricFilter .

В следующих примерах сравниваются параметр filters в запросе версии 3 и поле dimensionFilterClauses в запросе версии 4:

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 в v4

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

В следующих примерах показано, как параметр filters в запросе версии 3 поддерживается полем filtersExpression в эквивалентном запросе в версии 4:

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

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

Параметр include-empty-rows версии 3 соответствует полю includeEmptyRows в версии 4. Параметр v3 по умолчанию имеет значение true , тогда как в v4 поле по умолчанию имеет значение false . Если у вас нет значения, установленного в версии 3, вам необходимо установить значение true в версии 4.

В следующих примерах параметр include-empty-rows в запросе версии 3 сравнивается с полем includeEmptyRows в запросе версии 4:

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 в запросе версии 3 сравниваются с полями pageToken и pageSize в запросе версии 4:

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 версии 4 поддерживает большинство стандартных параметров запроса в API версии 3, за исключением userIp и параметров callback .

В следующих примерах сравнивается параметр quotaUser в запросе версии 3 с параметром в запросе версии 4:

v3 Конечная точка

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

v4 Конечная точка

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

Ответы

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

Отчеты

Отчет версии 4 имеет три поля верхнего уровня: columnHeader , data и nextPageToken .

Поскольку тело ответа версии 4 не включает ответы на все параметры запроса, как это делает ответ версии 3, чтобы получить ответ на определенный параметр запроса, клиентское приложение должно добавить этот параметр в ReportRequest .

Мы уже рассматривали nextPageToken в разделе «Разбиение на страницы» , поэтому давайте сначала посмотрим на объект columnsHeader .

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

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

В следующих примерах поле columnHeaders в ответе версии 3 сравнивается с полем columnHeader в ответе версии 4:

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 возвращает данные отчета в массиве строк , который содержит запрошенные параметры и показатели.

API отчетов Analytics версии 4 возвращает данные отчета в объекте 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 .

API отчетов аналитики версии 4 не возвращает логическое значение, если данные выбираются; скорее API возвращает поля 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"],
      }
    }
  ]
}

Анализ ответа 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));
        }
      }
    }
  }
}

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

Поскольку формат ответа об ошибке в версии 4 отличается от формата в версии 3, обновите свой код для обработки ответов об ошибках версии 4.

В следующих примерах сравнивается ответ об ошибке в версии 3 и эквивалентный ответ об ошибке в версии 4:

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