Обзор

API данных Google Analytics v1 позволяет создавать сводные таблицы. Сводные таблицы — это инструмент суммирования данных, который визуализирует данные путем изменения порядка информации в таблице путем поворота (поворота) ваших данных по одному или нескольким измерениям.

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

Таблица исходных данных

Используя эти данные, можно построить сводную таблицу, разбивая данные сеансов по браузерам, с параметрами страны и языка, выбранными в качестве дополнительных сводных данных.

Сводная таблица данных

Общие функции с основными отчетами

Запросы сводных отчетов имеют ту же семантику, что и запросы основных отчетов для многих общих функций. Например, нумерация страниц, фильтры измерений и свойства пользователя в сводных отчетах ведут себя так же, как и в основных отчетах. В этом руководстве основное внимание уделяется функциям сводных отчетов. Чтобы ознакомиться с основными функциями отчетов Data API v1, прочтите руководство по основам создания отчетов , а также руководство по расширенным вариантам использования .

Методы сводных отчетов

Data API v1 поддерживает функции сводной таблицы в следующих методах отчетности:

  • runPivotReport Этот метод возвращает настроенный сводный отчет с данными о событиях Google Analytics. Каждая сводная таблица описывает видимые столбцы и строки измерений в ответе отчета.

  • BatchRunPivotReports. Это пакетная версия метода runPivotReport , которая позволяет создавать несколько отчетов с помощью одного вызова API.

Выбор отчитывающейся организации

Все методы Data API v1 требуют указания идентификатора свойства Google Analytics внутри пути запроса URL-адреса в форме properties/GA_PROPERTY_ID , например:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport

Результирующий отчет будет создан на основе данных о событиях Google Analytics, собранных в указанном ресурсе Google Analytics.

Если вы используете одну из клиентских библиотек Data API , нет необходимости вручную манипулировать URL-путем запроса. Большинство клиентов API предоставляют параметр property , который ожидает строку в виде properties/GA_PROPERTY_ID . См. Краткое руководство для примеров использования клиентских библиотек.

Запрос сводного отчета

Чтобы создать запрос со сводной таблицей, используйте метод runPivotReport или метод patchRunPivotReports .

Чтобы запросить сводные данные, вы можете создать объект RunPivotReportRequest . Мы рекомендуем начать со следующих параметров запроса:

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

Вот пример запроса с рекомендуемыми полями:

HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
  {
    "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
    "dimensions": [
        { "name": "browser" },
        { "name": "country" },
        { "name": "language" }
      ],
    "metrics": [{ "name": "sessions" }],
    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 15
      }
    ]
  }

Повороты

Используйте объекты Pivot в поле pivot тела запроса, чтобы определить сводные данные отчета. Каждый Pivot описывает видимые столбцы и строки измерения в ответе отчета.

API данных версии 1 поддерживает несколько сводных данных, если произведение предельного параметра для каждого сводного значения не превышает 100 000.

Ниже приведен фрагмент, демонстрирующий использование pivots для построения отчета о количестве сеансов по странам с разбивкой по параметрам browser . Обратите внимание, что запрос использует поле orderBys для сортировки , а поля limit и offset для реализации разбиения на страницы .

    "pivots": [
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "browser"
        ],
        "offset": 3,
        "limit": 3,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }
    ],
    ...

Размеры

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

Размеры должны быть определены внутри поля размеров тела запроса. Чтобы эти измерения были видны в отчете, они также должны быть указаны в поле «Имена полей» объекта Pivot . Измерение не будет отображаться в отчете, если оно не используется ни в одной сводке сводного запроса. Не каждое измерение должно присутствовать в fieldNames сводной таблицы. Измерения можно использовать исключительно в фильтрах, а не в fieldNames любой сводной таблицы.

Ниже приведен фрагмент, демонстрирующий использование полей dimension и fieldNames для таблицы с указанием browser , country и language :

    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 10
      }
    ],

Метрики

Метрики – это количественные измерения данных о событиях на вашем веб-сайте или в приложении. В запросе отчета вы можете указать одну или несколько метрик. Полный список имен метрик API, доступных для указания в запросах, см. в разделе «Метрики API».

В запросах сводных отчетов метрики определяются с использованием поля metrics тела запроса, что аналогично методам базовой отчетности .

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

    "metrics": [
      {
        "name": "sessions"
      }
    ],

Агрегации показателей

Используйте поле metricAggregations объекта Pivot для расчета агрегированных значений метрик для каждого сводного объекта.

Агрегации будут рассчитываться только в том случае, если в запросе указано поле metricAggregations .

Ниже приведен фрагмент запроса, который запрашивает итоговые значения для сводного измерения browser :

"pivots": [
  {
    "fieldNames": [
      "browser"
    ],
    "limit": 10,
    "metricAggregations": [
      "TOTAL",
    ]
  },
  ...

Рассчитанные метрики возвращаются в поле агрегатов объекта RunPivotReportResponse . Для строк агрегированных показателей поле dimensionValues ​​содержит специальное значение RESERVED_TOTAL , RESERVED_MAX или RESERVED_MIN .

  "aggregates": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "4"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "6"
        }
      ]
    },
  ....

  }

Пагинация

Подобно основным методам отчетности , сводные запросы позволяют указать поля предела и смещения в объекте Pivot для реализации разбиения на страницы. Настройки пагинации применяются к каждому сводному элементу индивидуально. Поле limit необходимо для каждого объекта Pivot , чтобы ограничить количество элементов отчета.

API данных версии 1 поддерживает несколько сводных данных, если произведение limit параметра для каждого сводного значения не превышает 100 000.

Ниже приведен фрагмент, демонстрирующий использование полей offset и limit для получения следующих пяти language измерений со смещением 10:

      {
        "fieldNames": [
          "language"
        ],
        "offset": 10,
        "limit": 5
      }

Фильтрация

Как и в случае с основной функцией отчетности , фильтр параметров на уровне запроса необходимо использовать, если в запросе сводных отчетов требуется фильтрация параметров.

Сортировка

Поведением упорядочения запросов сводного отчета можно управлять для каждого сводного отчета индивидуально с помощью поля orderBys объекта Pivot , который содержит список объектов OrderBy .

Каждый OrderBy может содержать одно из следующего:

  • DimensionOrderBy сортирует результаты по значениям измерения.
  • MetricOrderBy сортирует результаты по значениям метрики.
  • PivotOrderBy используется в сводных запросах и сортирует результаты по значениям метрики в группе сводных столбцов.

В этом примере показан фрагмент определения сводной таблицы, которая сводит отчет по измерению browser , упорядочивая результаты по показателю sessions в порядке убывания.

      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }

Сообщить об ответе

Ответ сводного отчета на запрос API сводного отчета представляет собой в основном заголовок и строки.

Заголовки ответов

Заголовок сводного отчета состоит из PivotHeaders , DimensionHeaders и MetricHeaders , в которых перечислены столбцы сводного отчета.

Например, отчет со сводными параметрами browser , country и language и метрикой sessions будет содержать такие заголовки:

{
  "pivotHeaders": [
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "Chrome"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Firefox"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "United States"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Canada"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "English"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "French"
            }
          ]
        },
        ...

      ],
      ...
    }
  ],
  "dimensionHeaders": [
    {
      "name": "browser"
    },
    {
      "name": "country"
    },
    {
      "name": "language"
    }
  ],
  "metricHeaders": [
    {
      "name": "sessions",
      "type": "TYPE_INTEGER"
    }
  ],
  ...

}

На диаграмме ниже показана роль каждого компонента ответа сводного отчета при отображении сводного отчета:

Таблица исходных данных

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

Ответ сводного отчета методов runPivotReport и BatchRunPivotReports отличается от ответа для основных методов отчетности, таких как runReport и BatchRunReports , тем, что каждая строка ответа сводного отчета представляет одну ячейку таблицы , тогда как в обычном отчете одна строка ответа представляет полную строку таблицы. .

Ниже приведен фрагмент ответа сводного отчета на запрос с параметрами сводной информации о browser , country и language , а также метрикой sessions . Каждая ячейка сводного отчета возвращается индивидуально:

  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "United States"
        },
        {
          "value": "English"
        }
      ],
      "metricValues": [
        {
          "value": "1"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "Canada"
        },
        {
          "value": "French"
        }
      ],
      "metricValues": [
        {
          "value": "3"
        }
      ]
    },
    ...

  ]

Эти данные соответствуют двум ячейкам, выделенным в таблице ниже:

Таблица исходных данных

Клиентские библиотеки

См. краткое руководство по установке и настройке клиентских библиотек .

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

PHP

use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\OrderBy;
use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy;
use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy;
use Google\Analytics\Data\V1beta\Pivot;
use Google\Analytics\Data\V1beta\RunPivotReportRequest;
use Google\Analytics\Data\V1beta\RunPivotReportResponse;

/**
 * Runs a pivot query to build a report of session counts by country,
 * pivoted by the browser dimension.
 * @param string $propertyId Your GA-4 Property ID
 */
function run_pivot_report(string $propertyId)
{
    // Create an instance of the Google Analytics Data API client library.
    $client = new BetaAnalyticsDataClient();

    // Make an API call.
    $request = (new RunPivotReportRequest())
        ->setProperty('properties/' . $propertyId)
        ->setDateRanges([new DateRange([
            'start_date' => '2021-01-01',
            'end_date' => '2021-01-30',
            ]),
        ])
        ->setPivots([
            new Pivot([
                'field_names' => ['country'],
                'limit' => 250,
                'order_bys' => [new OrderBy([
                    'dimension' => new DimensionOrderBy([
                        'dimension_name' => 'country',
                    ]),
                ])],
            ]),
            new Pivot([
                'field_names' => ['browser'],
                'offset' => 3,
                'limit' => 3,
                'order_bys' => [new OrderBy([
                    'metric' => new MetricOrderBy([
                        'metric_name' => 'sessions',
                    ]),
                    'desc' => true,
                ])],
            ]),
        ])
        ->setMetrics([new Metric(['name' => 'sessions'])])
        ->setDimensions([
            new Dimension(['name' => 'country']),
            new Dimension(['name' => 'browser']),
        ]);
    $response = $client->runPivotReport($request);

    printPivotReportResponse($response);
}

/**
 * Print results of a runPivotReport call.
 * @param RunPivotReportResponse $response
 */
function printPivotReportResponse(RunPivotReportResponse $response)
{
    print 'Report result: ' . PHP_EOL;

    foreach ($response->getRows() as $row) {
        printf(
            '%s %s' . PHP_EOL,
            $row->getDimensionValues()[0]->getValue(),
            $row->getMetricValues()[0]->getValue()
        );
    }
}

Питон

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    OrderBy,
    Pivot,
    RunPivotReportRequest,
)


def run_sample():
    """Runs the sample."""
    # TODO(developer): Replace this variable with your Google Analytics 4
    #  property ID before running the sample.
    property_id = "YOUR-GA4-PROPERTY-ID"
    run_pivot_report(property_id)


def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a pivot query to build a report of session counts by country,
    pivoted by the browser dimension."""
    client = BetaAnalyticsDataClient()

    request = RunPivotReportRequest(
        property=f"properties/{property_id}",
        date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
        pivots=[
            Pivot(
                field_names=["country"],
                limit=250,
                order_bys=[
                    OrderBy(
                        dimension=OrderBy.DimensionOrderBy(dimension_name="country")
                    )
                ],
            ),
            Pivot(
                field_names=["browser"],
                offset=3,
                limit=3,
                order_bys=[
                    OrderBy(
                        metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
                    )
                ],
            ),
        ],
        metrics=[Metric(name="sessions")],
        dimensions=[Dimension(name="country"), Dimension(name="browser")],
    )
    response = client.run_pivot_report(request)
    print_run_pivot_report_response(response)


def print_run_pivot_report_response(response):
    """Prints results of a runPivotReport call."""
    print("Report result:")
    for row in response.rows:
        for dimension_value in row.dimension_values:
            print(dimension_value.value)

        for metric_value in row.metric_values:
            print(metric_value.value)


Node.js


  // TODO(developer): Uncomment this variable and replace with your
  // Google Analytics 4 property ID before running the sample.
  // propertyId = 'YOUR-GA4-PROPERTY-ID';

  // Imports the Google Analytics Data API client library.
  const {BetaAnalyticsDataClient} = require('@google-analytics/data');

  // Initialize client that will be used to send requests. This client only
  // needs to be created once, and can be reused for multiple requests.
  const analyticsDataClient = new BetaAnalyticsDataClient();

  // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension.
  async function runPivotReport() {
    const [response] = await analyticsDataClient.runPivotReport({
      property: `properties/${propertyId}`,
      dateRanges: [
        {
          startDate: '2021-01-01',
          endDate: '2021-01-30',
        },
      ],
      pivots: [
        {
          fieldNames: ['country'],
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: 'country',
              },
            },
          ],
        },
        {
          fieldNames: ['browser'],
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: 'sessions',
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: 'sessions',
        },
      ],
      dimensions: [
        {
          name: 'country',
        },
        {
          name: 'browser',
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

  // Prints results of a runReport call.
  function printPivotReportResponse(response) {
    console.log('Report result:');
    response.rows.forEach(row => {
      row.dimensionValues.forEach(dimensionValue => {
        console.log(dimensionValue.value);
      });

      row.metricValues.forEach(metricValue => {
        console.log(metricValue.value);
      });
    });
  }

Демо-приложение

См. демонстрационное приложение сводного отчета Google Analytics API v1, где приведен пример создания и отображения сводного отчета с использованием JavaScript.