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

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

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

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

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

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

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

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

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

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

Для всех методов API данных версии 1 требуется, чтобы идентификатор свойства Google Analytics 4 был указан внутри пути запроса URL-адреса в форме properties/GA4_PROPERTY_ID , например:

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

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

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

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

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

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

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

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

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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 и patchRunPivotReports отличается от ответа для основных методов отчетности, таких как 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"
        }
      ]
    },
    ...

  ]

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

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

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

Ниже приведен пример использования клиентской библиотеки Python, которая выполняет сводный запрос для создания отчета о количестве сеансов по стране, сгруппированного по измерению браузера.

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

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

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