此页面由 Cloud Translation API 翻译。

受众群体导出基础知识

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

您可以使用 Google Analytics（分析）Data API v1 生成受众群体导出内容，其中包括受众群体中用户的概况。

创建受众群体导出

Google Analytics（分析）Data API v1 使用异步方法来创建受众群体导出。首先，需要向 audienceExports.create 方法发出请求，才能创建用户的受众群体导出。然后，使用 audienceExports.query 方法检索该受众群体中的用户。

此外，您可以使用 audienceExports.get 检索有关特定受众群体导出内容的配置元数据，并使用 audienceExports.list 列出媒体资源的所有受众群体导出内容。

选择一个举报实体

Data API v1 的所有方法都需要在网址请求路径中以 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"
  }
}

查询受众群体导出就绪状态

调用 audienceExports.create 后，可能需要几分钟才能生成受众群体导出内容。您可以通过调用 audienceExports.get 方法来获取受众群体导出的就绪状态。

使用从 audienceExports.create 响应中收到的受众群体导出名称（例如 properties/1234567/audienceExports/123）来指定受众群体导出。

例如：

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.create 方法创建受众群体导出后，请调用 audienceExports.query 方法并指定受众群体导出名称（例如 properties/1234567/audienceExports/123）。

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
}

受众群体导出数据预期

下一部分针对受众群体导出功能中的用户成员资格设定了预期数据。

数据新鲜度

受众群体导出数据新鲜度是指 Google Analytics（分析）收集事件、处理事件，然后更新受众群体中的用户成员资格所需的时间。如果该整个过程花费 24 小时，那么受众群体导出数据的新鲜度就是 24 小时。如需了解详情，请参阅数据新鲜度。

例如，如果用户完成了首次购买，然后在 7 小时后针对“购买者”受众群体创建了受众群体导出，那么该用户几乎肯定尚未被纳入到“购买者”受众群体导出中。首次购买后的 14 到 38 小时内，该用户很有可能会出现在新的受众群体导出中。

受众群体导出内容属于快照

受众群体导出是受众群体中某个实时快照的用户列表。对于 Google Ads 再营销，Google Analytics（分析）会自动并持续地将受众群体中的用户导出到 Google Ads。相比之下，使用 Data API v1 创建受众群体导出时，您需要创建新的受众群体导出，以查看该受众群体中的最新用户。

系统会根据可用的最新用户成员资格创建受众群体导出。但是，受众群体导出的数据新鲜度可以达到 20 小时，这意味着受众群体导出将基于当前时刻之前 20 小时内的所有事件。

最新的成员资格数据每天更新一次，通常是在媒体资源所在时区的白天时段。也就是说，针对同一受众群体在上午 9 点和上午 11 点执行的受众群体导出可能会返回相同的数据，但如果是下午 3 点，则针对同一受众群体执行的受众群体导出可能会因包含另外一天的数据而有所不同。

受众群体导出到期日期

受众群体导出内容将在 72 小时后过期。新用户每天可能会进入和退出受众群体。如需获取最新的用户快照，您需要每天创建新的受众群体导出。

受众群体导出功能的用户限制

当受众群体或媒体资源的规模超出用户限制时，受众群体导出功能会返回受众群体的代表性样本。这些限制取决于您的媒体资源类型（即标准媒体资源或 360 媒体资源），并且会在每次受众群体导出中单独强制执行。回访用户是所请求受众群体中的用户，被认为用户可能是该受众群体的成员，也可能不是该受众群体的成员。

限制类型	标准媒体资源限制	Analytics 360 媒体资源的限制
回访用户数量上限	200 万	2 亿
考虑最多的用户	1000 万	10 亿

在报告中使用的 ID 一致性

在报告中使用的 ID 决定了如何在报告中删除重复用户。受众群体导出功能不会根据“在报告中使用的 ID”设置而改变。受众群体导出功能始终会依次按照 User-ID 和设备 ID 来识别用户。

这意味着，受众群体报告显示的用户数可以多于受众群体导出功能返回的用户数。例如，如果在报告中使用的 ID 为“基于设备”，并且收集了用户 ID，则报告不会根据用户 ID 删除重复的用户，但受众群体导出功能会根据用户 ID 删除重复的用户。

回填一致性

在 Google Analytics（分析）中创建受众群体并启用 Google Ads 再营销后，Google Analytics（分析）会在 Google Ads 中利用最近添加的成员回填该受众群体。不过，Google Analytics（分析）报告和受众群体导出内容不包含回填的受众群体成员。在为报告和受众群体导出创建受众群体后，用户需要记录事件，才能在该受众群体中显示。

例如，如果用户在 6 月 20 日记录了购买事件，而您在 6 月 21 日创建了“购买者”受众群体，那么您可能需要等到 6 月 22 日，才能在新的受众群体导出中看到该用户。但是，只有当该用户在 6 月 21 日记录了任何事件时，才会出现在受众群体导出中。