受众 - X

自定义受众群体

概述

合作伙伴可以通过多种方式创建自定义受众。

Audience API（CRM）
网页
移动端
灵活受众

请注意，无法在投放定向中排除相似受众。此外，也不能在同一广告项目（广告组）中同时定向自定义受众及其相似受众。 受众管理 受众可通过受众合作伙伴和 Ads API 合作伙伴进行管理。我们在 API 中提供了一系列端点，用于访问和维护自定义受众。关于自定义受众信息，我们提供 2 个端点：

有关如何上传和管理受众的更多信息，请参阅 Audience API 指南。 处理时间 通常情况下，受众更改以批处理方式运行，每 6–8 小时执行一次。在处理受众更改期间，待更新的现有受众本身不受影响。我们不建议在该时间窗口内对同一受众进行超过一次的新增更新和一次的移除更新。定向仅当某受众匹配到过去 90 天内在 X 自有及运营客户端上活跃的至少 100 名用户时，才能进行定向。GET accounts/:account_id/custom_audiences/:custom_audience_id 将指示某受众是否因匹配用户过少而无法被定向。 Audience API（CRM）

受众或 API 合作伙伴提供一组经哈希处理的标识符，X 进行匹配并生成可用于在 X 上进行媒体购买的分段。合作伙伴可以使用 Audience API 创建这些受众。 工作原理

网页当与 MPP 受众合作伙伴协作时，我们提供标准的 Cookie 匹配流程，以识别可用于在 X 上进行媒体购买的分段。此外，广告主可以设置 X Web Event Tag 来收集网站用户数据并创建相应的自定义受众。 设置步骤

工作原理

移动端 详情请参阅来自移动应用的自定义受众博文。 灵活受众 灵活受众使广告主能够基于现有自定义受众或其子集构建并保存受众组合。可根据互动的新近度和频率，定向自定义受众成员的子集。 自定义受众的受限使用情形 阅读更多限制说明

受众常见问题解答

问：我们推送了大量数据，为什么受众规模显示为 TOO_SMALL？ 答：目前数据会实时添加到受众中，但用于计算受众规模的处理作业会在一段时间后才运行。正确的受众规模应在数小时后显示在 UI 中。 问：我们已完成发送受众数据，并等待了 24 小时或更久，但仍无法定向该受众——下一步该怎么做？ 答：请确认以下事项：

传递的用户 ID 是否正确且未格式错误。
传递的受众名称是否正确，并与之前的成员更新一致。
请确认 POST 命令的响应。
请确认已正确实施 ID Sync 像素，并且按照 ID Sync 流程，已有足够用户访问相关站点以完成用户映射。成员更新中未映射的用户不会转换为可定向用户。

如果以上均已确认无误，请联系 X 产品对接人，并尽可能提供详尽信息（参见合作方来件指南作为首选信息示例）。 问：我们可以调用该端点多少次，以及应使用什么算法？ 答：我们强烈建议以增量差异的方式调用我们的系统，切勿重新发送完整的受众成员列表。系统经过测试，具备处理全球大型网站增量数据更新的吞吐能力。受众的初始上传应谨慎限速，首次上传预计需要较长时间完成。 问：用于定向的受众最小规模是多少？

受众的最小规模为 100 名用户（匹配后）。如果匹配的受众少于 500 名用户，则不会在 X Ads UI 中提供用于定向。

问：处理受众文件需要多长时间？受众文件在 X 用户界面中可用需要多久？

通常处理受众文件需要 4-6 小时，但这取决于文件大小。文件处理完成后，受众会在 X Ads UI 中可用。

问：匹配率如何计算？

匹配率 = 90 天内活跃的 X 用户数 / 提供的用户数量

问：如何测试受众文件是否正常工作？

你可以提供一个测试受众文件，并使用“keltonlynn”作为广告主 handle。我们随后可以验证该文件是否能够被正确摄取并加载到 X UI 中。

问：什么是合作方用户标识符（p_user_id）？

这是你公司用于唯一识别每位客户的标识符。

问：什么是标准 ID？

可以是电子邮件地址、设备 ID、X @handle 或 ID。

问：如何获取 HMAC 密钥？

我们将通过加密电子邮件提供。请将你的 PGP 公钥发送至mpp-inquiry@x.com，我们会先发送测试邮件以验证一切正常。验证通过后，我们会发送 HMAC 密钥。

问：如何使用给定的 HMAC 密钥验证哈希过程是否生效？

X 将提供一个测试文件（包含示例电子邮件地址、设备 ID 等）以及相应的哈希结果文件，供你对照验证结果。

问：完整数据匹配文件是否有大小限制？

没有，完整数据匹配文件没有大小限制。

问：处理完整数据匹配文件需要多长时间？

X 接收文件后，处理大约需要 1 天时间。

CRM

本文档介绍了面向自定义受众（Custom Audiences）的 CRM 合作伙伴的集成细节，包括文件格式与数据交换流程。摘要 Company 将代表客户向 X 提交一份经哈希处理的常见用户标识符列表（如电子邮件地址）或合作伙伴用户 ID，用于执行盲匹配并生成用于定向的 X 用户 ID 列表。用于定向的细分受众将提供给在 ads.x.com 广告系列设置中由文件名指定的、属于该广告主的特定 @handle。 Company 的所有文件将通过 X 为 Company 授予的专用账户，以 IronBox（www.golockbox.com, http://www.golockbox.com）上的加密安全包形式安全传输给 X。X 将提供 IronBox 的访问权限。有关 IronBox API 的文档可在 https://secure.goironcloud.com/Docs/Help/ 查阅。

合作伙伴 ID 匹配要求

如果公司使用自己的标准 ID 系统来跟踪用户(即不使用常见的用户标识符,如电子邮件地址、设备 ID、X 用户 ID 等),则建议采用以下流程。 1. 完整数据匹配 首先,公司需要提供一份包含所有用户记录的完整列表,其中包括与 X 通用的唯一用户标识符,以单个文件的形式执行完整数据匹配,并生成由 X 存储的合作伙伴 ID(p_user_id)到 X ID(tw_id)的映射关系。此操作将每 2-3 个月定期执行一次,以确保数据的准确性。匹配完成后,X 将通过电子邮件向公司提供此文件的基准匹配率。此文件的格式应为: 命名规范:FullDataMatch.[CompanyName].txt 哈希算法:HMAC_SHA-256 格式: 第 1 列:通用标识符的 HMAC 哈希值第 2 列:合作伙伴用户 ID(每个用户唯一,但在文件中可重复) 列分隔符(CSV):使用逗号分隔哈希后的通用用户标识符和合作伙伴 ID 行分隔值

例如:如果用户记录 A 的合作伙伴用户 ID 为 1,通用标识符为 1、2 和 3:


通用用户标识符 1	p_user_1
通用用户标识符 2	p_user_1
通用用户标识符 3	p_user_1

*请参阅下方的通用用户标识符哈希说明部分 2. 自定义细分列表 公司将以 p_user_id 的形式提供用户列表,用于为客户创建自定义受众,以便在 X 上进行定向投放。

行分隔值
p_user_id
- (与上述 1. 完整数据匹配部分中提供的相同。如果完整数据匹配中提供的值已进行哈希处理,则公司需在受众文件中提供相同的哈希值。如果提供的值未进行哈希处理,则公司需提供未哈希的值。)

标准匹配要求

如果公司未使用标准 ID 来映射所有客户的用户标识符，建议采用以下流程。 自定义分段列表 公司将代表客户直接向 X 提供经过哈希处理的常见用户标识符列表，用于创建自定义受众。文件格式应为：

按行分隔的值
已哈希的常见用户标识符（例如电子邮件地址）
遵循下文列出的文件命名约定
按照下文“哈希指引”中关于电子邮件地址的哈希处理说明进行操作

自定义细分列表文件命名与操作

文件的具体操作由其文件名决定。支持的操作及通用命名规范如下：audiencename_partnername.handle.operation.filetype

audiencename：自定义受众名称。该字段是在 ads.x.com 广告系列设置界面选择受众时显示的名称，例如 brand_loyalty_card_holders。
partnername：代表广告主提交数据的公司名称，例如 company_name。
handle：拥有自定义受众访问权限的 X 账号（@handle），例如 @pepsi、@dietpepsi
operation：new、add、remove、removeall、replace（详见下文）
：标准 Unix 纪元时间（单位：秒），用于确保每个上传的受众文件唯一
filetype：文件须为 *.txt 格式

创建和更新受众

使用单个文件创建新受众，例如：loyalty_card_holders_partnername.pepsi.new.txt Add - 将列表中的匹配结果添加到现有受众，例如：loyalty_card_holders_partnername.pepsi.add..txt Remove - 从现有受众中移除列表中的匹配结果，例如：loyalty_card_holders_partnername.pepsi.remove..txt Remove All - 从该客户的所有受众中移除由定期更新的累积列表生成的匹配结果（即客户的选择退出列表）。例如：partnername.pepsi.removeall.txt

可用于维护广告主的全面“已选择退出”用户列表。
X 仅以此文件中提供的最新列表为准，并将对所有现有和未来受众中的匹配结果生效。

指在提供并处理此文件时匹配到的 X 用户。 Replace - 删除一个现有受众并以新的受众列表替换。例如：loyalty_card_holders_partnername.pepsi.replace..txt 公司整体选择退出 - 公司将提供一个累积的选择退出文件，用于移除根据公司选择退出政策已选择退出的用户。 X 仅以该公司选择退出文件中提供的最新列表为准，并将在所有现有和未来受众中对在提供并处理此文件时匹配到的 X 用户生效。公司选择退出文件的格式如下：例如：partnername.removeall.txt Delete - 从当前受众列表中删除一个现有受众，例如：loyalty_card_holders_partnername.pepsi.delete.txt

哈希说明

X 将通过 PGP 安全地共享一个经 base64 编码的生产密钥，用于对常见用户标识符（如电子邮箱地址）进行哈希。Company 将对该密钥进行 base64 解码，得到一个 32 字节的密钥，用于执行哈希。示例（base64 编码的密钥）： BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= 示例（Base64 解码后的密钥）： /:� TшY 规范化：在进行哈希之前，Company 将对常见用户标识符进行基础规范化（设备 ID 除外，参见“设备 ID 规范化”章节）。

电子邮件规范化

即去除首尾空格，并将电子邮件地址转换为小写。例：原始电子邮件地址：testemail_Organisational_baseball+884@It92I6Ev2B.Com 规范化后：testemail_organisational_baseball+884@it92i6ev2b.com 哈希值：74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec 注意：编码后的 HMAC 和密钥的字符数可能会因输入和编码而异，因此字符数并不固定。

设备 ID 规范化

我们对设备 ID 的哈希有相同要求：使用 SHA-256 哈希算法和我们提供给数据合作伙伴的通用盐值。我们会像处理电子邮件地址一样移除空格，但对 IDFA/Android ID 不做小写化处理，应按其原始格式使用 IDFA/Android ID。以下是 iOS 和 Android 在哈希前的设备 ID 原始格式示例： iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 Android ID: b5bf2122961b3595 哈希后的 iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b 哈希后的 Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

X 用户 ID 规范化

尽管这类数据分组（例如由 @handles 组成的 Customer List）不属于 PII，但对广告主而言仍是私有信息，因此 X ID 依然需要进行哈希处理。对 X ID 的哈希要求一致：使用 SHA-256 哈希算法，并使用我们提供给数据合作伙伴的通用盐值。应从 X ID/@username 中去除空格，但 User ID 无需规范化。为进行规范化，应将 @username 转为小写，且用户名中不应包含 @ 符号。原始 ID 格式为：

User ID: 27674040
@username: testusername

哈希后的 User ID：bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85 哈希后的 @username：12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

ID 同步集成

通过 p_id 发送数据的合作伙伴必须完成 ID 同步流程，以生成广告主或合作伙伴的用户 id 与 X 用户 id 的映射。这使广告主能够在 X 上直接定向触达其自有用户分群。合作伙伴在发送成员更新时还必须将参数 user_identifier_type 的值设置为 TALIST_PARTNER_USER_ID 或 TAWEB_PARTNER_USER_ID。

仅限 Web：可按照下文说明，在广告主网站上部署像素即可完成。
列表：可使用 CRM 页面中所述的任一方法完成。

像素 URL


基础 URL
https://analytics.x.com/i/adsct

像素参数


参数	说明
`p_id`	X 分配给你的合作方 id
`p_user_id`	该用户在合作方系统中的 id

ID 同步像素：

以合作伙伴示例 id 为 111、示例 p_user_id 为 abc 为例，构造的像素如下所示：

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

选择退出文件的配置与发送 合作伙伴应向 X 提供一份用户列表；据合作伙伴所知，这些用户已选择不接收定向广告投放。文件应按以下格式发送：


列号	列名	列类型	说明
1	Partner ID	string	“partner id” 是 X 提供给合作伙伴、用于唯一标识每个合作伙伴的 ID。
2	The user’s id in the partner system	string	`p_user_id` 是合作伙伴用于识别用户的唯一 ID。包含这些选择退出用户的文件应通过 TON upload 端点上传，已上传数据的路径应发送至 Global Opt Out 端点： PUT accounts/:account_id/custom_audiences/global_opt_out。

发送成员更新 如我们的端点文档所述，通过 POST custom_audience_memberships 端点传递用户时，应传递一个客户 ID，以启用基于 Cookie 的匹配。使用 p_id 发送数据的合作伙伴必须将 user_identifier_type 设置为 TALIST_PARTNER_USER_ID 或 TAWEB_PARTNER_USER_ID。其他步骤与实时 Audience API 集成指南中列出的步骤保持一致。

自定义受众用户数据

本文档说明了 [Custom Audience]/x-ads-api/audiences 用户数据的格式。 数据标准化 设备 ID：

IDFA：小写并带连字符；例如：4b61639e-47cc-4056-a16a-c8217e029462
AdID：需采用设备上的原始格式，不要全部大写，保留连字符；例如：2f5f5391-3e45-4d02-b645-4575a08f86e
Android id：需采用设备上的原始格式，不要全部大写，且不含连字符或空格；例如：af3802a465767e36

电子邮件地址：

使用小写，去除首尾空格；例如：support@x.com

X 用户名：

不含 @，小写并去除首尾空格；例如：jack

X 用户 ID：

标准整数；例如：143567

数据哈希 每行数据必须使用 SHA256 进行哈希，且不使用盐。此外，最终输出的哈希必须为小写。例如：49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d，而非 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

# 使用 Python 对用户 @AdsAPI 进行哈希处理
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

# 输出
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

可在 github.com/xdevplatform/ads-platform-tools 找到更多哈希相关的代码示例。

自定义受众：网页

信息合作伙伴将代表广告主发送一个用于定向的 ID 列表（p_user_ids）。这通过 ID 同步流程实现，该流程在 p_user_ids 与 X 用户 ID 之间建立映射。此映射随后用于生成可用于定向的 X 用户 ID 列表。这些自定义受众将依据 ads.x.com 上 Custom Audiences Web 广告系列设置中的标签，在广告主的特定 @handle 下可用。 X 将提供可安全部署在合作伙伴标签和站点上的像素，用于将这些 ID（p_user_ids）与 X 用户 ID 匹配。ID 同步流程完成后，合作伙伴将创建定向文件，并通过一个 HTTPS 端点提供给 X。X 会定期摄取这些定向文件，并在 X 的 UI 中提供。 X 安全像素 X 安全像素如下所示： https://analytics.x.com/i/adsct?p_user_id=xyz&p_id=123 p_user_id - xyz 表示由合作伙伴提供的合作伙伴用户 ID p_id - 123 表示该合作伙伴的唯一 ID（由 X 提供） 合作伙伴 HTTPS 端点与定向用户文件 合作伙伴需要向 X 提供一个 HTTPS 端点和凭据（用户名/密码），以便定期摄取定向文件。示例 HTTPS 端点如下所示：

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

%Y - 年份格式代码（YYYY） %M - 月份格式代码（MM） %D - 日期格式代码（DD）传输的 data 将包含以下文件：

合作伙伴定向用户文件
定向转化文件

所有文件均为 TSV 格式，其中每一行中的各个 fields 以制表符分隔。有效的字段值本身绝不会包含制表符。 允许的 X IP 范围： 以下是可开放访问 Partner Endpoint 的 IP 段。

199.16.156.0/22
199.59.148.0/22

合作伙伴定向用户文件：

列号	列名	列类型	描述
1	partner id	string	“partner id” 是 X 提供给合作伙伴、用于唯一标识每个合作伙伴的 ID。
2	advertiser id	string	“advertiser id” 是该广告主的 @handle。
3	p_user_id	string	“p_user_id” 是合作伙伴用于标识用户的唯一 ID。
3	confidence score	integer	“confidence score”为可选。我们建议的取值范围为 0–100。若用例为再营销，则 “100” 表示被直接再营销的用户；0–99 的任意分值表示对相似受众的置信程度。
4	segment label	string	“segment label”为可选。合作伙伴可使用 “segment label” 指定产品类别等。我们建议使用此 “segment label”，因为它是在 ads.x.com 界面中自定义受众的人类可读名称。

备注： 每次我们收到新的合作伙伴定向文件时，除非另有约定，我们期望这是合作伙伴建议我们投放的完整用户列表，而非增量更新。我们将与每位合作伙伴就该定向文件的投递频率达成一致。如果未按预期收到该文件，我们将使用上一版本，并设置预定义的到期时间。

Audience API 集成

概览

Audience API 作为 Ads API 的第 v4 版的一部分推出，相较于旧版 Audiences 端点带来了多项改进。该新端点由全新的 Audience 处理后端提供支持，并在稳定性、健壮性与可靠性方面显著提升。本指南旨在突出 Audience API 与旧版 Audience 上传和管理流程之间的差异。参考文档请参见 Audience API 参考页面。注意：所有 Audience 用户数据在上传前必须进行 SHA-256 哈希处理。更多详情，以及可接受的用户标识符类型与数据规范化说明，请参见用户数据页面。 Audience 功能变更 自 v4 起对 Custom Audiences 引入以下变更；一旦 Ads 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
已弃用 实时 Audiences：
- POST custom_audience_memberships
Custom Audience：
- 所有 Custom Audience 端点的请求与响应中将移除 list_type 参数。该参数此前用于标识 Audience 的用户标识符类型（如 email、X User ID 等），但现在 Audiences 支持同一 Audience 接受多个用户标识符，因此该值已不再适用。
通用：
- Audience 回溯窗口更新为匹配过去 90 天内活跃的用户（原为 30 天）
- 可投放定向的受众所需的最低匹配用户数从 500 降至 100

先决条件

具备 Ads API 访问权限
如需访问 Audience 端点，您需要被加入允许列表。请填写此表单；若您最初接受日期早于 2018-08-01，请接受新的 X Ads Products and Services Agreement

Audience 上传流程 下表列出旧版与新版 Audience 创建流程的主要差异，更多细节见下文：

流程步骤	Audience API	（已弃用）TON 上传
创建空壳 Audience	可通过 POST custom_audience endpoint 创建	可通过 POST custom_audience endpoint 创建
新增用户	在 Audience endpoint 中使用 `operation_type` `Update`	在 POST custom_audience_changes 端点中使用 `operation` `ADD`
移除用户	在 Audience endpoint 中使用 `operation_type` `Delete`	在 POST custom_audience_changes 端点中使用 `operation` `REMOVE`
用户选择退出	在 Audience endpoint 中使用 `operation_type` `Delete`，并提供该用户所属的相应 `custom_audience_id`	使用 Global opt-out endpoint

注意：通过 TON 上传路径进行更新或选择退出的任何受众，必须已通过 TON Upload 端点上传相应列表，并使用 custom_audience_changes 端点将其关联到某个 Audience。 速率限制 Audience API 端点的速率限制为每个账户 1500/1 分钟。单个有效负载中可发送的用户数量不设上限。对有效负载的唯一约束如下：

操作总数：2500 个操作
最大有效负载大小：5,000,000 字节

Audience 用户管理 要创建新的 Audience，需要完成以下步骤

创建新的自定义受众

使用 [POST custom_audience]/x-ads-api/audiences 端点创建一个新的自定义受众“壳”（shell），并获取相应的自定义受众 id。如果要从头创建受众，此步骤是必需的。若要更新现有受众，请跳至下一节

将用户添加到受众

使用 POST accounts/:account_id/custom_audiences/:custom_audience_id/users，并提供自定义受众的 id 以及如下示例载荷： POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # 所有值都必须经过哈希处理,此示例中使用的未哈希值仅用于演示目的
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

要将用户添加到 Audience，请将 operation_type 设为 Update。新的 Audience 接口允许为同一用户传入多个用户键。JSON 对象数组中的每个对象对应一个用户。以上示例负载中，请求会向 Audience 添加两名用户：一名包含 email 和 handle，另一名包含 email 和 twitter_id。

从受众中移除用户

与添加用户的流程类似，可以按如下方式将用户从受众中移除： POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # 所有值都必须经过哈希处理,此示例中使用的未哈希值仅用于演示目的
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

operation_type 必须设置为 Delete，并且系统会根据将用户添加到受众时提供的任意键来匹配用户。举例来说，如果某个用户是通过 email 和 twitter_id 添加到受众的，那么可以用其中任一键将该用户移除，即使用 email 或 twitter_id，或同时使用二者。此外，可以在同一个请求中同时向 Audience 添加和移除用户。该端点在一次请求中支持多个 operation_type。

选择退出的用户

随着全局选择退出端点被弃用，合作伙伴需要对已从任意受众选择退出的用户执行 Delete 操作。可通过以下方式实现：

记录每位用户所属的受众，并从各自的受众中逐一移除这些用户。
将该用户从与某个 Ads 账户关联的所有受众中移除。

通用最佳实践

我们强烈建议以准实时的批量方式调用此端点，避免出现处理时间较长的突发队列，从而减少对系统的不必要负载。这也能让用户更快可用于广告系列定向。
成功的 API 调用将返回 success_count 和 total_count，它们与请求中接收的 user 对象数量相对应。
此端点具备原子性：要么整个请求成功，要么在出现任何错误时整体失败。若返回错误响应，建议 API 使用方修复错误后，使用完整负载重试该请求。
发生失败时，建议合作伙伴采用带重试的指数退避策略。例如：首次失败后立即重试；第二次失败后 1 分钟再试；第三次连续失败后 5 分钟再试；以此类推。

API 参考

关键词洞察

GET insights/keywords/search

给定一组关键词，获取其关联的 Tweet 数量以及最多 30 个相关关键词。Tweet 数量仅对应输入的关键词，不包含相关关键词。允许的最大时间范围（end_time - start_time）为 7 天。请注意，结果限定在单一地区（国家）。 Resource URL https://ads-api.x.com/12/insights/keywords/search Parameters

Name	Description
granularity required	指定由 `start_time` 和 `end_time` 表示的时间范围内返回数据的粒度。例如，当设置为 `HOUR` 时，系统会在 `start_time` 与 `end_time` 之间的每个小时提供一个数据点。 Type: enum Possible values: `DAY`, `HOUR`
keywords required	以逗号分隔的关键词字符串，用于缩小搜索范围。所有关键词之间采用 OR 逻辑。 Note: 最多可使用 10 个关键词（`keywords` 与 `negative_keywords` 合计）。 Type: string Example: `developers`
start_time required	将检索到的数据限定为在 `start_time` 与 `end_time` 之间的时间窗口内收集的数据。采用 ISO 8601 格式表示。 Type: string Example: `2017-07-10T00:00:00Z`
end_time optional	将检索到的数据限定为在 `start_time` 与 `end_time` 之间的时间窗口内收集的数据。采用 ISO 8601 格式表示。 Note: 默认为当前时间。 Type: string Example: `2017-07-11T00:00:00Z`
location optional	可从 GET targeting_criteria/locations 端点获取一个定向值，以根据账户用户所在的位置收窄结果范围。请注意，目前仅支持国家级位置。 Type: string Example: `0ce8b9a7b2742f7e`
negative_keywords optional	以逗号分隔的关键词字符串，用于排除。所有否定关键词之间采用 OR 逻辑。 Note: 最多可使用 10 个关键词（`keywords` 与 `negative_keywords` 合计）。 Type: string Example: `rain`

Example Request

GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

示例响应*

    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "developers"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "developer",
          "coders",
          "mysql",
          "devs",
          "#technology",
          "#developers",
          "security",
          "programmers",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "developer",
          "programmer",
          "engineer",
          "big data",
          "agile",
          "app",
          "programming",
          "ios",
          "maker",
          "startups",
          "developer's",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }

定向受众权限

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

获取指定定制受众相关的部分或全部权限详情。 Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	正在使用的账户标识符。出现在资源路径中，通常是除 GET accounts 以外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
tailored_audience_id required	本次请求中你要操作的定制受众的引用。 Type: string Example: `1nmth`
count optional	指定每个请求尝试检索的记录数量。 Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string Example: `8x7v00oow`
granted_account_ids optional	通过提供以逗号分隔的标识符列表，将响应限定为所需的账户。最多可提供 200 个 ID。 Type: string Example: `18ce54aymz3`
sort_by optional	按受支持的属性进行升序或降序排序。更多信息参见 Sorting。 Type: string Example: `created_at-asc`
tailored_audience_permission_ids optional	通过提供以逗号分隔的标识符列表，将响应限定为所需的定制受众权限。最多可提供 200 个 ID。 Type: string Example: `ri`
with_total_count optional	是否包含 `total_count` 响应属性。 Note: 此参数与 `cursor` 互斥。 Note: 包含 `total_count` 的请求具有更低的速率限制，目前为每 15 分钟 200 次。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "tailored_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

创建一个新的权限对象，允许将指定受众与给定账户共享。注意：创建或修改定向受众权限时，必须由拥有该受众的账户发起。你可以在该受众的响应中查看 is_owner 属性以确认所有权。注意：受众仅可在同一业务下的广告账户之间共享；若受众所属的广告账户启用了 SHARE_AUDIENCE_OUTSIDE_BUSINESS 账户功能，则可与业务外的账户共享。 Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	被使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
granted_account_id required	你希望授予定向受众权限的账户。 Type: string Example: `18ce54aymz3`
permission_level required	`granted_account_id` 对该定向受众应具有的访问级别。 Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
tailored_audience_id required	你在请求中操作的定向受众的引用。 Type: string Example: `2906h`

Example Request

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "tailored_audience_id": "2906h"
        }
      },
      "data": {
        "tailored_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

撤销指定的 Tailored Audience 共享权限。注意：创建或修改某个 tailored audience 的权限，要求该受众由尝试修改权限的账户所拥有。你可以通过查看该受众响应中的 is_owner 属性来验证 tailored audience 的所有权。撤销后，我们保证被授予的账户（granted_account_id）将无法在后续的广告系列中定向该受众。现有广告系列会继续使用已共享的受众；广告系列不会停止，且该受众不会从广告系列中移除。在撤销受众共享权限后，无法复制该广告系列。 资源 URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

参数

名称	描述
account_id 必填	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
tailored_audience_id 必填	你在请求中操作的 tailored audience 的引用。类型：string 示例：`1nmth`
tailored_audience_permission_id 必填	你在请求中操作的 tailored audience 权限的引用。类型：string 示例：`ri`

示例请求 DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri 示例响应

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_permission_id": "ri",
          "tailored_audience_id": "1nmth"
        }
      },
      "data": {
        "tailored_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

目标受众

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

获取针对指定 custom_audience_id 的活跃或全部投放单元与广告系列列表

名称	描述
account_id 必填	被使用的账号标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求所需的必填参数。指定的账号必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
custom_audience_id 必填	此次请求中所操作的自定义受众引用。类型：string 示例：`2906h`
with_active 可选	当为 `false` 时，包含 `servable=false` 状态的投放单元类型：boolean 默认值：`true` 可选值：`true`、`false`
cursor 可选	指定用于获取下一页结果的游标。参见 Pagination 了解更多信息。类型：string 示例：`8x7v00oow`

示例请求 GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted 示例响应

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "测试推广活动",
          "line_items": [
            {
              "id": "5gzog",
              "name": "测试广告项",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "未命名推广活动",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

自定义受众的用户

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

此端点允许合作伙伴向指定的 custom_audience_id 添加、更新或移除用户。该端点也支持为同一用户提供多种类型的用户标识符。请求中 users 字段内提供的所有数据，除 partner_user_id 外，必须使用 SHA256 进行哈希处理，并先进行规范化。 批量请求

当前最大批处理大小为 2500（仅适用于此端点）。批处理大小由每个请求中的操作数量（Update/Delete）决定。例如，在单个数组中包含超过 2500 个操作对象（{"operation_type": "Update/Delete", [..] }）将导致错误。
此端点可接受的 POST 请求正文的最大大小为 5,000,000 字节。
此端点的速率限制为每 1 分钟窗口内 1500 次。
所有参数均通过请求正文发送，且必须设置 Content-Type 为 application/json。
批量请求作为一个整体成败一致，且无论成功或失败，所有 API 响应都会保留初始请求的项目顺序。

批量响应 Ads API 返回的响应包含两个字段：success_count 和 total_count。这两个值必须始终相等，表示后端已处理的请求记录数。当请求正文中发送的记录数不等于 success_count 和 total_count 时，应视为错误情况，需要重试。 批量错误

请求级错误（例如超出最大批处理大小）会在响应的 errors 对象下显示。
条目级错误（例如缺少必需参数）会在响应的 operation_errors 对象下显示。
operation_errors 中错误的索引对应输入项的索引，并附有相应的错误消息。

资源 URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users

参数

名称	说明
operation_type 必填	针对每个 `users` 组执行的操作类型。类型：enum 可能的取值：`Update`、`Delete`
params 必填	一个包含 `users` 数组、`effective_at` 和 `expires_at` 时间戳的 JSON 对象。类型：JSON
users 必填	一个由 JSON 对象组成的数组，每个对象包含单个用户的全部参数。类型：JSON
effective_at 可选	自定义受众关联生效的 UTC 时间。采用 ISO 8601 表示。默认值为当前日期和时间。类型：string 示例：`2017-07-05T07:00:00Z`
expires_at 可选	自定义受众关联到期的 UTC 时间。指定时间必须晚于 `effective_at` 的值。采用 ISO 8601 表示。默认值为自请求时间戳起 13 个月后。类型：string 示例：`2017-07-05T07:00:00Z`

鉴于对 users 对象采用多键方式，下面记录了该对象中各元素的说明：

名称	说明
email 可选	用户的电子邮件地址。类型：Array[String]
device_id 可选	IDFA/AdID/Android ID 类型：Array[String]
handle 可选	用户的 @handle。类型：Array[String]
twitter_id 可选	用户的 X id。类型：Array[String]
phone_number 可选	用户的电话号码。类型：Array[String]
partner_user_id 可选	用户在合作伙伴系统中的 id。类型：Array[String]

示例请求

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

    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
                "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
                "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
              ]
            }
          ]
        }
      },
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "device_id": [
                "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
              ],
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
              ],
              "twitter_id": [
                "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
                "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
              ]
            }
          ]
        }
      }
    ]

示例响应

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }

自定义受众权限

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

获取指定自定义受众所关联的部分或全部权限的详细信息。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	在请求中所操作的自定义受众的引用。 Type: string Example: `1nmth`
count optional	指定每个请求要尝试检索的记录数量。 Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string Example: `8x7v00oow`
granted_account_ids optional	通过指定以逗号分隔的标识符列表，将响应限定为所需账户。最多可提供 200 个 ID。 Type: string Example: `18ce54aymz3`
sort_by optional	按支持的属性以升序或降序排序。更多信息参见 Sorting。 Type: string Example: `created_at-asc`
custom_audience_permission_ids optional	通过指定以逗号分隔的标识符列表，将响应限定为所需的自定义受众权限。最多可提供 200 个 ID。 Type: string Example: `ri`
with_total_count optional	包含 `total_count` 响应属性。 Note: 此参数与 `cursor` 互斥。 Note: 包含 `total_count` 的请求将有较低的速率限制，目前为每 15 分钟 200 次。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "custom_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

创建一个新的权限对象，允许将指定受众与给定账户共享。注意：创建或修改自定义受众的权限要求该受众归尝试修改权限的账户所有。你可以在该受众的响应中查看 is_owner 属性以检查自定义受众的所有权。注意：受众仅可在同一企业下的广告账户之间共享；或当拥有该受众的广告账户启用了 SHARE_AUDIENCE_OUTSIDE_BUSINESS 账户功能时，方可在企业外共享。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

名称	描述
account_id 必填	目标账户的标识符。出现在资源路径中，并且通常是所有 Advertiser API 请求（GET accounts 除外）的必填参数。指定的账户必须与已通过身份验证的用户关联。类型：string 示例：`18ce54d4x5t`
granted_account_id 必填	你希望授予自定义受众权限的账户。类型：string 示例：`18ce54aymz3`
permission_level 必填	要授予 `granted_account_id` 的自定义受众访问级别。类型：enum 可能的取值：`READ_ONLY`、`READ_WRITE`
custom_audience_id 必填	你在请求中要操作的自定义受众。类型：string 示例：`2906h`

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

示例响应

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "custom_audience_id": "2906h"
        }
      },
      "data": {
        "custom_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

撤销指定的自定义受众共享权限。注意：创建或修改自定义受众的权限要求该受众归属于尝试修改权限的账户。你可以通过查看某个受众响应中的 is_owner 属性来检查该自定义受众的归属。撤销后，我们保证被授予的账户（granted_account_id）将无法在后续广告系列中定向该受众。现有广告系列会继续使用共享受众运行；广告系列不会停止，且该受众不会从广告系列中移除。在受众共享权限被撤销后，将无法复制该广告系列。 资源 URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

参数

名称	描述
account_id required	被使用账户的标识符。出现在资源路径中，并且通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
custom_audience_id required	你在请求中操作的自定义受众的引用。类型：string 示例：`1nmth`
custom_audience_permission_id required	你在请求中操作的自定义受众权限的引用。类型：string 示例：`ri`

示例请求 DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri 示例响应

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

自定义受众

GET accounts/:account_id/custom_audiences

检索与当前账户关联的部分或全部自定义受众的详细信息。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	目标账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
count optional	指定每次请求尝试检索的记录数。 Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string Example: `8x7v00oow`
permission_scope optional	允许将响应过滤为你拥有的列表或与你共享的列表。默认情况下，不指定此参数时，你只能看到你拥有的受众。 Type: enum Default: `OWNER` Possible values: `OWNER`, `SHARED`
q optional	按 `name` 限定资源的可选查询。 Note: 执行不区分大小写的前缀匹配。 Type: string Min, Max length: `1`, `255`
sort_by optional	按受支持的属性进行升序或降序排序。更多信息参见 Sorting。 Type: string Example: `created_at-asc`
custom_audience_ids optional	通过指定以逗号分隔的标识符列表，将响应限定为所需的自定义受众。最多可提供 200 个 ID。 Type: string Example: `1nmth`
with_deleted optional	在请求中包含已删除的结果。 Type: boolean Default: `false` Possible values: `true`, `false`
with_total_count optional	在响应中包含 `total_count` 属性。 Note: 此参数与 `cursor` 互斥。 Note: 包含 `total_count` 的请求将有较低的速率限制，目前为每 15 分钟 200 次。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth Example Response

    {
      "request": {
        "params": {
          "custom_audience_ids": [
            "1nmth"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": true,
          "name": "twurl-using-subshell-for-file",
          "targetable_types": [
            "CRM",
            "EXCLUDED_CRM"
          ],
          "audience_type": "CRM",
          "description": null,
          "permission_level": "READ_WRITE",
          "owner_account_id": "18ce54d4x5t",
          "id": "1nmth",
          "reasons_not_targetable": [],
          "created_at": "2017-01-08T08:19:58Z",
          "updated_at": "2017-01-08T16:21:13Z",
          "partner_source": "OTHER",
          "deleted": false,
          "audience_size": 1470
        }
      ]
    }

GET accounts/:account_id/custom_audiences/:custom_audience_id

检索与当前账户关联的特定自定义受众（Custom Audiences）。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

名称	说明
account_id required	目标账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已通过身份验证的用户关联。类型：string 示例：`18ce54d4x5t`
custom_audience_id required	在请求中所操作的自定义受众的标识。类型：string 示例：`2906h`
with_deleted optional	是否在结果中包含已删除项。类型：boolean 默认值：`false` 可选值：`true`、`false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

    {
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": 140321
      }
    }

POST accounts/:account_id/custom_audiences

创建一个与当前账户关联的新的占位符自定义受众（Custom Audience）。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	被使用账户的标识符。该值出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
name required	此受众的显示名称。必须唯一，否则会返回错误。 Type: string Example: `ads api users`
description optional	此受众的描述。 Type: string Example: `Collection of all users of the Ads API`

Example Request POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers"
        }
      }
    }

PUT accounts/:account_id/custom_audiences/:custom_audience_id

更新与当前账户关联的特定自定义受众。 资源 URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id 参数

名称	说明
account_id 必填	正在使用的账户标识符。该值出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已通过身份验证的用户关联。类型：string 示例：`18ce54d4x5t`
custom_audience_id 必填	本次请求所操作的自定义受众的引用。类型：string 示例：`2906h`
name 可选	该受众的显示名称。必须使用唯一名称，否则会返回错误。类型：string 示例：`ads api users`
description 可选	该受众的描述。类型：string 示例：`Collection of all users of the Ads API`

示例请求 PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed 示例响应

    {
      "data": {
        "targetable": false,
        "name": "developers_changed",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "is_owner": true,
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers_changed"
        }
      }
    }

POST batch/accounts/:account_id/custom_audiences

允许批量创建自定义受众。有关受众的更多信息，请参阅自定义受众概览页面。 注意：此批量端点目前处于封闭测试阶段，仅向部分广告主开放。在测试期间，仅支持创建基于移动端自定义受众的灵活受众。 批量请求

当前最大批次大小为 10。
所有参数均在请求正文中发送，且必须将 Content-Type 设置为 application/json。
批量请求作为一个整体同时成功或失败；无论成功还是错误，所有 API 响应都会保留初始请求中各项的顺序。

批量响应 批量 API 响应会返回一个有序的项目集合。除此之外，其结构与对应的单项端点完全相同。 批量错误

请求级错误（例如超出最大批次大小）会在响应的 errors 对象下显示。
项目级错误（例如缺少必需参数）会在响应的 operation_errors 对象下显示。

灵活受众

灵活受众一经创建不可修改。
通过以树形结构传入自定义受众，并使用布尔逻辑组合来创建灵活受众。
创建一个灵活受众最多可使用 10 个自定义受众叶节点。

资源 URL https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences 参数

名称	说明
account_id 必填	被使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
audience_type 必填	要创建的受众类型。类型：enum 可能的取值：`FLEXIBLE`, `MOBILE_AUDIENCE`
child_segments 必填	一个数组，包含用于定义你希望定向的 Custom Audience 成员子集的对象。每个对象应包含 `custom_audience_id`、`frequency`、`frequency_comparator`、`lookback_window`、`negate`，并在某些情况下包含额外的 `child_segments`。类型：array
name 必填	受众的显示名称。必须使用唯一的名称值，否则将导致错误。类型：string 示例：`my_flexible_audience_name`
operation_type 必填	针对每个条目执行的操作类型。类型：enum 可能的取值：`Create`, `Update`, `Delete`
boolean_operator 有时必填	父（包含）对象中子分段之间的逻辑关系。若父对象的 child_segments 非空，则为必填。类型：enum 可能的取值：`AND`, `OR`
lookback_window 有时必填	一个整数值，指定用户在多少天的范围内采取了特定操作并满足给定 custom audience 的条件。类型：int 可能的取值：`1`, `7`, `14`, `30`
segments 有时必填	一个对象，包含 `boolean_operator` 和 `child_segments`，用于定义你希望定向的 Custom Audience 成员子集。类型：object
custom_audience_id 有时必填	用作子分段的 custom audience 的 id。类型：string 示例：`tyfo`
frequency 可选	一个整数值，指定在回溯窗口内用户采取特定操作并满足给定 custom audience 条件的次数。类型：int 默认值：`1`
frequency_comparator 可选	与请求中传入的 `frequency` 进行比较的比较符。注意：下列取值中，`GTE` 表示大于等于，`LT` 表示小于，依此类推。类型：string 可能的取值：`NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` 默认值：`NUM_GTE`
negate 可选	对该分段取反，从而在组合中被排除。类型：boolean 默认值：`true` 可能的取值：`true`, `false`

示例请求 POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"我的灵活受众名称",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"AND",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"OR",
                "child_segments":[
                  {
                    "custom_audience_id":"TXR1",
                    "lookback_window":30,
                    "child_segments":[

                    ]
                  },
                  {
                    "custom_audience_id":"TYFO",
                    "frequency":1,
                    "frequency_comparator":"NUM_GT",
                    "lookback_window":30,
                    "negate":true,
                    "child_segments":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

示例响应

    {
      "data": {
        "targetable": false,
        "name": "my_flexible_audience_name",
        "targetable_types": [
          "FLEXIBLE",
          "EXCLUDED_FLEXIBLE"
        ],
        "audience_type": "FLEXIBLE",
        "id": "13ld7",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "metadata": [
          {
            "custom_audience_id": "13ld7",
            "account_id": "qsx3w2",
            "name": "my_flexible_audience_name",
            "audience_source": "FLEXIBLE_AUDIENCE",
            "upload_status": "UPLOADED",
            "segments": {
              "boolean_operator": "AND",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "custom_audience_id": "tyif",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [
                    {
                      "custom_audience_id": "txr1",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GTE",
                      "negate": false,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "tyfo",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            }
          }
        ],
        "created_at": "2015-11-10T21:26:43Z",
        "updated_at": "2015-11-11T01:11:47Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": [
        {
          "params": {
            "name": "my_flexible_audience_name",
            "audience_type": "FLEXIBLE",
            "segments": {
              "boolean_operator": "AND",
              "child_segments": [
                {
                  "custom_audience_id": "TYIF",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "child_segments": [
                    {
                      "custom_audience_id": "TXR1",
                      "lookback_window": 30,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "TYFO",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            },
            "account_id": "qsx3w2"
          },
          "operation_type": "Create"
        }
      ]
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

删除当前账户下的指定自定义受众。 资源 URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id 参数

名称	描述
account_id 必填	目标账户的标识符。该值出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
custom_audience_id 必填	本次请求中要操作的自定义受众的标识。类型：string 示例：`2906h`

示例请求 DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h 示例响应

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTHER",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

禁止触达名单

GET accounts/:account_id/do_not_reach_lists

检索与当前账户关联的部分或全部“禁止触达列表”的详细信息。注意：每个 account_id 至多只能拥有一个“禁止触达列表” Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

Name	Description
account_id required	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所必需的参数。指定的账户必须与已验证用户关联。 Type: string Example: `18ce54d4x5t`
with_deleted optional	在请求中包含已删除的结果。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54bgxky"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": false,
          "name": "禁止触达名单",
          "description": "DNRL 测试",
          "id": "4kzrq",
          "reasons_not_targetable": [
            "TOO_SMALL"
          ],
          "created_at": "2021-10-28T22:09:29Z",
          "list_size": null,
          "updated_at": "2021-11-04T03:33:06Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/do_not_reach_lists

创建一个与当前账户关联的全新 Do Not Reach List。注意：每个 account_id 最多只能有一个 Do Not Reach List 资源 URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists 参数

名称	说明
account_id 必填	目标账户的标识符。出现在资源路径中，并且通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
description 可选	此受众的描述。类型：string 示例：`A list of users to exclude`

示例请求 POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude 示例响应

    {
      "request": {
        "params": {
          "description": "要排除的用户列表",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "排除触达列表",
        "description": "要排除的用户列表",
        "id": "4ofrq",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:48Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:48Z",
        "deleted": false
      }
    }

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

此端点允许将用户添加到指定的 do_not_reach_list_id，或对其进行更新和移除。此端点仅接受电子邮件作为有效的用户标识符类型。请求中 emails 字段提供的所有数据必须使用 SHA256 进行哈希处理，并先进行规范化。注意

一个 account_id 最多只能拥有一个 Do Not Reach List
添加到此列表的用户必须将 expires_at 时间戳设置为自当前时间戳起不超过 13 个月
Do Not Reach List API 不接受 effective_at 时间戳，并默认使用当前时间戳
Do Not Reach List 不会将用户从该账户中的任何（或全部）自定义受众中移除，而是作为该账户所有投放活动的排除定向条件

批量请求

当前最大批量大小为 2500（仅针对此端点）。批量大小由每个请求中的操作数（Update/Delete）决定。例如，在一个数组中包含超过 2500 个操作对象（{"operation_type": "Update/Delete", [..] }）将导致错误。
此端点可接受的最大 POST 请求正文大小为 5,000,000 字节。
此端点的速率限制为每 1 分钟窗口 1500 次
所有参数通过请求正文发送，并且需要 application/json 的 Content-Type。
批量请求作为一个整体一起成功或失败，且无论错误还是成功，API 响应都会保留初始请求的项目顺序。

批量响应 Ads API 返回的响应包含两个字段：success_count 和 total_count。二者必须始终相等，表示后端已处理的请求记录数。当请求正文中发送的记录数与 success_count 和 total_count 不相等时，应视为错误情况，需要重试。 批量错误

请求级错误（例如，超过最大批量大小）会在响应的 errors 对象下显示。
项目级错误（例如，缺少必需参数）会在响应的 operation_errors 对象下显示。
operation_errors 中错误的索引对应输入项的索引，并附有相应的错误消息

资源 URL https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users 参数

Name	Description
account_id required	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
do_not_reach_list_id required	你在请求中要操作的 Do Not Reach List 的引用 Type: string Example: `2906h`
operation_type required	针对 `users` 分组正在执行的操作类型。 Type: enum Possible values: `Update`, `Delete`
params required	一个包含 `emails` 数组和 `expires_at` 时间戳的 JSON 对象。 Type: JSON
users required	由 JSON 对象组成的数组，包含单个用户的所有参数。 Type: JSON
expires_at optional	用户关联的过期 UTC 时间。指定时间必须晚于当前时间戳。采用 ISO 8601 表示。默认值为自当前时间戳起 13 个月。 Type: string Example: `2017-07-05T07:00:00Z`

鉴于对 users 对象采用多键方式，下面逐一说明该对象的每个元素：

名称	描述
email 可选	用户的电子邮件地址。类型：Array[String]
phone_number 可选	用户的电话号码。类型：Array[String]

示例请求

`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users`

    [
      {
        "operation_type": "Update",
        "params": {
          "expires_at": "2023-01-22T00:00:00Z",
          "users": [
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
              ]
            },
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
              ]
            }
          ]
        }
      }
    ]

示例响应

    {
      "data": [
        {
          "success_count": 2,
          "total_count": 2
        }
      ],
      "request": [
        {
          "params": {
            "do_not_reach_list_id": "4ofrq",
            "expires_at": "2023-01-22T00:00:00Z",
            "account_id": "18ce54bgxky"
          },
          "operation_type": "Update"
        }
      ]
    }

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

删除当前账户下指定的 Do Not Reach List。 资源 URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id 参数无 示例请求 DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp 示例响应

    {
      "request": {
        "params": {
          "do_not_reach_list_id": "4ofrp",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "禁止触达列表",
        "description": null,
        "id": "4ofrp",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2022-02-08T23:02:07Z",
        "list_size": null,
        "updated_at": "2022-02-08T23:02:21Z",
        "deleted": true
      }
    }

X 广告 API

基础

资源

测量

​自定义受众群体

​概述

​受众常见问题解答

​CRM

​合作伙伴 ID 匹配要求

​标准匹配要求

​自定义细分列表文件命名与操作

​创建和更新受众

​哈希说明

​电子邮件规范化

​设备 ID 规范化

​X 用户 ID 规范化

​ID 同步集成

​像素 URL

​像素参数

​ID 同步像素：

​自定义受众用户数据

​自定义受众：网页

​Audience API 集成

​概览

​创建新的自定义受众

​将用户添加到受众

​从受众中移除用户

​选择退出的用户

​API 参考

​关键词洞察

​GET insights/keywords/search

​定向受众权限

​GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

​目标受众

​GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

​自定义受众的用户

​POST accounts/:account_id/custom_audiences/:custom_audience_id/users

​资源 URL

​参数

​示例请求

​示例响应

​自定义受众权限

​GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

​自定义受众

​GET accounts/:account_id/custom_audiences

​GET accounts/:account_id/custom_audiences/:custom_audience_id

​POST accounts/:account_id/custom_audiences

​PUT accounts/:account_id/custom_audiences/:custom_audience_id

​POST batch/accounts/:account_id/custom_audiences

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id

​禁止触达名单

​GET accounts/:account_id/do_not_reach_lists

​POST accounts/:account_id/do_not_reach_lists

​POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

​DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

自定义受众群体

概述

受众常见问题解答

CRM

合作伙伴 ID 匹配要求

标准匹配要求

自定义细分列表文件命名与操作

创建和更新受众

哈希说明

电子邮件规范化

设备 ID 规范化

X 用户 ID 规范化

ID 同步集成

像素 URL

像素参数

ID 同步像素：

自定义受众用户数据

自定义受众：网页

Audience API 集成

概览

创建新的自定义受众

将用户添加到受众

从受众中移除用户

选择退出的用户

API 参考

关键词洞察

GET insights/keywords/search

定向受众权限

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

目标受众

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

自定义受众的用户

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

资源 URL

参数

示例请求

示例响应

自定义受众权限

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

自定义受众

GET accounts/:account_id/custom_audiences

GET accounts/:account_id/custom_audiences/:custom_audience_id

POST accounts/:account_id/custom_audiences

PUT accounts/:account_id/custom_audiences/:custom_audience_id

POST batch/accounts/:account_id/custom_audiences

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

禁止触达名单

GET accounts/:account_id/do_not_reach_lists

POST accounts/:account_id/do_not_reach_lists

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id