概述
简介
使用场景
- 创意
- 定向
- 出价类型
- 出价单位
A/B 测试
使用场景
- 创意
- 定向
- 出价类型
- 出价单位
属性
- 测试时长，由 start_time 和 end_time 字段表示
- 分流发生的层级，由 entity_type 字段表示
- 至少两个（最多 30 个）用户组，每个在 user_groups 数组中以对象形式表示
- 分配到该用户组的用户百分比，由 size 字段表示
- 构成该用户组用户池的广告系列 ID/广告组（Line Item）ID，由 entity_ids 数组表示
使用方法
创建
-
start_time 和 end_time 的取值必须
- 位于未来时间（相对于创建 A/B 测试的时点）
- 与广告系列/广告组的投放周期有重叠
- 非 App 类广告系列的测试至少持续 1 天；App 类广告系列的测试至少持续 5 天
- entity_type 可设置为 CAMPAIGN 或 LINE_ITEM
-
每个用户组在 user_groups 数组中表示为一个对象
- 至少需要两个用户组
- 最多允许 30 个用户组
-
每个用户组的 size 使用字符串表示，数值范围为 1.00 至 99.00
- 注意：各对象的 size 值相加后必须为 100.00
- 每个用户组应在其 entity_ids 数组中指定广告系列 ID
- A/B 测试所属广告系列中的所有 Line item 都必须纳入分流测试。
- Line item 级别仅支持等比例分配。
- 单次分流测试中允许的用户分组所包含的 Line item 数量须小于或等于 5。
- 每个用户分组仅允许 1 个 Line item。
更新
- 若要添加或移除对象或元素，请传入整个数组（及其子结构）；这是一次替换操作
-
其他情况下，通过引用键名或 ID 来修改（更改、添加、移除）现有 fields
- 若要移除字段，将其值设置为 null
- 未传入的字段不会被修改
请求示例
- 添加第三个未包含名称或描述的用户组
- 更改各用户组所占用户百分比
- 移除 A/B 测试的描述
- 为第一个用户组添加描述
- 为第二个用户组添加一个实体 ID（f2syz）
- 删除第二个用户组
- 调整各用户组的用户占比
API 参考文档
A/B 测试
GET accounts/:account_id/ab_tests
获取部分或全部 A/B 测试的详细信息。资源 URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型: string 示例: 18ce54d4x5t |
| ab_test_ids 可选 | 通过指定以逗号分隔的标识符列表，将响应限定为所需的 A/B 测试。最多可提供 200 个 ID。 类型: string 示例: hr7l0 |
| count 可选 | 指定每个独立请求尝试检索的记录数。 类型: int 默认值: 200 最小值、最大值: 1, 1000 |
| cursor 可选 | 指定用于获取下一页结果的游标。有关更多信息，请参见 分页。 类型: string 示例: 8x7v00oow |
| live_during 可选 | 将响应限定为在给定日期范围内曾经或将会处于活动状态的 A/B 测试。返回开始和结束时间与给定日期范围部分或完全重叠的 A/B 测试。 将值指定为以逗号分隔的日期，并使用 ISO 8601 格式表示。应先提供较早的日期。 类型: string 示例: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z |
| q 可选 | 通过 name 字段进行限定的可选查询。省略此参数可检索全部结果。类型: string 最小、最大长度: 1, 80 |
| sort_by 可选 | 按受支持的属性进行升序或降序排序。有关更多信息，请参见 排序。 类型: string 示例: created_at-asc |
| status 可选 | 将响应限定为具有指定状态的 A/B 测试。 类型: enum 可能的取值: COMPLETED, LIVE, SCHEDULED |
| user_id 可选 | 将响应限定为由指定用户 ID 创建的 A/B 测试。 注意: 不能与 username 同时指定。类型: long 示例: 756201191646691328 |
| username 可选 | 将响应限定为由指定用户名创建的 A/B 测试。不要包含开头的 “@” 符号。 注意: 不能与 user_id 同时指定。类型: string 示例: apimctestface |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型: boolean 默认值: false 可能的取值: true, false |
示例请求
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests
示例响应
POST accounts/:account_id/ab_tests
创建一个新的 A/B 测试。 所有参数通过请求正文发送，并且需要将Content-Type 设置为 application/json。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已验证的用户关联。 类型：string 示例： 18ce54d4x5t |
| end_time 必填 | 以 ISO 8601 表示的 A/B 测试结束时间。 类型：string 示例： 2020-10-02T00:00:00Z |
| entity_type 必填 | 用于划分用户组的实体类型。 类型：enum 可能的取值： CAMPAIGN、LINE_ITEM |
| start_time 必填 | 以 ISO 8601 表示的 A/B 测试开始时间。 类型：string 示例： 2022-05-30T00:00:00Z |
| user_groups 必填 | 对用户组的描述。更多信息见下表。可指定 2 至 30 个用户组。 类型：array of objects |
| description 可选 | A/B 测试的描述。最大长度：1,024 个字符。 类型：string 示例： documentation example |
| name 可选 | A/B 测试的名称。最大长度：255 个字符。 类型：string 示例： first AB test |
用户组
| 名称 | 说明 |
|---|---|
| entity_ids 必填 | 实体 ID 的数组。 注意：每个实体只能关联到一个 A/B 测试。 类型：array 示例： ["dxi0l", "e66bl"] |
| size 必填 | 分配给此用户组的用户百分比。为数值，以字符串表示，小数点后最多两位。例如，40% 可表示为：40、40.0 或 40.00。 注意：各个对象的 size 值相加后必须为 100.00。 类型：array 最小值/最大值： 1.00，99.00 |
| description 可选 | 用户组的描述。最大长度：1,024 个字符。 类型：string 示例： second AB test group |
| name 可选 | 用户组的名称。最大长度：255 个字符。 类型：string 示例： first group |
示例请求
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests -d '{"end_time": "2022-05-30T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2022-05-25T01:00:00Z", "user_groups": [{"entity_ids": ["f2qcw", "f2tht"], "size": "50.00", "name": "first group"},{"entity_ids": ["f2rqi", "f2tws"], "size": "50.00", "name": "second group", "description": "second AB test group"}], "name": "first AB test", "description": "documentation example"}'
示例响应
PUT accounts/:account_id/ab_tests/:ab_test_id
更新指定的 A/B 测试。 所有参数都在请求正文中发送，并且需要将Content-Type 设置为 application/json。
此端点支持包含对象 ID 的部分 JSON。适用以下原则：
- 若要添加或移除对象或元素，请传入整个数组（及其子结构）；这是一次替换操作
- 可以理解为重新创建该数组
- 其他情况下，通过引用键名或 ID 来修改（更改、添加、移除）现有字段
- 要移除字段，请将其值设置为
null - 未传入的字段不会被修改
- 要移除字段，请将其值设置为
status 为 SCHEDULED 时，才能更新 A/B 测试。存在一个例外：当其为 LIVE 时，可以更新 A/B 测试的 end_time。
资源 URL
https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| ab_test_id 必填 | 本次请求中所操作的 A/B 测试引用。 类型：string 示例： hr7l0 |
| description 可选 | A/B 测试的描述。最大长度：1,024 个字符。 注意：仅当 A/B 测试的 status 为 SCHEDULED 时可更新。类型：string 示例： documentation example |
| end_time 可选 | A/B 测试结束时间，采用 ISO 8601 表示。 注意：仅当 A/B 测试的 status 为 SCHEDULED 或 LIVE 时可更新。类型：string 示例： 2020-10-02T00:00:00Z |
| name 可选 | A/B 测试的名称。最大长度：255 个字符。 注意：仅当 A/B 测试的 status 为 SCHEDULED 时可更新。类型：string 示例： first AB test |
| start_time 可选 | A/B 测试开始时间，采用 ISO 8601 表示。 注意：仅当 A/B 测试的 status 为 SCHEDULED 时可更新。类型：string 示例： 2022-05-30T00:00:00Z |
| user_groups 必填 | 用户分组的定义。更多信息见下表。 注意：仅当 A/B 测试的 status 为 SCHEDULED 时可更新。类型：对象数组 |
用户组
| 名称 | 说明 |
|---|---|
| id 有时必填 | 在请求中你要操作的用户组对象的引用。 注意：在修改（更改、添加或移除）用户组对象的字段（fields）时必填。 注意：在添加或移除整个用户组对象时不要指定 ID。 类型：string 示例： p1bcx |
| description 可选 | 用户组的描述。最大长度：1,024 个字符。 注意：可通过将该字段设置为 null 来取消（移除）。类型：string 示例： second AB test group |
| entity_ids 可选 | 实体 ID 的数组。 注意：这是替换操作，将覆盖先前的所有设置。 注意：每个实体只能关联到一个 A/B 测试。 类型：array 示例： ["dxi0l", "e66bl"] |
| name 可选 | 用户组的名称。最大长度：255 个字符。 注意：可通过将该字段设置为 null 来取消（移除）。类型：string 示例： first group |
| size 可选 | 分配给此用户组的用户百分比。该数值以字符串表示，小数点后最多两位。例如，将 40% 表示为：40、40.0 或 40.00。 注意：所有对象的该数值相加必须为 100.00。 类型：string 最小值、最大值： 1.00，99.00 |
示例请求
- 删除 A/B 测试描述
- 修改结束时间
- 为第一个用户组添加描述
- 调整各用户组的用户占比
- 向第二个用户组添加一个实体 ID（
f2syz）
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0 -d '{"description": null, "end_time": "2022-06-01T01:00:00Z", "user_groups": [{"id": "p1bcx", "description": "first AB test group", "size": "60.00"},{"id": "p1bcy", "size": "40.00", "entity_ids": ["f2rqi", "f2tws", "f2syz"]}]}'
示例响应
DELETE accounts/:account_id/ab_tests/:ab_test_id
删除指定的 A/B 测试。 注意：删除 A/B 测试后无法恢复，之后再次尝试删除该资源将返回 HTTP 404。资源 URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests/:ab_test_id
参数
| 名称 | 说明 |
|---|---|
| ab_test_id 必填 | 此请求中所关联的 A/B 测试引用。 类型：string 示例： hr7l0 |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0