概览

借助 Google Analytics Admin API v1，您可以使用 runAccessReport 方法。报告会记录用户每次读取 Google Analytics 的情况 报告数据。访问记录最长会保留 2 年。数据访问 只有具备管理员角色的用户才可以访问此类报告。

创建数据访问报告

数据访问报告由 runAccessReport 方法。

核心报告的共同功能

数据访问权限报告请求与核心报告具有相同的语义 请求，从而实现多项共享功能。例如 分页、维度过滤条件、日期范围规范的行为相同 作为核心报告。

请熟悉核心报表功能概览： Google Data API v1 部分， 文档将重点介绍数据访问报告请求所特有的功能。

选择举报实体

类似于“核心报告” 功能 Data API v1、runAccessReport 方法需要 Google Analytics 属性标识符 采用 properties/GA_PROPERTY_ID 格式的网址请求路径，例如：

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

系统会根据 Google Analytics 生成所生成的数据访问报告 指定 Google Analytics 媒体资源的数据访问记录。

如果您使用的是某个 Admin API 客户端库， 因此无需手动处理请求网址路径大多数 API 客户端都会提供一个 property 参数，该参数需要 properties/GA_PROPERTY_ID 形式的字符串。有关代码段，请参见 有关使用客户端库的示例。

维度和指标

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

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

有关维度和 指标名称。

数据访问权限报告请求

要请求数据访问报告，请构建一个 RunAccessReportRequest 对象。周三 建议从以下请求参数开始：

下面是一个包含建议字段的示例请求。此查询会生成 用户电子邮件地址列表，他们最近一次访问指定媒体资源的时间 以及相应的访问计数。

HTTP

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 地址

HTTP

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 次的所有用户。

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 微秒为单位， epoch）。

用户访问权限细分报告

另一个实用报告示例是按访问权限细分用户访问次数 机制（例如 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 metric。

在每个用户/访问机制组合报告中，都会有一行数据。通过 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 metric。

每个媒体资源 ID/访问机制组合在报告中均包含一行。

个人数据访问报告

为了生成每一行都基于个别数据访问权限的报告 记录，请在查询中省略 mostRecentAccessEpochTimeMicros 维度，然后 请改用“epochTimeMicros”维度。无需查询 accessCount指标，因为报告的每一行都包含 发生过一次数据访问。

以下报告包含有关用户每次 访问了指定属性。

Unix 纪元时间（以微秒为单位） 用户电子邮件 访问过的媒体资源 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

此报告可通过 dimensions epochTimeMicros、userEmail、 accessedPropertyId、accessedPropertyName、userIP、accessMechanism、 costDataReturned、revenueDataReturned。

客户端库

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

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

Python

<ph type="x-smartling-placeholder"></ph> google-analytics-admin/properties_run_access_report.py
<ph type="x-smartling-placeholder"></ph> 在 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