创建受众群体导出

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

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

如需了解您在受众群体导出内容中看到的数据的重要信息，请参阅受众群体导出数据预期结果指南。

概览

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

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

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

选择报告实体

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

  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
}