周期性受众群体名单

本文档介绍了周期性受众群体名单，这是 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 字段中的有效维度列表。如需查看此方法支持的维度列表，请参阅受众群体导出架构文档。 只有此字段中提及的维度的数据才会包含在受众群体名单中。

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

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

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

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

投票配置元数据

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

示例如下：

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

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

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

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

使用网络钩子接收有关新受众群体名单的异步通知

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

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

如需详细了解如何在 Google Analytics（分析）Data API v1 中使用网络钩子，请参阅 WebhookNotification 文档。

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

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

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

如果受众群体导出准备就绪，系统将返回包含受众群体中用户列表的响应：

{
  "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
}