创建规则
您可以使用本接口创建自动规则。
重要提示
目前，该接口仅支持直客广告主。自动规则通知会直接路由至开发者注册的邮箱地址。因此，管理多个广告主的 SaaS 平台及技术公司无法使用此接口，因为系统无法将通知分别路由至其管理的各个广告主。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径| /v1.2/optimizer/rule/create/| /v1.3/optimizer/rule/create/|
|请求参数类型|advertiser_id: number<br>dimension_ids: number[]|advertiser_id: string<br>dimension_ids: string[]|
|返回参数类型|rule_ids: number[]|rule_ids`: string[]|
## 请求
**地址** <https://business-api.tiktok.com/open_api/v1.3/optimizer/rule/create/>
**方法** POST
**Header**
```xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许格式：`application/json`。|
参数
|字段|类型|描述|
|---|---|---|
|advertiser_id {必填}|string| 广告主ID。|
|rules|object[]| 规则列表。|
#|apply_objects {必填}|object[]| 规则应用的对象。对象可以是推广系列、广告组或广告。|
##|dimension {必填}|string| 对象层级。枚举值: `CAMPAIGN`(推广系列), `ADGROUP`(广告组), `AD`(广告)。|
##|dimension_ids| string[]| 对象ID列表。|
##|pre_condition_type {必填}|string| 预筛选条件。 <ul><li>`SELECTED`: 只包含所选ID</li><li>`ALL_ACTIVE_CAMPAIGN`: 选择所有在用推广系列</li><li>`ALL_ACTIVE_AD_GROUP`: 选择所有在用广告组 </li><li>`ALL_ACTIVE_AD`: 选择所有在用广告</li><li>` ALL_ACTIVE_AD_GROUP_UNDER_SELECTED`: 选择所选推广系列下的所有在用广告组</li><li>`ALL_ACTIVE_AD_UNDER_SELECTED`: 选择所选层级下的所有在用广告</li><li>`ALL_INACTIVE_CAMPAIGN`: 选择所有非在用推广系列 </li><li>`ALL_INACTIVE_AD_GROUP`: 选择所有非在用广告组</li><li>`ALL_INACTIVE_AD`: 选择所有非在用广告</li><li>`ALL_INACTIVE_AD_GROUP_UNDER_SELECTED`: 选择所选推广系列下的所有非在用广告组</li><li>`ALL_INACTIVE_AD_UNDER_SELECTED`: 选择所选推广系列或广告组(通过`dimension`和`dimension_ids`字段声明)下所有非在用广告</li></ul>|
#|conditions {必填}|object[]| 条件。|
##|subject_type {必填}|string| 用于设置条件的指标。枚举值: <ul><li>`COST`</li><li>`DAILY_BUDGET_SPENDING_RATE`</li><li>`LIFETIME_BUDGET_SPENDING_RATE`</li><li>`IMPRESSION`</li><li>`CLICK`</li><li>`CLICK`</li><li>`CONVERSION`</li><li>`CVR`</li><li>`CPA`</li><li>`CPM`</li><li>`CPC`</li><li>`CTR`</li><li>`COST_PER_RESULT`</li><li>`RESULT`</li><li>`RESULT_RATE`</li><li>`BID_STRATEGY`: `values` 必须定义为 `COST_CAP`, `BID_CAP`, `MAX_CONVERSION`或`LOWEST_COST`</li><li>`OPTIMIZATION_GOAL`: `values`必须定义为`CONVERT`, `CLICK`, `SHOW`, `REACH`, `INSTALL`, `IN_APP_EVENT`, `LEAD_GENERATION`, `TWO_SECOND_VIDEO_VIEW`或`SIX_SECOND_VIDEO_VIEW`</li><li>`OBJECTIVE`: `values`必须定义为`TRAFFIC`, `APP_PROMOTION`, `WEB_CONVERSIONS`, `VIDEO_VIEWS`, `REACH`或`LEAD_GENERATION`</li><li>`NAME`</li><li>`DAYS_SINCE_CREATION`: `match_type` 必须定义为`GT`, `LT`, `BETWEEN`或`MATCH`</li><li>`NO_CONDITION`</li><li>`ROAS_PURCHASE`</li><li>`ROAS_IMPRESSION_ADS`</li><li>`ROAS_PURCHASE_SKAN`</li><li>`ROAS_COMPLETE_PAYMENT`</li><li>`ROAS_PURCHASES_ONSITE`</li><li>`NOT_REAL_TIME_CPA`</li><li>`NOT_REAL_TIME_CONVERSION`</li><li>`NOT_REAL_TIME_CVR`</li></ul>|
##|range_type|string| 条件的时间范围。枚举值: <ul><li>`TODAY`</li><li>`YESTERDAY`</li><li>`PAST_THREE_DAYS`</li><li>`PAST_FIVE_DAYS`</li><li>`PAST_SEVEN_DAYS`</li><li>`LIFETIME`</li></ul>|
##|match_type|string| 条件的匹配类型（操作符），用于连接指标和具体的值。枚举值:`GT` (大于), `LT` (小于), `BETWEEN`(在两者之间)。当`subject_type`是`NAME`时，可以使用以下`match_type`：<li>`CONTAINS`</li><li>`NOT_CONTAINS`</li><li>`START_WITH`</li><li>`END_WITH`</li><li>`STRING_EQUAL`|
##|values|string[]| 条件的值。 如果 `match_type`设为`BETWEEN`, 您需要在列表中包含两个值。<br><p><span style="color:darkred"><b>注意</b></span>：传入的`subject_type`不同，`values`字段的校验规则也不同。欲了解具体校验规则，请参考<a href="#item-link-values字段的校验规则">values字段的校验规则</a>。 |
##|calculation_type|string|`subject_type`必须为`COST`。<li>当传空时，默认值是 `OF_EACH_OBJECT`。</li><li>`ALL_OBJECTS`</li><li>`OF_EACH_OBJECT` </li>|
#|actions {必填}|object[]| 条件满足是要执行的操作。|
##|subject_type {必填}|string| 操作类型。枚举值: `TURN_ON`(打开), `TURN_OFF`(关闭), `MESSAGE`(发送信息), `DAILY_BUDGET`（日预算）, `LIFETIME_BUDGET`（总预算）, `BID`（出价）。|
##|action_type|string| `INCREASE`（增加）, `DECREASE`（降低）, `ADJUST_TO`（调整至）。|
##|value_type|string|`EXACT`（绝对值）, `PERCENT`（百分比）。|
##|value{+条件必填}|object|预算的值。<br>当`subject_type`=`DAILY_BUDGET`, `LIFETIME_BUDGET` 或 `BID`时必填。|
###|value {+条件必填}|float|要提高，降低，或调整至的预算。<ul><li>若 `action_type` =`INCREASE` 或 `DECREASE`，取值范围：[0.01, 1000000000000]。</li><li>若`action_type` =`ADJUST_TO`：</li><ul><li>当 `dimension`=`CAMPAIGN`时，取值范围：[50, 1000000000000]。</li><li>当`dimension`=`ADGROUP`时，取值范围： [20, 1000000000000]。</li></ul></ul>|
###|limit {+条件必填}|float|最大预算 (若`action_type` =`INCREASE`) 或最小预算 （ 若`action_type` =`DECREASE`）。<br>当 `action_type` =`INCREASE` 或`DECREASE`时必填。<ul><li>当`dimension`=`CAMPAIGN`，取值范围： [50, 1000000000000]。</li><li>当`dimension`=`ADGROUP`，取值范围： [20, 1000000000000]。</li></ul><br>若`action_type`=`ADJUST_TO`， 则无需传入此参数。|
##|frequency_info|object| 频率设置。当`subject_type`为`DAILY_BUDGET`，`LIFETIME_BUDGET`或者`BID`时可用。|
###|type|string|枚举值：<ul><li>`ONLY_ONCE`（只一次）</li><li> `ONCE_IN_24_H`（每24小时一次）</li><li> `ONCE_IN_48_H`（每48小时一次）</li><li> `ONCE_IN_1_W`（每周一次）</li><li> `CUSTOM`（自定义）</li>|
###|custom_frequency_type|string|自定义频率类型。仅在`type`为`CUSTOM`时生效. <li> `N_MINTUE_Y_TIMES`（N分钟内Y次）</li><li> `N_HOUR_Y_TIMES`（N小时内Y次）</li><li> `N_DAY_Y_TIMES`（N天内Y次）</li>|
###|time|number|`custom_frequency_type`中的N。|
###|count|number|`custom_frequency_type`中的Y。|
#|notification {必填}|object| 通知设置。|
##|notification_type {必填}| string|通知类型。枚举值： <ul><li>`TASK_FINISH`: 在任务完成时发送通知。本选项只能用于`MESSAGE`（发送信息）这一操作类型。</li><li>`ANY_CHANGES`：如果操作类型不是`MESSAGE`（发送信息），但是您想在执行相应的操作同时收到通知，那么可以选该选项。</li><li>`NOT_NOTIFICATION`: 无需通知。</li></ul>|
##|email_setting|object|邮件通知设置。 |
###|notification_period|string|枚举值：<ul><li>`EVERY_TIME`</li><li>`TIME_SCHEDULE`: 在指定时间发送所有通知。|
###|email_exec_time|string[]|当`notification_period`为`TIME_SCHEDULE`时必填。邮件通知的发送时间，例如“12：00”。|
###|no_result_notification|boolean|若不传，将默认为false，代表当无结果时，不会发送任何邮件。|
###|mute_option|string|选择是否要静止当天的邮件通知。枚举值：<ul><li>`MUTE`</li><li>`UNMUTE`</li></ul>|
#|rule_exec_info {必填}|object| 规则运行设置。|
##|exec_time_type {必填}|string| 运行时间。枚举值： <ul><li>`PER_HALF_HOUR`: 每半小时运行一次。</li><li>`CUSTOM`: 规则会在特定时间运行(通过`exec_time`字段设置)。</li><li>`HALF_HOUR_IN_SPECIFIC_TIME_PERIOD`: 规则会在指定的星期内的指定时间段里每30分钟运行一次。<li>`SPECIFIC_TIME_ACCURATE_ONCE`: 规则会在特定时间运行一次 (通过`exec_time`字段设置)。</li></ul>|
##|exec_time|string| 如果运行时间设为 `CUSTOM`或`SPECIFIC_TIME_ACCURATE_ONCE`，使用本字段来设置具体的运行时间。<br>格式：<ul><li>当`exec_time_type`设置为`CUSTOM`时，格式为"HH:MM"。 例如：`12:00`。<li>当`exec_time_type`设置为`SPECIFIC_TIME_ACCURATE_ONCE`时，格式为"YYYY-MM-DD HH:MM"。例如：`2023-04-20 04:20`。</li></ul><span style="color:darkred"><b>注意</b></span>: 如果`exec_time_type`设置为`SPECIFIC_TIME_ACCURATE_ONCE`，不能超过当前时间一年。|
##|time_period_info|object[]|当`exec_time_type`为`HALF_HOUR_IN_SPECIFIC_TIME_PERIOD`时生效。用户可以通过`start_time`（开始时间）, `end_time`（结束时间）, `date_type`（日期类型）以及`num`来定义该字段。|
###|num{+条件必填}|integers[]| 当`date_type`为`WEEK`或`MONTH`时必填。数字表示一周或一个月中的某一天。<ul><li>当`date_type`为`WEEK`时，该字段取值范围为[1, 7]，即周一至周日。<li>当`date_type`为`MONTH`时，该字段取值范围为[1, 28]，即该月的1日至28日。</li></ul>|
###|start_time|string| 开始时间，例如 "12:00:00"。|
###|end_time|string| 结束时间，例如 "12:00:00"。|
###|date_type|string|日期类型。枚举值：`DAY`，`WEEK`，`MONTH`。|
#|tzone|string|用户时区。在创建/修改规则时，需与`mute_option`组合使用。获取目前可接受的时区代码，可参阅[时区信息](https://ads.tiktok.com/marketing_api/docs?id=1737586324313089)。|
#|name {必填}|string| 规则名。|
|lang|string| 报错信息使用的语言。枚举值：`ZH` (简体中文), `EN` (英语), `JA` (日语)。默认值：`EN`。|
示例
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/optimizer/rule/create/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data '{
"advertiser_id": "{{advertiser_id}}",
"rules": [
{
"apply_objects": [
{
"dimension": "CAMPAIGN",
"dimension_ids": [],
"pre_condition_type": "ALL_INACTIVE_CAMPAIGN"
}
],
"conditions": [
{
"subject_type": "CLICK",
"range_type": "LIFETIME",
"match_type": "GT",
"values": [
"0"
]
}
],
"actions": [
{
"subject_type": "MESSAGE"
}
],
"notification": {
"notification_type": "TASK_FINISH"
},
"rule_exec_info": {
"exec_time_type": "CUSTOM",
"exec_time": "12:00"
},
"name": "[API]Automated Rule-example"
}
]
}'
(/code)
values字段的校验规则
传入的subject_type不同，values字段的校验规则也不同。请根据相应的规则填入values字段，否则系统会报错。具体校验规则见下表。
|<code>subject_type</code>{50%}|<code>values</code>校验规则{50%}|
|---|---|---|
|NAME|字符串长度区间: (0,512]|
|COST<br>CPA<br>NOT_REAL_TIME_CPA<br>CPM<br>CPC<br>COST_PER_RESULT|精度：取决于广告主账户的币种对应的精度(请参考[不同币种对应的精度](https://ads.tiktok.com/marketing_api/docs?id=1772544628718594)，了解详细信息）<br>取值范围：[0,100000000]|
|DAILY_BUDGET_SPENDING_RATE<br>LIFETIME_BUDGET_SPENDING_RATE<br>CVR<br>CVR_SKAN<br>NOT_REAL_TIME_CVR<br>CTR<br>RESULT_RATE|精度：0.01<br>取值范围： [0,100]|
|IMPRESSION<br>CLICK<br>CONVERSION<br>CONVERSION_SKAN<br>NOT_REAL_TIME_CONVERSION<br>RESULT|精度：1<br>取值范围：[0,10000000000]|
|ROAS_PURCHASE<br>ROAS_IMPRESSION_ADS<br>ROAS_PURCHASE_SKAN<br>ROAS_COMPLETE_PAYMENT<br>ROAS_PURCHASES_ONSITE|精度：0.01<br>取值范围：[0,100000]|
返回
|字段|类型|描述|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|request_id |string|请求的日志id，唯一标识一个请求。|
|data |object|返回数据。|
#|rule_ids |string[]| 已创建或修改的规则ID列表。|
示例
(code JSON JSON)
{
"code": 0,
"message": "OK",
"request_id": "2021072906384801024503714429014AE4",
"data": {
"rule_ids": [
"6984697088064290818"
]
}
}
(/code)