周期性受众群体名单

本文档介绍了周期性受众群体名单，这是 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 接收有关新受众群体名单的异步通知

您可以选择在有受众群体名单可用时异步接收 Webhook 通知，而不是使用 recurringAudienceLists.get 方法定期轮询特定周期性受众群体名单的配置元数据。

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

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

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

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

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
}