Обзор

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

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

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

Примечание. Справочную информацию по переносу существующего кода из Google Analytics Reporting API v4 (только для ресурсов Universal Analytics) в Google Analytics Data API v1 (только для ресурсов Google Analytics 4) см. в руководстве по миграции .

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

Запросы сводных отчетов имеют ту же семантику, что и запросы основных отчетов для многих общих функций. Например, нумерация страниц, фильтры измерений и свойства пользователя в сводных отчетах ведут себя так же, как и в основных отчетах. В этом руководстве основное внимание уделяется функциям сводных отчетов. Чтобы ознакомиться с основными функциями отчетов 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 .
• По крайней мере одна действительная запись в поле размеров .
• По крайней мере одна действительная запись в поле метрики .
• По крайней мере две действительные записи сводных данных в поле сводных данных .

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

HTTP

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 , чтобы ограничить количество элементов отчета.

Data API v1 поддерживает несколько сводных данных, если произведение 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, которая выполняет сводный запрос для создания отчета о количестве сеансов по стране, сгруппированного по измерению браузера.

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

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

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