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

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

Как запросить отчет о доступе к данным с помощью клиентской библиотеки

Самый быстрый способ начать работу с отчетами о доступе к данным – использовать клиентские библиотеки.

Инструкции по установке и настройке клиентских библиотек Google Аналитики приведены в кратком руководстве.

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

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

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

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

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

Как создать отчет о доступе к данным

Чтобы запросить отчет о доступе к данным, используйте метод runAccessReport.

Выберите объект отчета

Как и в случае с основными функциями отчетов в Data API версии 1, для метода runAccessReport в Google Analytics Admin API версии 1 требуется указать идентификатор ресурса Google Аналитики в пути запроса URL в формате properties/GA_PROPERTY_ID, например:

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

Отчет о доступе к данным создается на основе записей о доступе к данным Google Аналитики для указанного ресурса Google Аналитики.

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

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

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

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

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

Запросить отчет

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

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

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

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

Прочитайте ответ

Ответ отчета о доступе к данным в основном состоит из заголовка и строк. Заголовок состоит из элементов 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-адрес пользователя.

POST https://analyticsadmin.googleapis.com/v1beta/properties/GA_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 раз.

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

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

Ниже приведены примеры отчетов, которые вы можете попробовать.

Последний доступ

Ниже приведен пример отчета о доступе, который можно создать с помощью runAccessReport.

Чтобы создать этот отчет, запросите параметры mostRecentAccessEpochTimeMicros, userEmail и accessCount показатель. В отчете содержится по одной строке для каждого пользователя. Параметр mostRecentAccessEpochTimeMicros агрегирует записи о доступе к данным для каждого пользователя, у которого есть доступ к ресурсу, и возвращает время последнего доступа (в микросекундах Unix с начала эпохи) для каждой строки.

Доступ пользователей

Другой пример полезного отчета – разбивка доступов пользователей по способу доступа (например, через пользовательский интерфейс Google Аналитики, API и т.д.).

Чтобы создать такой отчет, запросите параметры mostRecentAccessEpochTimeMicros, userEmail, accessMechanism и показатель accessCount.

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

Обзор доступа к ресурсу

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

Чтобы создать такой отчет, запросите параметры accessedPropertyId, accessedPropertyName, accessMechanism и показатель accessCount.

В отчете содержится по одной строке для каждого сочетания идентификатора ресурса и способа доступа.

Доступ к отдельным данным

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

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

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