Обзор

Google Analytics Admin API v1 позволяет создавать отчеты о доступе к данным с помощью метода runAccessReport . В отчете представлены записи каждый раз, когда пользователь читает данные отчетов Google Analytics. Записи о доступе хранятся до 2 лет. Отчеты о доступе к данным доступны только пользователям с ролью администратора .

Создание отчета о доступе к данным

Отчеты о доступе к данным предоставляются методом runAccessReport .

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

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

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

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

Подобно основной функции отчетности Data API v1, метод runAccessReport Google Analytics Admin API v1 требует, чтобы идентификатор свойства Google Analytics 4 был указан внутри пути запроса URL-адреса в форме properties/GA4_PROPERTY_ID , например:

  POST  https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport

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

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

Размеры и показатели

Размеры описывают и группируют данные доступа к вашему ресурсу. Например, измерение userEmail указывает адрес электронной почты пользователя, который получил доступ к данным отчетов. Значения измерений в ответах отчета представляют собой строки.

Метрики представляют собой количественные измерения отчета. Метрика accessCount возвращает общее количество записей доступа к данным.

Полный список названий параметров и показателей, доступных в запросах отчетов о доступе к данным, см. в схеме доступа к данным .

Запрос отчета о доступе к данным

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

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

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

HTTP

POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "mostRecentAccessEpochTimeMicros"
    },
    {
      "dimensionName": "userEmail"
    }
  ],
  "metrics": [
    {
      "metricName": "accessCount"
    }
  ]
}

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

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

Каждая строка отчета о доступе состоит из AccessDimensionValues ​​и AccessMetricValues ​​для столбцов отчета. Порядок столбцов одинаков в запросе, заголовке и каждой строке.

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

{
  "dimensionHeaders": [
    {
      "dimensionName": "mostRecentAccessEpochTimeMicros"
    },
    {
      "dimensionName": "userEmail"
    }
  ],
  "metricHeaders": [
    {
      "metricName": "accessCount"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "1667591408427733"
        },
        {
          "value": "Bola@example.net"
        }
      ],
      "metricValues": [
        {
          "value": "1238"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1667710959827161"
        },
        {
          "value": "Alex@example.net"
        }
      ],
      "metricValues": [
        {
          "value": "475"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1667868650762743"
        },
        {
          "value": "Mahan@example.net"
        }
      ],
      "metricValues": [
        {
          "value": "96"
        }
      ]
    }
  ],
  "rowCount": 3
}

Фильтрация записей доступа

Используйте поле DimensionFilter объекта RunAccessReportRequest , чтобы ограничить ответ отчета определенными значениями измерения, которые соответствуют фильтру.

В следующем примере создается отчет на основе отдельных записей доступа к данным с фильтрацией записей доступа одного пользователя с адресом электронной почты Alex@example.net . Отчет содержит время каждой записи доступа, адрес электронной почты и IP-адрес пользователя.

HTTP

POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "epochTimeMicros"
    },
    {
      "dimensionName": "userEmail"
    },
    {
      "dimensionName": "userIP"
    }
  ],
  "dimensionFilter": {
    "accessFilter": {
      "fieldName": "userEmail",
      "stringFilter": {
        "matchType": "EXACT",
        "value": "Alex@example.net"
      }
    }
  }
}

Аналогично, поле metricFilter объекта RunAccessReportRequest можно использовать для ограничения ответа отчета определенными значениями метрики, которые соответствуют фильтру.

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

HTTP

{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "userEmail"
    }
  ],
  "metricFilter": {
    "accessFilter": {
      "numericFilter": {
        "operation": "GREATER_THAN",
        "value": {
          "int64Value": 100
        }
      },
      "fieldName": "accessCount"
    }
  },
  "metrics": [
    {
      "metricName": "accessCount"
    }
  ]
}

Примеры отчетов

Вот несколько примеров отчетов, которые вы можете попробовать.

Отчет о последнем доступе по пользователям

Следующий пример отчета о доступе, который можно создать с помощью runAccessReport :

Микросхемы последнего доступа к эпохе времени Электронная почта пользователя Количество доступов
1525220215025371 Бола@example.net 5
1525220215028361 Алекс@example.net 36
1525220215027671 Чарли@example.net 1153
1525220215027341 Махан@example.net 1

Этот отчет можно создать путем запроса измеренийmostRecentAccessEpochTimeMicros userEmail mostRecentAccessEpochTimeMicros метрики accessCount . Отчет содержит одну строку для каждого пользователя: измерение mostRecentAccessEpochTimeMicros объединяет записи доступа к данным для каждого пользователя, обращающегося к свойству, и возвращает время последнего доступа (в микросекундах Unix с момента epoch ) для каждой строки.

Отчет о доступе пользователей

Еще одним примером полезного отчета является разбивка доступа пользователей по механизмам доступа (например, пользовательский интерфейс Google Analytics, API и т. д.).

Микросхемы последнего доступа к эпохе времени Электронная почта пользователя Механизм доступа Количество доступов
1525220215028367 Алекс@example.net Огневая база 31
1525220215555778 Алекс@example.net Пользовательский интерфейс Google Аналитики 1
1525220215022378 Бола@example.net Пользовательский интерфейс Google Аналитики 65
1525220215026389 Бола@example.net API Google Аналитики 894
1525220215025631 Чарли@example.net API Google Аналитики 67
1525220215068325 Махан@example.net Google Реклама 3

Этот отчет можно создать путем запроса измерений mostRecentAccessEpochTimeMicros , userEmail , accessMechanism и метрики accessCount .

Отчет содержит одну строку для каждой комбинации пользователя/механизма доступа. mostRecentAccessEpochTimeMicros содержит информацию о том, когда пользователь в последний раз обращался к свойству с использованием указанного механизма доступа.

Обзорный отчет о доступе к собственности

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

Идентификатор доступного свойства Имя доступного свойства Механизм доступа Количество доступов
12345678 Демо-приложение Огневая база 31
12345678 Демо-приложение Пользовательский интерфейс Google Аналитики 624
12345678 Демо-приложение Google Реклама 83
12345678 Демо-приложение API Google Аналитики 1744 г.

Этот отчет можно создать путем запроса измерений accessedPropertyId , accessedPropertyName , accessMechanism и метрики accessCount .

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

Отчет об индивидуальном доступе к данным

Чтобы создать отчет, в котором каждая строка основана на отдельной записи доступа к данным, опустите mostRecentAccessEpochTimeMicros из запроса и используйте вместо него измерение epochTimeMicros . Нет необходимости запрашивать метрику accessCount , поскольку каждая строка отчета содержит информацию об одном случае доступа к данным.

Следующий отчет содержит подробную информацию о каждом доступе пользователя к указанному свойству.

Эпоха Времени Микрос Электронная почта пользователя Идентификатор доступного свойства Имя доступного свойства IP-адрес пользователя Механизм доступа Данные о затратах возвращены Данные о доходах возвращены
1525220215025371 Бола@example.net 12345678 Демо-приложение 1.2.3.1 Пользовательский интерфейс Google Аналитики истинный истинный
1525220645645645 Махан@example.net 12345678 Демо-приложение 1.2.3.5 Пользовательский интерфейс Google Аналитики ЛОЖЬ ЛОЖЬ
1525220211312322 Бола@example.net 12345678 Демо-приложение 22.11.33.11 Google Реклама истинный ЛОЖЬ
1525220210234221 Алекс@example.net 12345678 Демо-приложение 22.11.33.22 Огневая база ЛОЖЬ ЛОЖЬ
1525220215028368 Алекс@example.net 12345678 Демо-приложение 1.2.3.2 Google Реклама ЛОЖЬ ЛОЖЬ
1525220214234231 Махан@example.net 12345678 Демо-приложение 22.11.33.55 Google Реклама истинный истинный
1525220423423452 Чарли@example.net 12345678 Демо-приложение 1.2.3.3 API Google Аналитики истинный ЛОЖЬ
1525220132312333 Махан@example.net 12345678 Демо-приложение 1.2.3.5 Google Реклама истинный истинный

Этот отчет можно создать путем запроса измерений epochTimeMicros , userEmail , accessedPropertyId , accessedPropertyName , userIP , accessMechanism , costDataReturned , revenueDataReturned .

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

Подробную информацию о том, как установить и настроить клиентские библиотеки , см. в кратком руководстве.

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

Питон

google-analytics-admin/properties_run_access_report.py
Открыть в представлении Cloud Shell на GitHub
from datetime import datetime

from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import (
    AccessDateRange,
    AccessDimension,
    AccessMetric,
    RunAccessReportRequest,
)


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


def run_access_report(property_id: str, transport: str = None):
    """
    Runs an access report for a Google Analytics property. The report will
    aggregate over dimensions `userEmail`, `accessedPropertyId`,
    `reportType`, `revenueDataReturned`, `costDataReturned`,
    `userIP`, and return the access count, as well as the most recent access
    time for each combination.
    See https://developers.google.com/analytics/devguides/config/admin/v1/access-api-schema
    for the description of each field used in a data access report query.
    Args:
        property_id(str): The Google Analytics Property ID.
        transport(str): The transport to use. For example, "grpc"
            or "rest". If set to None, a transport is chosen automatically.
    """
    client = AnalyticsAdminServiceClient(transport=transport)
    request = RunAccessReportRequest(
        entity=f"properties/{property_id}",
        dimensions=[
            AccessDimension(dimension_name="userEmail"),
            AccessDimension(dimension_name="accessedPropertyId"),
            AccessDimension(dimension_name="reportType"),
            AccessDimension(dimension_name="revenueDataReturned"),
            AccessDimension(dimension_name="costDataReturned"),
            AccessDimension(dimension_name="userIP"),
            AccessDimension(dimension_name="mostRecentAccessEpochTimeMicros"),
        ],
        metrics=[AccessMetric(metric_name="accessCount")],
        date_ranges=[AccessDateRange(start_date="yesterday", end_date="today")],
    )

    access_report = client.run_access_report(request)

    print("Result:")
    print_access_report(access_report)


def print_access_report(response):
    """Prints the access report."""
    print(f"{response.row_count} rows received")
    for dimensionHeader in response.dimension_headers:
        print(f"Dimension header name: {dimensionHeader.dimension_name}")
    for metricHeader in response.metric_headers:
        print(f"Metric header name: {metricHeader.metric_name})")

    for rowIdx, row in enumerate(response.rows):
        print(f"\nRow {rowIdx}")
        for i, dimension_value in enumerate(row.dimension_values):
            dimension_name = response.dimension_headers[i].dimension_name
            if dimension_name.endswith("Micros"):
                # Convert microseconds since Unix Epoch to datetime object.
                dimension_value_formatted = datetime.utcfromtimestamp(
                    int(dimension_value.value) / 1000000
                )
            else:
                dimension_value_formatted = dimension_value.value
            print(f"{dimension_name}: {dimension_value_formatted}")

        for i, metric_value in enumerate(row.metric_values):
            metric_name = response.metric_headers[i].metric_name
            print(f"{metric_name}: {metric_value.value}")


properties_run_access_report.py