概览

借助 Google Analytics（分析）Admin API v1，您可以使用 runAccessReport 方法生成数据访问报告。该报告会提供用户每次读取 Google Analytics（分析）报告数据的记录。访问记录最长会保留 2 年。只有拥有管理员角色的用户才能查看数据访问报告。

创建数据访问报告

数据访问报告由 runAccessReport 方法提供。

包含核心报告的共享功能

对于许多共享功能，数据访问报告请求与核心报告请求具有相同的语义。例如，分页、维度过滤条件和日期范围规范在数据访问报告中的运作方式与核心报告相同。

请熟悉 Data API v1 的核心报告功能概览，因为本文档的其余部分将重点介绍数据访问报告请求特有的功能。

选择举报实体

与 Data API v1 的核心报告功能类似，Google Analytics（分析）Admin API v1 的 runAccessReport 方法要求在网址请求路径中以 properties/GA4_PROPERTY_ID 的形式指定 Google Analytics（分析）4 媒体资源标识符，例如：

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

所生成的数据访问报告将根据指定 Google Analytics（分析）4 媒体资源的 Google Analytics（分析）数据访问记录生成。

如果您使用的是 Admin API 客户端库之一，则无需手动操作请求网址路径。大多数 API 客户端都会提供一个 property 参数，该参数需要 properties/GA4_PROPERTY_ID 形式的字符串。如需查看使用客户端库的示例，请参阅本指南末尾的代码段。

维度和指标

维度描述媒体资源的访问权限数据并对其进行分组。例如，userEmail 维度表示访问报告数据的用户的电子邮件地址。报告响应中的维度值是字符串。

指标表示报告的量化衡量标准。accessCount 指标会返回数据访问记录的总数。

如需查看数据访问报告请求中可用的维度和指标名称的完整列表，请参阅数据访问架构。

数据访问报告请求

如需请求数据访问报告，请构建 RunAccessReportRequest 对象。我们建议从以下请求参数开始：

  • 日期范围字段中至少有一个有效条目。
  • 维度字段中至少有一个有效条目。
  • 如果未使用 epochTimeMicros 维度，请在 metrics 字段中至少添加一个有效条目，以接收报告中每个维度值组合的定量数据。

以下是包含建议字段的示例请求。此查询将生成用户电子邮件地址列表、用户在过去 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
}

过滤访问记录

使用 RunAccessReportRequest 对象的 dimensionFilter 字段将报告响应限制为与该过滤条件相匹配的特定维度值。

以下示例根据各个数据访问记录生成报告，对电子邮件地址为 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"
      }
    }
  }
}

同样，RunAccessReportRequest 对象的 metricFilter 字段可用于将报告响应限制为与该过滤条件相匹配的特定指标值。

以下示例会生成一份报告，其中包含访问指定媒体资源 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 Bola@example.net 5
1525220215028361 Alex@example.net 36
1525220215027671 Charlie@example.net 1153
1525220215027341 Mahan@example.net 1

您可以通过查询维度 mostRecentAccessEpochTimeMicros、userEmail 和 accessCount 指标来生成此报告。该报告的每位用户均包含一行：mostRecentAccessEpochTimeMicros 维度汇总了访问媒体资源的每位用户的数据访问记录，并返回每行的上次访问时间（以自纪元以来的 Unix 微秒数表示）。

用户访问权限细分报告

另一个实用报告的例子是按访问机制（例如 Google Analytics（分析）界面、API 等）细分用户访问。

最近访问纪元时间（以微秒为单位） 用户电子邮件 访问机制 访问计数
1525220215028367 Alex@example.net Firebase 31
1525220215555778 Alex@example.net Google Analytics（分析）界面 1
1525220215022378 Bola@example.net Google Analytics（分析）界面 65
1525220215026389 Bola@example.net Google Analytics（分析）API 894
1525220215025631 Charlie@example.net Google Analytics（分析）API 67
1525220215068325 Mahan@example.net Google Ads 3

您可以通过查询维度 mostRecentAccessEpochTimeMicros、userEmail、accessMechanism 和 accessCount 指标来生成此报告。

针对每个用户/访问权限机制组合，报告会占用一行。mostRecentAccessEpochTimeMicros 维度包含用户上次使用指定访问机制访问媒体资源的时间。

“媒体资源访问权限概览”报告

您可以针对媒体资源生成报告，而无需细分单个用户。例如，以下报告说明了使用不同的访问机制访问媒体资源的频率：

已访问媒体资源 ID 所访问的媒体资源名称 访问机制 访问计数
12345678 DemoApp Firebase 31
12345678 DemoApp Google Analytics（分析）界面 624
12345678 DemoApp Google Ads 83
12345678 DemoApp Google Analytics（分析）API 1744

您可以通过查询维度 accessedPropertyId、accessedPropertyName、accessMechanism 和 accessCount 指标来生成此报告。

针对每种媒体资源 ID/访问权限机制组合，报告会分行显示一行。

个别数据访问报告

若要生成每一行都基于单独的数据访问记录的报告，请从查询中省略 mostRecentAccessEpochTimeMicros 维度，并改用 epochTimeMicros 维度。您无需查询 accessCount 指标，因为报告的每一行都包含与单个数据访问事件相关的信息。

以下报告包含有关用户每次访问指定属性的详细信息。

新纪元时间（以微秒为单位） 用户电子邮件 已访问媒体资源 ID 所访问的媒体资源名称 用户 IP 访问机制 返回的费用数据 返回的收入数据
1525220215025371 Bola@example.net 12345678 DemoApp 1.2.3.1 Google Analytics（分析）界面 true true
1525220645645645 Mahan@example.net 12345678 DemoApp 1.2.3.5 Google Analytics（分析）界面 false false
1525220211312322 Bola@example.net 12345678 DemoApp 11.22.33.11 Google Ads true false
1525220210234221 Alex@example.net 12345678 DemoApp 11.22.33.22 Firebase false false
1525220215028368 Alex@example.net 12345678 DemoApp 1.2.3.2 Google Ads false false
1525220214234231 Mahan@example.net 12345678 DemoApp 11.22.33.55 Google Ads true true
1525220423423452 Charlie@example.net 12345678 DemoApp 1.2.3.3 Google Analytics（分析）API true false
1525220132312333 Mahan@example.net 12345678 DemoApp 1.2.3.5 Google Ads true true

您可以通过查询维度（epochTimeMicros、userEmail、accessedPropertyId、accessedPropertyName、userIP、accessMechanism、costDataReturned、revenueDataReturned）来生成报告。

客户端库

如需了解如何安装和配置客户端库，请参阅快速入门指南。

以下示例使用 Python 客户端库运行数据访问查询并输出响应。

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