概述

作为广告 API v4 的组成部分而随其发布的受众 API 对原受众端点进行了若干改进。这个新端点由新的受众处理后端提供支持，并在稳定性、稳健性和可靠性方面进行了改进。本指南旨在重点说明受众 API 与原受众上传和管理流程之间的差异。

可在受众 API 参考文档页面查看参考文档。

注意：所有受众用户数据在上传前必须经过 SHA-256 哈希处理。可在用户数据页面查看更多详情，以及接受的用户标识符类型和数据规范化。

受众功能的更改

自 v4 起，我们对自定义受众做出了以下变更，在广告 API v3 停用后，所有已弃用端点都将不再可用：

已弃用 TON 上传：
- GET accounts/:account_id/custom_audience_changes
- GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
- POST accounts/:account_id/custom_audience_changes
- PUT accounts/:account_id/custom_audiences/global_opt_out
已弃用实时受众：
- POST custom_audience_memberships
自定义受众：
- list_type 参数将从所有自定义受众端点上的请求和响应中删除。此参数曾用于标识 Audience 的标识符类型（例如，电子邮件、Twitter 用户 ID 等），而 Audiences 现在可接受同一 Audience 的多个用户标识符，因此，该值现已不再相关。
一般功能：
- 受众回看窗口已更新，以匹配过去 90 天内（原为 30 天）活跃的用户
- 定位受众所需的最少匹配用户数量已减少为 100 个用户（原为 500 个用户）

前提条件

广告 API 访问
要访问受众端点，你需要列入允许列表。若初始接受日期早于 2018 年 8 月 1 日，请填写此表格并接受新的 Twitter 广告产品和服务协议

受众上传流程

下表列出了新旧受众创建流程的主要区别，下面提供了更多详细信息：

流程步骤	受众 API	（已弃用）TON 上传
创建 Shell 受众	可通过 POST custom_audience 端点创建	可通过 POST custom_audience 端点创建
添加新用户	将 `operation_type` `Update` 与 Audience 端点结合使用	将 `operation` `ADD` 与 POST custom_audience_changes 端点结合使用
删除用户	将 `operation_type` `Delete` 与 Audience 端点结合使用	将 `operation` `REMOVE` 与 POST custom_audience_changes 端点结合使用
选择退出的用户	将 `operation_type` `Delete` 与 Audience 端点和用户所属的对应 `custom_audience_id` 结合使用	使用 Global opt-out 端点实现

注意，通过 TON 上传路径更新或选择退出的任何受众都必须具有通过 TON 上传端点上传的对应列表，并使用 custom_audience_changes 端点与受众关联。

速率限制

受众 API 端点的速率限制为每个账号 1500/ 分钟。单个有效负荷中可发送的用户数量不存在限制。对有效负荷的唯一限制是：

1.操作总次数：2500 次操作

2.最大有效负荷大小：5,000,000 字节

受众用户管理

要创建新的受众，需要执行以下步骤

创建新的自定义受众

使用 POST custom_audience 端点创建新的自定义受众“Shell”，然后检索对应的自定义受众 id。如果从头开始创建受众，则需要执行此步骤。如果要更新现有受众，请跳到下一部分

将用户添加至受众

使用 POST accounts/:account_id/custom_audiences/:custom_audience_id/users 和自定义受众 id，有效负荷示例如下所示：

POST https://ads-api.twitter.com/6/accounts/18ce54d4x5t/custom_audiences/1nmth/users


# All values must be hashed, unhashed values are used in this example for illustrative purposes
[
  {
    "operation_type": "Update",
    "params": {
      "effective_at": "2018-05-15T00:00:00Z",
      "expires_at": "2019-01-01T07:00:00Z",
      "users": [
        {
          "email": [
            "abc@twitter.com"
          ],
          "handle": [
            "twitter",
            "adsapi"
          ]
        },
        {
          "email": [
            "edf@twitter.com"
          ],
          "twitter_id": [
            "121291606",
            "17874544"
          ]
        }
      ]
    }
  }
]

要将用户添加至受众，请使用 operation_type Update。新的受众界面支持为单个用户输入多个用户键。JSON 对象数组中的每个对象对应一个用户。通过使用上述的有效负荷示例，请求会向受众添加两名用户，一名用户拥有 email和 handle，另一名用户拥有 email 和 twitter_id。

将用户从受众中删除

与上述的添加用户流程相似，可通过以下方法将用户从受众中删除：

POST https://ads-api.twitter.com/6/accounts/18ce54d4x5t/custom_audiences/1nmth/users


# All values must be hashed, unhashed values are used in this example for illustrative purposes
[
  {
    "operation_type": "Delete",
    "params": {
      "effective_at": "2018-05-15T00:00:00Z",
      "expires_at": "2019-01-01T07:00:00Z",
      "users": [
        {
          "email": [
            "abc@twitter.com"
          ],
          "twitter_id": [
            "783214",
            "1225933934"
          ]
        },
        {
          "email": [
            "edf@twitter.com"
          ],
          "twitter_id": [
            "121291606",
            "17874544"
          ]
        }
      ]
    }
  }
]

operation_type 必须设置为 Delete，将基于向受众添加用户时出现的任何键匹配用户。例如，如果用户已被添加到使用 email 和 twitter_id 的受众中，则可以使用这些键中的任意一个删除相同的用户，例如，同时使用 email 和 twitter_id，或选择二者之一。

此外，还可以在同一个请求中对受众中的用户执行添加和删除。端点支持每个请求多个 operation_type。

选择退出的用户

随着全局退出端点的弃用，合作伙伴需要 Delete 已经选择退出任何受众身份的所有用户。可通过以下方法来实现：

跟踪用户的受众所属情况，并将这些用户从每个受众中单独删除。
将用户从与广告账号关联的所有受众中删除。

通用最佳实践

我们强烈建议在准实时批次中调用此端点，以避免出现尖峰队列，尖峰队列的处理时间较长，并且通常会给系统造成不必要的负荷。这也确保了用户可以更快地用于广告活动定位。
成功的 API 调用将返回与请求中收到的 user 对象数量对应的 success_count 和 total_count。
该端点具有原子性，即，要么整个请求成功，要么整个请求因出现任何错误而失败。如果出现错误响应，建议 API 消费者修复错误并重试带有完整有效负荷的请求。
失败时，建议合作伙伴使用指数退避方式重试。例如，第一次失败时立即重试，第二次失败后等待 1 分钟再重试，连续第三次失败后等待 5 分钟再重试，以此类推