更新规则
您可以使用本接口更新规则。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径| /v1.2/app/track/| /v1.3/app/track/|
|请求参数类型|advertiser_id: number<br>dimensions_id: number[]<br>rule_id: number |advertiser_id: string<br>dimensions_id: string[]<br>rule_id: string |
|返回参数类型|rule_ids: number[]|rule_ids`: string[]|
## 请求
**地址** <https://business-api.tiktok.com/open_api/v1.3/optimizer/rule/update/>
**方法** POST
**Header**
```xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许格式：`application/json`。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|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`字段的校验规则也不同。欲了解具体校验规则，请参考[`values`字段的校验规则](https://ads.tiktok.com/marketing_api/docs?rid=7xusz43oh3h&id=1738767670852610#item-link-values字段的校验规则)。|
##|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|<ul><li> 当 `action_type`为 `INCREASE`（增加）或 `DECREASE`（降低）时, 用户可以通过`use_limit` 和 `limit`来定义最大和最小值。</li><li>当 `action_type`为 `ADJUST_TO`时, 无需传入`use_limit` 和 `limit`。</li></ul><br>例如，若 `action_type`为`INCREASE`，`value_type` 为 `PERCENT`, 且 `value` 对象为`{"value": 20.0, "use_limit":true, "limit": 100.0}`，则当满足条件时，将提高20.0 % 的预算，但不会超过100.0 美元。|
###| value | float | 当 `action_type` 为 `ADJUST_TO` 时生效。 <br><br>要调整到的具体值。 |
###| limit | float | 当 `action_type` 为 `INCREASE` 或 `DECREASE` 时生效。<br><br><ul><li>若 `action_type` 为 `INCREASE`，本字段代表最大值限制。</li><li>若 `action_type` 为 `DECREASE`，本字段代表最小值限制。</li></ul> <br>若您传入本字段，您需同时将 `use_limit` 设置为 `true` 。 |
###| use_limit | boolean | 当 `action_type` 为 `INCREASE` 或 `DECREASE` 时生效。<br><br>是否设置最大值或最小值限制。 |
##|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)。|
#|rule_id {必填}|string|规则ID。|
#|name {必填}|string| 规则名。|
|lang|string| 报错信息使用的语言。枚举值：`ZH` (简体中文), `EN` (英语), `JA` (日语)。默认值：`EN`。|
示例
(code JSON JSON)
{
"advertiser_id":75960823018,
"rules":[
{
"apply_objects":[
{
"dimension":"CAMPAIGN",
"dimension_ids":[1694011873852465],
"pre_condition_type":"SELECTED"
}
],
"conditions":[
{
"subject_type":"CLICK",
"range_type":"LIFETIME",
"match_type":"GT",
"values":["1"]
}
],
"actions":[{
"subject_type":"MESSAGE"
}],
"notification":{
"notification_type":"TASK_FINISH"
},
"rule_exec_info":{
"exec_time_type":"PER_HALF_HOUR",
"exec_time":""
},
"name":"[API]Automated Rule--example-update",
"rule_id":6984697088064290818
}
]
}
(/code)
返回
|字段|类型|描述|
|---|---|---|
|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": "202107290645040102450631993207A638",
"data": {
"rule_ids": [
6984697088064290818
]
}
}
(/code)