Эта страница переведена с помощью Cloud Translation API.

Обзор

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

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

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

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

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

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

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

Методы создания сводных отчетов

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

Метод 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 , либо метод batchRunPivotReports .

Для запроса сводных данных можно создать объект 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 поддерживает несколько сводных таблиц при условии, что произведение параметра limit для каждой сводной таблицы не превышает 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 указывает город («Париж» или «Нью-Йорк»), из которого произошло каждое событие. В запросе на отчет вы можете указать ноль или более измерений.

Измерения должны быть определены в поле dimensions тела запроса. Чтобы быть видимыми в отчете, эти измерения также должны быть указаны в поле fieldNames объекта Pivot . Измерение не будет видно в отчете, если оно не используется ни в одной сводной таблице запроса 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",
    ]
  },
  ...

Вычисленные метрики возвращаются в поле aggregates объекта 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"
        }
      ]
    },
  ....

  }

Пагинация

Аналогично методам Core Reporting , запросы на создание сводных таблиц позволяют указывать поля limit и offset в объекте 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, отличается от ответа методов Core Reporting, таких как 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

google-analytics-data/src/run_pivot_report.php

Открыть в режиме Cloud Shell на GitHub

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()
        );
    }
}run_pivot_report.php

Python

google-analytics-data/run_pivot_report.py

Открыть в режиме Cloud Shell на GitHub

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)

run_pivot_report.py

Node.js

google-analytics-data/run_pivot_report.js

Открыть в режиме Cloud Shell на GitHub

  // 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);
      });
    });
  }run_pivot_report.js

Демонстрационное приложение

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

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

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

Методы создания сводных отчетов

Выбор отчетной организации

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

HTTP

Повороты

Размеры

Метрики

Агрегированные метрики

Пагинация

Фильтрация

Сортировка

Ответ на отчет

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

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

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

PHP

Python

Node.js

Демонстрационное приложение

Обзор