周期性受众群体名单

本文档介绍了周期性受众群体列表，这是 Google Analytics Data API v1 的一项高级功能。如需了解受众群体名单导出功能，请参阅受众群体导出基础知识指南。

循环受众群体名单每天都会根据受众群体成员的变化生成受众群体名单，以确保您使用的是最新数据。

常规（非周期性）受众群体名单是指在生成名单时受众群体中的用户组成的静态名单。

每天创建新的受众群体名单

处理一天的受众群体数据并更新会员资格所需的时间不确定。无法保证受众群体名单数据会在 24 小时内更新。

例如，即使您每天在同一时间请求受众群体名单，在某些日子，受众群体名单也会与前一天相同；而在其他日子，受众群体名单则会不同，并且会包含额外一天的会员资格变动。

每天创建新的受众群体名单

受众群体名单基于最新会员资格变更前一天的事件数据。如果您在每日会员资格更新发生之前创建受众群体名单，系统将使用前两天的数据。如果您在每日会员资格更新发生后创建受众群体名单，该名单将使用昨天的数据。

定期轮询周期性受众群体名单

只有在有额外一天的数据时，周期性受众群体名单才会生成受众群体名单。这样一来，您就无需再猜测何时创建新的受众群体列表。不过，您可以全天以低成本轮询周期性受众群体列表，以查看是否有更多数据可用。

在一天内定期轮询周期性受众群体名单

创建周期性受众群体名单

如需创建周期性受众群体列表，请在请求中使用 RecurringAudienceList 对象调用 recurringAudienceLists.create 方法。以下是必填参数：

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

以下是一个周期性受众群体名单创建请求示例：

HTTP 请求

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

recurringAudienceLists.create 方法的响应包含 name 字段中的名称（例如 properties/1234567/recurringAudienceLists/123），该名称可用于后续查询，以检索此周期性受众群体列表的配置元数据。此外，配置元数据还包含为此周期性受众群体名单创建的受众群体名单实例的资源名称。

HTTP 响应

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

轮询配置元数据

使用 recurringAudienceLists.get 方法检索有关特定周期性受众群体列表的配置元数据。配置元数据包含为此周期性受众群体名单创建的受众群体名单实例的资源名称。

示例如下：

HTTP 请求

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

响应中会返回 RecurringAudienceList 的实例。它包含配置元数据，其中包括为此周期性受众群体名单创建的受众群体名单实例的资源名称。

HTTP 响应

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

您可以使用 recurringAudienceLists.list 列出相应媒体资源的所有周期性受众群体名单。

使用 Webhook 接收有关新受众群体名单的异步通知

您可以使用 recurringAudienceLists.get 方法定期轮询有关特定周期性受众群体名单的配置元数据，也可以在受众群体名单变为可用状态时异步接收 Webhook 通知。

如需配置 Webhook 通知，请在创建新的周期性受众群体名单时指定 webhookNotification 字段。

如需详细了解如何在 Google Analytics Data API v1 中使用 Webhook，请参阅 Async audience lists with webhooks 指南。

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

如需检索 Audience Export 中的用户，请调用 audienceExports.query 方法，并指定从 recurringAudienceLists.get 或 recurringAudienceLists.list 提供的配置元数据中检索到的 Audience Export 名称。

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
}