← 返回目录
📁 API Reference › Automated Rules

根据条件获取规则

您可以使用本接口根据条件获取规则。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径|/v1.2/optimizer/rule/list/| /v1.3/optimizer/rule/list/| |请求参数类型|advertiser_id: number|advertiser_id: string| |返回参数类型|dimension_ids: number[]<br>task_exec_id: number<br>rule_id: number|dimension_ids: string[]<br>task_exec_id: string<br>rule_id: string| |废弃返回参数|/|recipients`|


## 请求

**地址** <https://business-api.tiktok.com/open_api/v1.3/optimizer/rule/list/>

**方法** GET

**Header**

```xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许格式：`application/json`。|

参数

|字段|类型|描述|
|---|---|---|
|advertiser_id {必填}|string| 广告主ID。 |
|filtering|object[]|筛选条件。|
#|status|string| 规则的状态。枚举值：<ul><li>`ON`：已启用。</li><li>`OFF`：已关闭。</li><li>`DELETED`：已删除。</li></ul>|
#|rule_info|string[]|规则ID或规则名称。|
#|data_dimension|string|枚举值：`CAMPAIGN`, `ADGROUP`, `AD`。|
|tzone|string|若传入，返回中所有的时间信息 (`create_datetime`, `email_exec_time`, `check_datetime`, `exec_datetime`)将以用户定义的时区呈现。获取当前可接受的时区，请参阅[时区信息](https://ads.tiktok.com/marketing_api/docs?id=1737586324313089)。|
|page|number|当前页数。默认：1|
|page_size|number|页面大小。默认：10|

示例

(code JSON JSON)
{
    "advertiser_id": "75960823018",
    "filters":[
        {
            "filter_type":"RULE_INFO",
            "filter_input":["6984697088064290818"]
        }
    ],
    "page":1,
    "page_size":10
}
(/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|返回数据|
#|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>|
###|bind_type|string|规则绑定类型。枚举: `BIND`(绑定), `UNBIND`(解除绑定)|
##|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`</li><li>`OPTIMIZATION_GOAL`</li><li>`OBJECTIVE`</li><li>`NAME`</li><li>`DAYS_SINCE_CREATION`</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| 条件的匹配类型（操作符），用于连接指标和具体的值。枚举值: <li>`GT` (大于)</li> <li>`LT` (小于)</li> <li>`BETWEEN`(在两者之间)</li><li>`MATCH`(匹配）</li><li>`CONTAINS`</li><li>`NOT_CONTAINS`</li><li>`START_WITH`</li><li>`END_WITH`</li><li>`STRING_EQUAL`|
###|values|string[]| 条件的值。 |
###|calculation_type|string|枚举值：</li><li>ALL_OBJECTS</li><li>OF_EACH_OBJECT </li>|
##|action |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|当 `action_type`为 `INCREASE`（增加）或 `DECREASE`（降低）时, 用户可以通过`use_limit` 和 `limit`来定义最大和最小值。当 `action_type`为 `ADJUST_TO`时, 无需传入`use_limit` 和 `limit`。|
###|frequency_info|object| 频率设置|
####|type|string|<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，代表当无结果时，不会发送任何邮件。|
##|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>|
###|time_period_info|object[]|当`exec_time_type`为`HALF_HOUR_IN_SPECIFIC_TIME_PERIOD`时生效。用户可以通过`start_time`（开始时间）, `end_time`（结束时间）, `date_type`（日期类型）以及`num`来定义该字段。|
####|num|integers[]| 数字表示一周或一个月中的某一天。<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`。|
##|last_check_result_summary|object| 最后一次规则运行信息。|
###|check_datetime|string| 规则查看日期和时间，基于UTC时区。|
###|exec_datetime|string| 规则运行日期和时间，基于UTC时区。|
###|change_success|number| 更改成功的对象数量。|
###|no_change|number| 未被更改的对象数量。|
###|change_fail|number| 更改失败的对象数量。|
###|task_exec_id|string| 规则执行ID。|
##|rule_id|string|规则ID。|
##|name |string| 规则名。|
##|rule_status|string|规则状态。枚举值：<ul><li>`ON`：已启用。</li><li>`OFF`：已关闭。</li><li>`DELETED`：已删除。</li></ul>|
##|create_datetime|string|规则创建的日期和时间，基于UTC时区。|

示例

(code JSON JSON)
{
    "code": 0,
    "message": "OK",
    "request_id": "2021072906564801024501305243095511",
    "data": {
        "rules": [
            {
                "last_check_result_summary": {
                    "change_success": 1,
                    "change_fail": 0,
                    "exec_datetime": "2021-07-12 06:00:00",
                    "task_exec_id": "6983915767100080129",
                    "not_change": 0,
                    "check_datetime": "2021-07-12 06:00:00"
                },
                "rule_id": "6982553361971232769",
                "notification": {
                    "notification_type": "TASK_FINISH"
                },
                "conditions": [
                    {
                        "subject_type": "CLICK",
                        "match_type": "GT",
                        "values": [
                            "0"
                        ],
                        "range_type": "LIFETIME"
                    }
                ],
                "name": "[API]Automated Rule--20210712-PPE-8",
                "rule_exec_info": {
                    "exec_time_type": "PER_HALF_HOUR",
                    "exec_time": ""
                },
                "create_datetime": "2021-07-12 04:43:56",
                "actions": [
                    {
                        "subject_type": "MESSAGE"
                    }
                ],
                "rule_status": "OFF",
                "apply_objects": [
                    {
                        "dimension_ids": [
                            "1695172996977714"
                        ],
                        "pre_condition_type": "SELECTED",
                        "dimension": "CAMPAIGN",
                        "bind_type": "BIND"
                    }
                ]
            },
            {
                "last_check_result_summary": {
                    "change_success": 0,
                    "change_fail": 0,
                    "exec_datetime": "0001-01-01 00:00:00",
                    "task_exec_id": "0",
                    "not_change": 0,
                    "check_datetime": "0001-01-01 00:00:00"
                },
                "rule_id": "6984697088064290818",
                "notification": {
                    "notification_type": "TASK_FINISH"
                },
                "conditions": [
                    {
                        "subject_type": "CLICK",
                        "match_type": "GT",
                        "values": [
                            "1"
                        ],
                        "range_type": "LIFETIME"
                    }
                ],
                "name": "[API]Automated Rule--example-update",
                "rule_exec_info": {
                    "exec_time_type": "PER_HALF_HOUR",
                    "exec_time": ""
                },
                "create_datetime": "2021-07-29 06:45:04",
                "actions": [
                    {
                        "subject_type": "MESSAGE"
                    }
                ],
                "rule_status": "ON",
                "apply_objects": [
                    {
                        "dimension_ids": [
                            "1694011873852465"
                        ],
                        "pre_condition_type": "SELECTED",
                        "dimension": "CAMPAIGN",
                        "bind_type": "BIND"
                    }
                ]
            }
        ]
    }
}
(/code)
← 获取规则结果获取结果详情 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →