此页面由 Cloud Translation API 翻译。

概览

借助 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 对象。周三建议从以下请求参数开始：

在 date 中至少输入一个有效条目范围字段。
在维度字段。
如果未使用“epochTimeMicros”维度，则至少要在该指标字段以接收每个维度值组合的定量数据，报告。

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

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