Method: properties.audienceLists.query

检索用户受众群体名单。创建受众群体后，用户不会立即显示在列表中。首先，需要向 audienceLists.create 发出请求来创建用户受众群体名单；其次，使用此方法检索受众群体名单中的用户。

如需了解受众群体名单的简介和示例，请参阅创建受众群体名单。

利用 Google Analytics 4 中的受众群体功能，您可以根据自身业务需求对用户进行细分。如需了解详情，请访问 https://support.google.com/analytics/answer/9267572。

此方法在 audienceExports.query 中以 Beta 版稳定性提供。如需对此 API 提供反馈，请填写 Google Analytics Audience Export API 反馈表单。

HTTP 请求

POST https://analyticsdata.googleapis.com/v1alpha/{name=properties/*/audienceLists/*}:query

网址采用 gRPC 转码语法。

路径参数

参数
name

string

必需。要从中检索用户的受众群体名单的名称。格式：properties/{property}/audienceLists/{audienceList}

请求正文

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

JSON 表示法 
{
  "offset": string,
  "limit": string
}
字段
offset

string (int64 format)

可选。起始行的行数。第一行计为第 0 行。

分页时，第一个请求不指定偏移量；或者等效地将偏移量设置为 0；第一个请求返回前 limit 行。第二个请求将偏移量设置为第一个请求的 limit；第二个请求返回第二个 limit 行。

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

string (int64 format)

可选。要返回的行数。如果未指定，则返回 10,000 行。无论您请求多少行，该 API 每次请求最多返回 25 万行。limit 必须为正值。

如果维度值的数量少于 limit，API 也可以返回少于所请求 limit 的行。

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

响应正文

受众群体名单中的用户列表。

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

JSON 表示法 
{
  "audienceRows": [
    {
      object (AudienceRow)
    }
  ],
  "audienceList": {
    object (AudienceList)
  },
  "rowCount": integer
}
字段
audienceRows[]

object (AudienceRow)

受众群体名单中每个用户的行。此响应中的行数将小于或等于请求的页面大小。
audienceList

object (AudienceList)

有关所查询 AudienceList 的配置数据。返回以帮助解读此响应中的受众群体行。例如，此 AudienceList 中的维度与 AudienceRows 中的列相对应。
rowCount

integer

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

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

授权范围

需要以下 OAuth 范围之一：

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

AudienceRow

受众群体用户行的维度值属性。

JSON 表示法 
{
  "dimensionValues": [
    {
      object (AudienceDimensionValue)
    }
  ]
}
字段
dimensionValues[]

object (AudienceDimensionValue)

受众群体用户的每个维度值属性。系统会为请求的每个维度列添加一个维度值。

AudienceDimensionValue

维度值。

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "value": string
  // End of mutually exclusive fields.
}
字段
一种维度值。以下是互斥字段的列表。在响应中，最多只能设置一个字段：
value

string

如果维度类型为字符串，则为字符串形式的值。
互斥字段的结束位置。