数据访问权限报告

您可以使用 Admin API v1 的 runAccessReport 方法创建数据访问报告。此报告会显示用户每次读取 Google Analytics 数据的情况。数据访问记录最长可保留 2 年。只有拥有管理员角色的用户才能查看数据访问报告。

使用客户端库请求数据访问报告

若要快速开始使用数据访问报告，最简单的方法是使用客户端库。

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

以下示例使用 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

与核心报告共享的功能

对于许多常见功能，数据访问报告请求的语义与核心报告请求相同。例如，分页、维度过滤条件和日期范围在这两种报告类型中的运作方式相同。

熟悉 Data API v1 中核心报告的概览，然后返回此页面详细了解数据访问报告。

创建数据访问权限报告

使用 runAccessReport 方法请求数据访问报告。

选择报告实体

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

  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 对象。我们建议您先使用以下请求参数：

  • date ranges 字段中至少有一个有效条目。
  • dimensions 字段中至少有一个有效条目。
  • 如果不使用 epochTimeMicros 维度，则 metrics 字段中至少有一个有效条目，用于接收报告中每个维度值组合的定量数据。

以下是包含推荐字段的请求示例。此查询将生成用户电子邮件地址、用户在过去 7 天内最近一次访问指定媒体资源的时间以及相应的访问次数的列表。

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
}

按访问记录过滤

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

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

同样，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 创建：

最近一次访问的 Unix 纪元时间（以微秒为单位） 用户电子邮件地址 访问次数
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 等）对用户访问情况进行细分。

最近一次访问的 Unix 纪元时间（以微秒为单位） 用户电子邮件地址 访问机制 访问次数
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 指标，因为报告中的每一行都包含与单次数据访问情况相关的信息。

以下报告包含有关用户每次访问指定媒体资源的详细信息。

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

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