概述
简介
使用场景
- 创意
- 定向
- 出价类型
- 出价单位
A/B Testing
用例
- 创意
- 定向
- 出价类型
- 出价单位
属性
- 测试持续时间，由 start_time 和 end_time 字段表示
- 进行拆分的层级，由 entity_type 字段表示
- 至少两个（最多 30 个）用户分组，每个分组在 user_groups 数组中以对象形式表示
- 应分配到该用户分组的用户百分比，由 size 字段表示
- 应构成该用户分组用户池的广告系列 ID/投放单元（line item）ID，由 entity_ids 数组表示
使用
创建
-
start_time 和 end_time 的取值必须
- 相对于创建 A/B 测试的时间而言为将来时间
- 与广告系列/广告投放项的投放日期重叠
- 非 App 类广告系列的测试必须至少持续一天；App 类广告系列的测试必须至少持续五天
- entity_type 可设置为 CAMPAIGN 或 LINE_ITEM
-
每个用户组在 user_groups 数组中表示为一个对象
- 至少需要两个用户组
- 最多允许 30 个用户组
-
每个用户组的大小使用字符串形式的数值设置，范围为 1.00 至 99.00
- 注意：各对象的 size 值相加之和必须为 100.00
- 应在每个用户组的 entity_ids 数组中指定广告系列 ID
- A/B 测试广告系列中的所有行项目都必须包含在分流测试中。
- 行项目级仅允许等比分流。
- 单个分流测试中允许的用户组行项目数量须小于或等于 5。
- 每个用户组仅允许 1 个行项目。
更新
- 如需添加或移除对象或元素，请传入整个数组（及其子结构）；这是一次替换操作
-
其他情况下，通过引用键名或 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 请求所必需的参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| ab_test_ids 可选 | 通过指定以逗号分隔的标识符列表，将响应限定为所需的 A/B Tests。最多可提供 200 个 ID。 Type: string Example: hr7l0 |
| count 可选 | 指定每个请求尝试检索的记录数量。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor 可选 | 指定一个游标以获取下一页结果。有关更多信息，请参阅 Pagination。 Type: string Example: 8x7v00oow |
| live_during 可选 | 将响应限定为在给定日期范围内曾经或将会上线的 A/B Tests。返回开始和结束时间与给定日期范围部分或全部重叠的 A/B Tests。 将值指定为以逗号分隔的日期，使用 ISO 8601 表示。应先给出较早的日期。 Type: string Example: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z |
| q 可选 | 一个可选的 query（查询），按 name 限定资源。省略此参数以检索全部。Type: string Min, Max length: 1, 80 |
| sort_by 可选 | 按受支持的属性进行升序或降序排序。有关更多信息，请参阅 Sorting。 Type: string Example: created_at-asc |
| status 可选 | 将响应限定为具有指定状态的 A/B Tests。 Type: enum Possible values: COMPLETED, LIVE, SCHEDULED |
| user_id 可选 | 将响应限定为由指定用户 ID 创建的 A/B Tests。 注意：不能与 username 同时指定。Type: long Example: 756201191646691328 |
| username 可选 | 将响应限定为由指定用户名创建的 A/B Tests。不要包含开头的“@”符号。 注意：不能与 user_id 同时指定。Type: string Example: apimctestface |
| with_deleted 可选 | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: 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 请求所必需的参数。所指定的账户必须与已通过身份验证的用户关联。 Type: string Example: 18ce54d4x5t |
| end_time 必填 | A/B 测试结束的时间，采用 ISO 8601 表示。 Type: string Example: 2020-10-02T00:00:00Z |
| entity_type 必填 | 用于划分用户组的实体类型。 Type: enum Possible values: CAMPAIGN, LINE_ITEM |
| start_time 必填 | A/B 测试开始的时间，采用 ISO 8601 表示。 Type: string Example: 2022-05-30T00:00:00Z |
| user_groups 必填 | 用户组的定义。更多信息见下表。可指定 2 到 30 个用户组。 Type: array of objects |
| description 可选 | A/B 测试的描述。最大长度：1,024 个字符。 Type: string Example: documentation example |
| name 可选 | A/B 测试的名称。最大长度：255 个字符。 Type: string Example: first AB test |
用户分组
| 名称 | 说明 |
|---|---|
| entity_ids 必填 | 实体 ID 的数组。 注意：每个实体只能关联到一个 A/B 测试。 Type: array Example: ["dxi0l", "e66bl"] |
| size 必填 | 分配给此用户分组的用户占比。该数值为数值，但以字符串形式表示，小数点后最多两位。例如，将 40% 表示为：40、40.0 或 40.00。 注意：所有_对象_的 size 值之和必须等于 100.00。 Type: array Min, Max: 1.00, 99.00 |
| description 可选 | 用户分组的描述。最大长度：1,024 个字符。 Type: string Example: second AB test group |
| name 可选 | 用户分组的名称。最大长度：255 个字符。 Type: string Example: 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。
此 endpoint 支持包含对象 ID 的部分 JSON。遵循以下原则：
- 如需添加或移除对象或元素，请传入整个数组（及其子结构）；这是一次替换操作
- 可将其视为重新创建该数组
- 其他情况下，通过引用键名或 ID 来修改（更改、添加、移除）现有 fields
- 如需移除某个字段，将其值设为
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 请求的必需参数。指定的账号必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| ab_test_id 必填 | 你在请求中所操作的 A/B 测试的引用。 Type: string Example: hr7l0 |
| description 可选 | A/B 测试的描述。最大长度：1,024 个字符。 注意：仅当 A/B 测试的 status 为 SCHEDULED 时可更新。Type: string Example: documentation example |
| end_time 可选 | A/B 测试结束时间，采用 ISO 8601 表示。 注意：仅当 A/B 测试的 status 为 SCHEDULED 或 LIVE 时可更新。Type: string Example: 2020-10-02T00:00:00Z |
| name 可选 | A/B 测试的名称。最大长度：255 个字符。 注意：仅当 A/B 测试的 status 为 SCHEDULED 时可更新。Type: string Example: first AB test |
| start_time 可选 | A/B 测试开始时间，采用 ISO 8601 表示。 注意：仅当 A/B 测试的 status 为 SCHEDULED 时可更新。Type: string Example: 2022-05-30T00:00:00Z |
| user_groups 必填 | 用户分组的说明。更多信息见下表。 注意：仅当 A/B 测试的 status 为 SCHEDULED 时可更新。Type: array of objects |
用户组
| 名称 | 描述 |
|---|---|
| id 有时必填 | 请求中所操作的用户组对象的引用。 注意：当修改（更改、添加或移除）用户组对象的_fields_时必填。 注意：在添加或移除整个用户组对象时不要指定 ID。 Type: string Example: p1bcx |
| description 可选 | 用户组的描述。最大长度：1,024 个字符。 注意：将该字段设为 null 可清除（移除）其值。Type: string Example: second AB test group |
| entity_ids 可选 | 实体 ID 的数组。 注意：这是替换操作，会覆盖先前设置的值。 注意：实体只能关联到一个 A/B Test。 Type: array Example: ["dxi0l", "e66bl"] |
| name 可选 | 用户组的名称。最大长度：255 个字符。 注意：将该字段设为 null 可清除（移除）其值。Type: string Example: first group |
| size 可选 | 分配给此用户组的用户百分比。该数值以字符串形式表示，且小数点后最多两位。例如，将 40% 表示为：40、40.0 或 40.00。 注意：所有_对象_的 size 值相加必须为 100.00。 Type: string Min, Max: 1.00, 99.00 |
示例请求
- 移除 A/B 测试的描述
- 更改 end_time
- 为第一个用户组添加描述
- 调整各用户组的用户占比
- 向第二个用户组添加实体 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 测试的引用。 Type: string Example: hr7l0 |
示例请求
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0