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

已请求此媒体资源的数据访问报告。例如，如果“123”是您的 GA4 媒体资源 ID，则实体应为“properties/123”。

请求正文

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

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
}
字段
dimensions[]

object (AccessDimension)

响应中请求和显示的尺寸。最多允许 9 个维度。
metrics[]

object (AccessMetric)

响应中请求和显示的指标。请求最多可以有 10 个指标。
dateRanges[]

object (AccessDateRange)

要读取的访问权限记录的日期范围。如果请求多个日期范围，则每个响应行都将包含一个从零开始的日期范围索引。如果两个日期范围重叠，那么重叠日期范围的访问记录将包含在两个日期范围的响应行中。请求的日期范围不得超过 2 个。
dimensionFilter

object (AccessFilterExpression)

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

object (AccessFilterExpression)

使用指标过滤条件，您可以将报告响应限制为符合过滤条件的特定指标值。与报告 SQL 子句类似，在汇总报告行后，系统会应用指标过滤条件。维度不能用于此过滤条件。
offset

string (int64 format)

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

如需详细了解此分页参数，请参阅分页。
limit

string (int64 format)

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

如果剩余行没有 limit 那么多，则 API 返回的行数可能会少于所请求的 limit。例如，维度 country 的值可能少于 300 个，因此如果仅报告 country，您获取的行数不能超过 300 行，即使您将 limit 设为更高的值也是如此。

如需详细了解此分页参数，请参阅分页。
timeZone

string

此请求的时区（如果已指定）。如果未指定，则使用媒体资源的时区。请求的时区用于解读报告的开始日期和结束日期。

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

object (AccessOrderBy)

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

boolean

切换是否返回此 Google Analytics（分析）媒体资源配额的当前状态。配额在 AccessQuota 中返回。

响应正文

如果成功，响应正文将包含结构如下的数据：

自定义的数据访问记录报告响应。

JSON 表示法 
{
  "dimensionHeaders": [
    {
      object (AccessDimensionHeader)
    }
  ],
  "metricHeaders": [
    {
      object (AccessMetricHeader)
    }
  ],
  "rows": [
    {
      object (AccessRow)
    }
  ],
  "rowCount": integer,
  "quota": {
    object (AccessQuota)
  }
}
字段
dimensionHeaders[]

object (AccessDimensionHeader)

报告中与特定维度对应的列的标题。DimensionHeaders 的数量和 DimensionHeaders 的顺序与行中出现的维度一致。
metricHeaders[]

object (AccessMetricHeader)

报告中与特定指标对应的列的标题。MetricHeaders 的数量和 MetricHeaders 的顺序与行中显示的指标相符。
rows[]

object (AccessRow)

报告中维度值组合和指标值的行。
rowCount

integer

查询结果中的总行数。rowCount 与响应中返回的行数、limit 请求参数和 offset 请求参数无关。例如，如果查询返回 175 行，并且在 API 请求中包含 limit（上限为 50），则响应将包含值为 175 的 rowCount，但只包含 50 行。

如需详细了解此分页参数，请参阅分页。
quota

object (AccessQuota)

此 Google Analytics（分析）媒体资源（包括此请求）的配额状态。

授权范围

需要以下 OAuth 范围之一：

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

访问维度

“维度”是指数据的属性。例如，维度 userEmail 表示访问报告数据的用户的电子邮件地址。报告响应中的维度值是字符串。

JSON 表示法 
{
  "dimensionName": string
}
字段
dimensionName

string

维度的 API 名称。如需查看此 API 支持的维度列表，请参阅数据访问架构。

维度在 dimensionFilter 和 orderBys 中按名称引用。

访问指标

报告的定量测量。例如，指标 accessCount 是数据访问记录的总数。

JSON 表示法 
{
  "metricName": string
}
字段
metricName

string

指标的 API 名称。如需查看此 API 支持的指标列表，请参阅数据访问架构。

指标在 metricFilter 和 orderBys 中按名称引用。

访问日期范围

连续的日期范围：startDate、startDate + 1、...、endDate。

JSON 表示法 
{
  "startDate": string,
  "endDate": string
}
字段
startDate

string

查询的开始开始日期（格式为 YYYY-MM-DD）。不得晚于 endDate。我们也接受 NdaysAgo、yesterday 或 today 格式，在这种情况下，系统会根据请求的时区中的当前时间推断日期。
endDate

string

查询的包含结束日期，格式为 YYYY-MM-DD。不得早于 startDate。我们也接受 NdaysAgo、yesterday 或 today 格式，在这种情况下，系统会根据请求的时区中的当前时间推断日期。

访问过滤条件表达式

表示维度或指标过滤条件。同一表达式中的字段必须是所有维度或所有指标。

JSON 表示法 
{

  // Union field one_expression can be only one of the following:
  "andGroup": {
    object (AccessFilterExpressionList)
  },
  "orGroup": {
    object (AccessFilterExpressionList)
  },
  "notExpression": {
    object (AccessFilterExpression)
  },
  "accessFilter": {
    object (AccessFilter)
  }
  // End of list of possible types for union field one_expression.
}
字段
联合字段 one_expression。为 FilterExpression 指定一种类型的过滤条件表达式。one_expression 只能是下列其中一项：
andGroup

object (AccessFilterExpressionList)

andGroup 中的每个 FilterExpression 都有 AND 关系。
orGroup

object (AccessFilterExpressionList)

orGroup 中的每个 FilterExpression 都有 OR 关系。
notExpression

object (AccessFilterExpression)

FilterExpression 不是 notExpression。
accessFilter

object (AccessFilter)

初始过滤器。在同一 FilterExpression 中，过滤器的所有字段名称都需要是所有维度或所有指标。

AccessFilterExpressionList

过滤条件表达式列表。

JSON 表示法 
{
  "expressions": [
    {
      object (AccessFilterExpression)
    }
  ]
}
字段
expressions[]

object (AccessFilterExpression)

过滤条件表达式列表。

访问权限过滤器

用于过滤维度或指标值的表达式。

JSON 表示法 
{
  "fieldName": string,

  // Union field one_filter can be only one of the following:
  "stringFilter": {
    object (AccessStringFilter)
  },
  "inListFilter": {
    object (AccessInListFilter)
  },
  "numericFilter": {
    object (AccessNumericFilter)
  },
  "betweenFilter": {
    object (AccessBetweenFilter)
  }
  // End of list of possible types for union field one_filter.
}
字段
fieldName

string

维度名称或指标名称。
联合字段 one_filter。为 Filter 指定一种类型的过滤条件。one_filter 只能是下列其中一项：
stringFilter

object (AccessStringFilter)

与字符串相关的过滤条件。
inListFilter

object (AccessInListFilter)

列表值过滤器。
numericFilter

object (AccessNumericFilter)

数值或日期值的过滤条件。
betweenFilter

object (AccessBetweenFilter)

两个值的过滤条件。

AccessStringFilter

字符串过滤器。

JSON 表示法 
{
  "matchType": enum (MatchType),
  "value": string,
  "caseSensitive": boolean
}
字段
matchType

enum (MatchType)

此过滤器的匹配类型。
value

string

用于匹配的字符串值。
caseSensitive

boolean

如果为 true，则字符串值区分大小写。

MatchType

字符串过滤器的匹配类型。

枚举
MATCH_TYPE_UNSPECIFIED 未指定
EXACT 字符串值完全匹配。
BEGINS_WITH 以字符串值开头。
ENDS_WITH 以字符串值结尾。
CONTAINS 包含字符串值。
FULL_REGEXP 正则表达式与字符串值的完全匹配。
PARTIAL_REGEXP 正则表达式与字符串值的部分匹配。

访问权限列表过滤器

结果需要包含在字符串值列表中。

JSON 表示法 
{
  "values": [
    string
  ],
  "caseSensitive": boolean
}
字段
values[]

string

字符串值的列表。不得为空。
caseSensitive

boolean

如果为 true，则字符串值区分大小写。

AccessNumericFilter

数值或日期值的过滤条件。

JSON 表示法 
{
  "operation": enum (Operation),
  "value": {
    object (NumericValue)
  }
}
字段
operation

enum (Operation)

此过滤器的操作类型。
value

object (NumericValue)

数值或日期值。

操作

应用于数字过滤器的操作。

枚举
OPERATION_UNSPECIFIED 未指定。
EQUAL 等于
LESS_THAN 小于
LESS_THAN_OR_EQUAL 小于或等于
GREATER_THAN 大于
GREATER_THAN_OR_EQUAL 大于或等于

NumericValue

用于表示数字。

JSON 表示法 
{

  // Union field one_value can be only one of the following:
  "int64Value": string,
  "doubleValue": number
  // End of list of possible types for union field one_value.
}
字段
联合字段 one_value。数值 one_value 只能是下列其中一项：
int64Value

string (int64 format)

整数值
doubleValue

number

DoubleValue

AccessBetweenFilter

用于表明结果必须介于两个数字（含）之间。

JSON 表示法 
{
  "fromValue": {
    object (NumericValue)
  },
  "toValue": {
    object (NumericValue)
  }
}
字段
fromValue

object (NumericValue)

以此数字开头。
toValue

object (NumericValue)

以此编号结尾。

访问顺序

排序依据定义了响应在行中的排序方式。例如，按访问量降序对行排序就是一种排序，按国家/地区字符串排序行则是一种不同的排序。

JSON 表示法 
{
  "desc": boolean,

  // Union field one_order_by can be only one of the following:
  "metric": {
    object (MetricOrderBy)
  },
  "dimension": {
    object (DimensionOrderBy)
  }
  // End of list of possible types for union field one_order_by.
}
字段
desc

boolean

如果为 true，则按降序排序。如果为 false 或未指定，则按升序排序。
联合字段 one_order_by。为 OrderBy 指定一种类型的订单。one_order_by 只能是下列其中一项：
metric

object (MetricOrderBy)

按指标值对结果进行排序。
dimension

object (DimensionOrderBy)

按维度值对结果进行排序。

指标排序依据

按指标值排序。

JSON 表示法 
{
  "metricName": string
}
字段
metricName

string

请求中排序指标名称。

维度排序依据

按维度值排序。

JSON 表示法 
{
  "dimensionName": string,
  "orderType": enum (OrderType)
}
字段
dimensionName

string

请求中排序所依据的维度名称。
orderType

enum (OrderType)

控制维度值排序规则。

OrderType

按字符串维度值排序的规则。

枚举
ORDER_TYPE_UNSPECIFIED 未指定。
ALPHANUMERIC 按 Unicode 代码点排序的字母数字顺序。例如“2”<“A”<“X”<“b”<“z”。
CASE_INSENSITIVE_ALPHANUMERIC 按小写 Unicode 代码点排序，不区分大小写。例如“2”<“A”<“b”<“X”<“z”。
NUMERIC 在排序之前，维度值会转换为数字。例如，在 NUMERIC 排序中，“25”<“100”；在 ALPHANUMERIC 排序中，“100”< “25”。非数字维度值的所有排序值都低于所有数字值。

访问维度标头

描述报告中的维度列。报告中请求的维度会在行和 DimensionHeaders 内生成列条目。但是，仅在过滤条件或表达式中使用的维度不会在报表中生成列；因此，这些维度不会生成标题。

JSON 表示法 
{
  "dimensionName": string
}
字段
dimensionName

string

维度的名称；例如“userEmail”。

访问指标标头

描述报告中的指标列。报告中请求的可见指标会在行和 MetricHeaders 中生成列条目。不过，过滤条件或表达式中仅使用的指标不会在报表中生成列；因此，这些指标不会生成标题。

JSON 表示法 
{
  "metricName": string
}
字段
metricName

string

指标的名称；例如“accessCount”。

访问权限行

访问每行的报告数据。

JSON 表示法 
{
  "dimensionValues": [
    {
      object (AccessDimensionValue)
    }
  ],
  "metricValues": [
    {
      object (AccessMetricValue)
    }
  ]
}
字段
dimensionValues[]

object (AccessDimensionValue)

维度值列表。这些值的顺序与请求中指定的顺序相同。
metricValues[]

object (AccessMetricValue)

指标值列表。这些值的顺序与请求中指定的顺序相同。

访问维度值

维度的值。

JSON 表示法 
{
  "value": string
}
字段
value

string

维度值。例如，对于“国家/地区”维度，此值可以是“法国”。

访问指标值

指标的值。

JSON 表示法 
{
  "value": string
}
字段
value

string

测量值。例如，此值可以为“13”。

访问配额

此 Google Analytics（分析）媒体资源的所有配额的当前状态。如果某项资源的配额已用尽，则对该属性的所有请求都将返回“资源已用尽”错误。

JSON 表示法 
{
  "tokensPerDay": {
    object (AccessQuotaStatus)
  },
  "tokensPerHour": {
    object (AccessQuotaStatus)
  },
  "concurrentRequests": {
    object (AccessQuotaStatus)
  },
  "serverErrorsPerProjectPerHour": {
    object (AccessQuotaStatus)
  },
  "tokensPerProjectPerHour": {
    object (AccessQuotaStatus)
  }
}
字段
tokensPerDay

object (AccessQuotaStatus)

媒体资源每天可以使用 25 万个令牌。大部分请求消耗的令牌数都少于 10 个。
tokensPerHour

object (AccessQuotaStatus)

媒体资源每小时可以使用 50000 个令牌。API 请求会使用单个数量的令牌，并且此数字将从每小时、每日和每个项目每小时配额中扣除。
concurrentRequests

object (AccessQuotaStatus)

属性最多可以使用 50 个并发请求。
serverErrorsPerProjectPerHour

object (AccessQuotaStatus)

属性和云项目对每小时最多可以出现 50 个服务器错误。
tokensPerProjectPerHour

object (AccessQuotaStatus)

媒体资源每小时最多可以使用每个项目 25% 的令牌。也就是说，Analytics 360 媒体资源每小时每个项目可以使用 12,500 个令牌。API 请求会使用单个数量的令牌，并且此数字将从每小时、每日和每个项目每小时配额中扣除。

访问配额状态

特定配额组的当前状态。

JSON 表示法 
{
  "consumed": integer,
  "remaining": integer
}
字段
consumed

integer

此请求消耗的配额。
remaining

integer

此请求后剩余配额。