周期性受众群体名单

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

定期受众群体名单会每天生成受众群体名单，因为受众群体成员资格会发生变化，以确保您使用的是最新数据。

常规（非定期）受众群体名单是生成名单时受众群体中的用户静态名单。

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

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

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

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

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

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

只有在有额外一天的数据可用时，定期受众群体名单才会生成受众群体名单。这样一来，您就不必猜测何时创建新的受众群体名单。相反，您可以全天以较低的成本轮询定期受众群体名单，以查看是否有额外的数据可用。

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

创建定期受众群体名单

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

  • audience 字段中的有效受众群体名称，格式为 properties/{propertyId}/audiences/{audienceId}。 您可以使用 audiences.list Google Analytics Admin API v1 的方法获取此值。 Audience.name 字段audiences.list包含受众群体名称。
  • 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 指南 。

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

如需检索受众群体导出中的用户，请调用 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
}