Method: properties.audienceLists.query

检索用户的受众群体名单。创建受众群体后，系统不会立即将用户列入其中。首先，必须向 audienceLists.create 发出请求才能创建用户受众群体名单，其次，此方法用于检索受众群体名单中的用户。

如需通过示例了解受众群体名单，请参阅创建受众群体名单。

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

此方法在 Beta 版稳定性阶段可通过 audienceExports.query 使用。如需提供您对此 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 请求中包含 limit（50），则响应将包含 rowCount（175），但只有 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 表示法 
{

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

string

如果维度类型为字符串，则值为字符串。