Method: properties.runAccessReport

返回数据访问记录的自定义报告。此报告会提供用户每次读取 Google Analytics(分析)报告数据的记录。访问记录最长会保留 2 年。

您可以为媒体资源请求数据访问报告。您可以针对任何媒体资源请求报告,但是与配额无关的维度只能针对 Google Analytics 360 媒体资源请求。此方法仅供管理员使用。

这些数据访问记录包括 GA4 界面报告、GA4 界面探索、GA4 Data API,以及 Firebase 和 AdMob 等其他可通过关联从 Google Analytics(分析)中检索数据的产品。这些记录不包括媒体资源配置更改,例如添加数据流或更改媒体资源的时区。如需了解配置更改历史记录,请参阅 searchChangeHistoryEvents

HTTP 请求

POST https://analyticsadmin.googleapis.com/v1alpha/{entity=properties/*}:runAccessReport

网址采用 gRPC 转码语法。

路径参数

参数
entity

string

数据访问报告支持在媒体资源一级或帐号一级提出请求。如果在帐号一级提出请求,数据访问报告将包含该帐号下所有媒体资源的所有访问权限。

若要在媒体资源一级发出请求,如果您的 GA4 媒体资源 ID 为“123”,则实体类型应为“properties/123”。若要在账号一级请求,实体应为“accounts/1234”(如果您的 GA4 账号 ID 为“1234”)。

请求正文

请求正文中包含结构如下的数据:

JSON 表示法
{
  "dimensions": [
    {
      object (AccessDimension)
    }
  ],
  "metrics": [
    {
      object (AccessMetric)
    }
  ],
  "dateRanges": [
    {
      object (AccessDateRange)
    }
  ],
  "dimensionFilter": {
    object (AccessFilterExpression)
  },
  "metricFilter": {
    object (AccessFilterExpression)
  },
  "offset": string,
  "limit": string,
  "timeZone": string,
  "orderBys": [
    {
      object (AccessOrderBy)
    }
  ],
  "returnEntityQuota": boolean,
  "includeAllUsers": boolean,
  "expandGroups": boolean
}
字段
dimensions[]

object (AccessDimension)

请求并在响应中显示的维度。请求最多包含 9 个维度。

metrics[]

object (AccessMetric)

请求并显示于响应中的指标。最多允许请求 10 个指标。

dateRanges[]

object (AccessDateRange)

要读取的访问记录的日期范围。如果请求了多个日期范围,则每个响应行都会包含一个从零开始的日期范围索引。如果两个日期范围重叠,则重叠日期的访问记录会同时包含在两个日期范围的响应行中。最多允许请求 2 个日期范围。

dimensionFilter

object (AccessFilterExpression)

利用维度过滤条件,您可以将报告响应限制为与该过滤条件匹配的特定维度值。例如,过滤单个用户的访问记录。要了解详情,请参阅维度过滤条件基础知识中的相关示例。此过滤条件中不能使用指标。

metricFilter

object (AccessFilterExpression)

利用指标过滤条件,您可以将报告响应限制为与该过滤条件相匹配的特定指标值。指标过滤条件在聚合报告的行之后应用,类似于 SQL 的 using-clause 子句。维度不能在此过滤条件中使用。

offset

string (int64 format)

起始行的行数。第一行计为第 0 行。如果未指定 offset,系统会将其视为 0。如果 offset 为零,则此方法将返回第一页包含 limit 条目的结果。

如需详细了解此分页参数,请参阅分页

limit

string (int64 format)

要返回的行数。如果未指定,将返回 10,000 行。无论您请求的数量是多少,每个请求最多返回 100,000 行。“limit”必须为正数。

如果剩余行数少于 limit,API 返回的行数可能会少于请求的 limit 行。例如,如果维度“country”的可能值少于 300 个,那么,在仅针对“country”生成报表时,即使您将 limit 设为更高的值,所得到的行数也不能超过 300 行。

如需详细了解此分页参数,请参阅分页

timeZone

string

此请求的时区(如果已指定)。如果未指定,系统将使用媒体资源的时区。此请求的时区用于解读报告的开始日期和结束日期。

格式为 IANA 时区数据库 (https://www.iana.org/time-zones) 中的字符串,例如“America/New_York”或“Asia/Tokyo”。

orderBys[]

object (AccessOrderBy)

指定响应中行的排序方式。

returnEntityQuota

boolean

切换是否返回此 Google Analytics(分析)媒体资源配额的当前状态。配额在 AccessQuota 中返回。对于帐号级请求,此字段必须为 false。

includeAllUsers

boolean

可选。确定在响应中包含是否从未进行过 API 调用的用户。如果为 true,则有权访问指定媒体资源或帐号的所有用户都会包含在响应中,而不管他们是否进行了 API 调用。如果为 false,则仅包含已进行 API 调用的用户。

expandGroups

boolean

可选。决定是否返回用户群组中的用户。此字段仅在 includeAllUsers 设置为 true 时有效。如果为 true,则返回所有有权访问指定媒体资源或帐号的用户。如果为 false,则仅返回具有直接访问权限的用户。

响应正文

如果成功,则响应正文包含一个 RunAccessReportResponse 实例。

授权范围

需要以下 OAuth 范围之一:

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics.edit