Создание отчета

Это руководство для разработчиков по Analytics Reporting API v4. Подробную информацию об API см. в справочнике по API .

Отчеты

API отчетов Analytics версии 4 предоставляет метод BatchGet для доступа к ресурсу Reports . В следующих разделах описывается структура тела запроса для batchGet и структура тела ответа из batchGet .

Тело запроса

Чтобы использовать API отчетов Google Analytics версии 4 для запроса данных, необходимо создать объект ReportRequest , который соответствует следующим минимальным требованиям:

  • Действительный идентификатор представления для поля viewId .
  • По крайней мере одна действительная запись в поле dateRanges .
  • По крайней мере одна действительная запись в поле метрики .

Чтобы найти идентификатор представления , запросите метод сводки учетных записей или воспользуйтесь проводником учетных записей . Если диапазон дат не указан, диапазон дат по умолчанию: {"startDate": "7daysAgo", "endDate": "yesterday"} .

Вот пример запроса с минимумом обязательных полей:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:users"}]
    }
  ]
}

Метод batchGet принимает максимум пять объектов ReportRequest . Все запросы должны иметь одинаковые dateRange , viewId , segments , samplingLevel и cohortGroup .

Тело ответа

Тело ответа запроса API представляет собой массив объектов отчета . Структура отчета определяется в объекте ColumnHeader , который описывает измерения и метрики, а также их типы данных в отчете. Значения параметров и показателей указываются в поле данных .

Вот пример ответа на приведенный выше образец запроса:

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

Метрики

Метрики — это количественные измерения; для каждого запроса требуется хотя бы один объект Metric .

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

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:sessions"}]
    }
  ]
}

Вы можете использовать проводник параметров и показателей или API метаданных, чтобы получить список доступных параметров и показателей.

Фильтрация

Отправляя запрос batchGet , вы можете попросить его возвращать только метрики, соответствующие определенным критериям. Чтобы фильтровать метрики, в теле запроса укажите один или несколько MetricFilterClause и в каждом MetricFilterClause определите один или несколько MetricFilters . В каждом MetricFilter укажите следующие значения:

  • metricName
  • not
  • operator
  • comparisonValue

Пусть {metricName} представляет метрику, {operator} operator , а {comparisonValue} comparisonValue . Тогда фильтр работает следующим образом:

if {metricName} {operator} {comparisonValue}
   return the metric

Если вы укажете true для not , фильтр будет работать следующим образом:

if {metricName} {operator} {comparisonValue}
   do not return the metric

В следующем примере batchGet возвращает только просмотры страниц, значение которых больше 2:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

Выражения

Выражение показателя — это математическое выражение, которое вы определяете на основе существующих показателей; он работает как динамические вычисляемые показатели . Вы можете определить псевдоним для представления выражения метрики, например:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

Заказ

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

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

В следующем примере batchGet возвращает метрики, отсортированные сначала по сеансам, а затем по просмотрам страниц в порядке убывания:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

Размеры

Размеры описывают характеристики ваших пользователей, их сеансы и действия. Например, параметр «Город» описывает характеристики сеансов и указывает город («Париж» или «Нью-Йорк»), из которого был создан каждый сеанс. В запросе batchGet вы можете указать ноль или более объектов измерения , например:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics":
      [
        {"expression": "ga:users"}
      ],
      "dimensions":
      [
        {"name": "ga:city"}
      ]
    }
  ]
}

Фильтрация

Отправляя запрос batchGet , вы можете попросить его возвращать только те измерения, которые соответствуют определенным критериям. Чтобы фильтровать измерения, в тексте запроса укажите один или несколько DimensionsFilterClauses и в каждом DimensionsFilterClause определите один или несколько DimensionsFilters . В каждом DimensionsFilters укажите следующие значения:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

Пусть {dimensionName} представляет измерение, {operator} operator , а {expressions} expressions . Тогда фильтр работает следующим образом:

if {dimensionName} {operator} {expressions}
    return the dimension

Если вы укажете true для not , фильтр будет работать следующим образом:

if {dimensionName} {operator} {expressions}
    do not return the dimension

В следующем примере batchGet возвращает просмотры страниц и сеансы в браузере Chrome:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

Заказ

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

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

Например, следующий batchGet возвращает измерения, отсортированные по стране, а затем по браузеру:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

Сегменты гистограммы

Характеристики измерений с целочисленными значениями легче понять, разбив их значения на диапазоны. Используйте поле histogramBuckets , чтобы определить диапазоны результирующих сегментов, и укажите HISTOGRAM_BUCKET в качестве типа заказа, например:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

Несколько диапазонов дат

API отчетов Google Analytics версии 4 позволяет получать данные за несколько диапазонов дат в одном запросе. Независимо от того, указывает ли ваш запрос один или два диапазона дат, данные возвращаются в объекте dateRangeValue , например:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

Дельта-заказ

При запросе значений метрики в двух диапазонах дат вы можете упорядочить результаты по разнице значений метрики в диапазонах дат, например:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

Поведение измерения даты

Если вы запрашиваете измерение, связанное с датой или временем , объект DateRangeValue будет содержать только значения для дат, попадающих в соответствующие диапазоны; все остальные значения, не входящие в указанные диапазоны дат, будут равны 0 .

Например, рассмотрим запрос измерения ga:date и показателя ga:sessions в двух диапазонах дат: январь и февраль. В ответе на запрошенные данные за январь значения за февраль будут равны 0 ; а в ответе на запрошенные данные за февраль значения за январь будут равны 0 .

Январский отчет

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

Отчет за февраль

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

Сегменты

Чтобы запросить подмножество данных Google Analytics, используйте сегменты . Например, вы можете определить пользователей из определенной страны или города в одном сегменте, а пользователей, посещающих определенную часть вашего сайта, — в другом. Фильтры возвращают только строки, удовлетворяющие условию, тогда как сегменты возвращают подмножество пользователей, сеансов или событий, соответствующих условиям, содержащим сегменты.

При выполнении запроса с сегментами убедитесь, что:

  • Каждый ReportRequest в методе batchGet должен содержать идентичные определения сегментов.
  • Вы добавляете ga:segment в список измерений.

Например:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

Дополнительные примеры запросов с сегментами см. в разделе «Примеры» .

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

Используйте поле segmentId для запроса сегментов. Вы не можете использовать одновременно segmentId и dynamicSegment для запроса сегментов.

Например:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

Выборка

Выборка может повлиять на результаты ваших данных и является распространенной причиной того, что значения, возвращаемые API, не соответствуют веб-интерфейсу. Используйте поле samplingLevel чтобы установить желаемый размер выборки.

  • Установите значение SMALL для быстрого ответа с меньшим размером выборки.
  • установите значение LARGE для более точного, но более медленного ответа.
  • установите значение DEFAULT для ответа, который сочетает в себе скорость и точность.

Например:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

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

Ниже приведен пример ответа, который содержит выборочные данные из запроса с двумя диапазонами дат. Результаты были рассчитаны на основе почти 500 тысяч выборок с размером пространства выборки примерно 15 миллионов сеансов :

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

Пагинация

API отчетов Analytics версии 4 использует поля pageToken и pageSize для разбивки по страницам результатов ответов, охватывающих несколько страниц. Вы получаете pageToken из параметра nextPageToken в ответе на запрос reports.batchGet :

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

Следующий шаг

Теперь, когда вы изучили основы создания отчета, взгляните на расширенные функции API v4.