此页面由 Cloud Translation API 翻译。

创建受众群体导出

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

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

有关受众群体导出结果数据的重要信息，请参阅受众群体导出数据预期指南。

概览

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

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

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

选择举报实体

所有 Data API 方法都要求在网址请求路径内指定 properties/GA4_PROPERTY_ID 形式的 Google Analytics（分析）4 媒体资源标识符。示例如下：

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

报告是根据在指定 Google Analytics（分析）4 媒体资源中收集的 Google Analytics（分析）事件数据生成的。

如果您使用的是某个 Data API 客户端库，则无需更改请求网址路径。大多数 API 客户端都会提供一个 property 参数，该参数需要 properties/GA4_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
}