创建受众群体导出

Google Analytics 中的受众群体功能可让您根据自身业务需求对用户进行细分。借助受众群体，您可以根据共同的属性对网站或应用的用户进行分组。

您可以使用 Data API 导出受众群体，包括其用户的快照。

如需详细了解受众群体导出数据中显示的数据，请参阅受众群体导出数据预期指南。

概览

发出以下 Data API 请求，以创建和查询受众群体导出：

  1. 调用 audienceExports.create 方法以创建受众群体导出。
  2. 调用 audienceExports.query 方法可用于检索受众群体中的用户。

如需了解详情，您可以调用 audienceExports.get 来检索有关特定受众群体导出的配置元数据，并调用 audienceExports.list 来列出特定媒体资源的所有受众群体导出。

选择报告实体

所有 Data API 方法都需要在网址请求路径中指定 Google Analytics 媒体资源标识符，格式为 properties/GA_PROPERTY_ID。示例如下：

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports

该报告是根据指定 Google Analytics 媒体资源中收集的 Google Analytics 事件数据生成的。

如果您使用的是 Data API 客户端库，则无需更改请求网址路径。大多数 API 客户端都会提供一个 property 参数，该参数需要 properties/GA_PROPERTY_ID 形式的字符串。如需查看有关如何使用客户端库的示例，请参阅快速入门指南。

创建受众群体导出

如需创建受众群体导出，请在请求中使用 AudienceExport 对象调用 audienceExports.create 方法。以下是必填参数：

  • audience 字段中的有效受众群体名称，格式为 properties/{propertyId}/audiences/{audienceId}。您可以使用 Google Analytics Admin API v1 的 audiences.list 方法来获取此值。audiences.list 响应的 Audience.name 字段包含目标受众群体名称。
  • dimensions 字段中的有效维度列表。如需查看此方法支持的维度的列表，请参阅受众群体导出架构文档。受众群体导出中仅包含此字段中提及的维度的数据。

以下是创建受众群体导出的请求示例：

HTTP 请求

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

audienceExports.create 方法的响应包含 name 字段中的受众群体导出名称，例如 properties/1234567/audienceExports/123。以下是示例响应：

HTTP 响应

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

您可以使用 name 查询从受众群体导出中获取的用户。

查询受众群体导出的准备状态

在调用 audienceExports.create 后，可能需要几分钟时间才能生成受众群体导出。

您可以调用 audienceExports.get 方法来检查受众群体导出的就绪状态。

使用 audienceExports.create 响应中的受众群体导出名称在请求中指定受众群体导出。

以下是请求示例：

HTTP 请求

GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123

受众群体导出的就绪状态会在响应的 state 字段中返回。受众群体导出生成完成后，其状态会从 CREATING 更改为 ACTIVE。

以下是示例响应：

HTTP 响应

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

您可以调用 audienceExports.list 方法来获取所有受众群体导出的状态。

从受众群体导出中检索用户

生成受众群体导出数据后，调用 audienceExports.query 方法，并在请求中指定受众群体导出数据的 name。

以下是请求示例：

HTTP 请求

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

如果受众群体导出已准备就绪，此调用会返回受众群体中的用户列表。

以下是示例响应：

HTTP 响应

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}