评估参数

规则的 evaluation_spec 主要目的是：确定此规则应对哪些对象执行操作。evaluation_type 确定评估方式的类型，并具有以下选项：

评估类型	描述
`SCHEDULE`	用于排期类规则
`TRIGGER`	用于触发类规则

evaluation_spec 中包含一个 filters 数组，您可以通过该数组进一步缩小匹配对象清单的范围。例如，您可以针对广告、广告组和广告系列的元数据和成效分析指标构建筛选条件。所有筛选条件都使用 AND 运算符一起进行评估。

filters 数组中包含一个由筛选条件对象组成的清单。这些对象都是包含 field、value 和 operator 键的字典：

筛选条件对象键描述

筛选条件对象键	描述
`field`	必要。筛选条件字段，例如成效分析数据或元数据
`value`	必要。此字段的静态筛选条件值
`operator`	必要。此字段的逻辑运算符

field

必要。

筛选条件字段，例如成效分析数据或元数据

value

必要。

此字段的静态筛选条件值

operator

必要。

此字段的逻辑运算符

每个筛选条件都有一系列支持的逻辑运算符。SCHEDULE 和 TRIGGER 规则支持的逻辑运算符如下：

逻辑运算符	值（示例）
`GREATER_THAN`	数字 (100)
`LESS_THAN`	数字 (100)
`EQUAL`	数字 (100)
`NOT_EQUAL`	数字 (100)
`IN_RANGE`	元组 ([100, 200])
`NOT_IN_RANGE`	元组 ([100, 200])
`IN`	清单 (["1", "2", "3"])
`NOT_IN`	清单 (["1", "2", "3"])
`CONTAIN`	字符串 ("ABC")
`NOT_CONTAIN`	字符串 ("ABC")
`ANY`	清单 ([1, 2, 3])
`ALL`	清单 ([1, 2, 3])
`NONE`	清单 ([1, 2, 3])

对于 TRIGGER 评估类型，evaluation_spec 需要有一个 trigger。该 trigger 包含一个 type 和一个底层 filters 参数。filters 参数可以是 field、value 和 operator。

该 trigger 将动态地确定我们是否应该评估一项规则，您只能提供一个 trigger。详情请参阅触发类规则。

在下文中，我们定义了您可以使用的一些特殊筛选条件和几组常规筛选条件。

特殊筛选条件

`time_preset`

time_preset 筛选条件确定要汇总哪个时间段的成效分析指标。目前，我们仅支持使用一个 time_preset。该筛选条件适用于此规则中的所有统计数据筛选条件，包括触发条件中使用的统计数据筛选条件（如存在）。

time_preset 支持的唯一运算符是 EQUAL，而且只要存在任何成效分析筛选条件或触发条件，time_preset 便是必要项。触发类规则仅支持包括 TODAY 的时间预设，因为该值可执行实时评估。

规则的时间预设可以与其他界面不同。此处的一些时间预设包括今天的数据。这是因为如果规则运行的频率超过每天一次，今天的数据至关重要。对于其他界面，LAST_N_DAYS 的预设值通常不包括今天的数据。详情请参阅下文。

{
  "field": "time_preset",
  "value": "TODAY",
  "operator": "EQUAL"
}

时间预设值	描述
`LIFETIME`	对象的投放期
`TODAY`	当天，从广告账户所在时区的午夜开始计算
`LAST_2_DAYS`	`YESTERDAY` 和 `TODAY`
`LAST_3_DAYS`	过去整整 2 天和 `TODAY`
`LAST_7_DAYS`	过去整整 6 天和 `TODAY`
`LAST_14_DAYS`	过去整整 13 天和 `TODAY`
`LAST_28_DAYS`	过去整整 27 天和 `TODAY`
`LAST_30_DAYS`	过去整整 29 天和 `TODAY`
`THIS_MONTH`	本月，包含 `TODAY`
`THIS_WEEK_MON_TODAY`	本周，以周一作为一周的第一天，包含 `TODAY`
`THIS_WEEK_SUN_TODAY`	本周，以周日作为一周的第一天，包含 `TODAY`
`YESTERDAY`	过去整整 1 天，不包含 `TODAY`
`LAST_2D`	过去整整 2 天，不包含 `TODAY`
`LAST_3D`	过去整整 3 天，不包含 `TODAY`
`LAST_7D`	过去整整 7 天，不包含 `TODAY`
`LAST_14D`	过去整整 14 天，不包含 `TODAY`
`LAST_28D`	过去整整 28 天，不包含 `TODAY`
`LAST_30D`	过去整整 30 天，不包含 `TODAY`
`LAST_ND_14_8`	14 天前到 7 天前，适用于广告花费回报 (ROAS)
`LAST_ND_30_8`	30 天前到 7 天前，适用于广告花费回报 (ROAS)
`LAST_ND_60_8`	60 天前到 7 天前，适用于广告花费回报 (ROAS)
`LAST_ND_120_8`	120 天前到 7 天前，适用于广告花费回报 (ROAS)
`LAST_ND_180_8`	180 天前到 7 天前，适用于广告花费回报 (ROAS)
`LAST_ND_LIFETIME_8`	从开始投放到 7 天前，适用于广告花费回报 (ROAS)
`LAST_ND_60_29`	60 天前到 28 天前，适用于广告花费回报 (ROAS)
`LAST_ND_120_29`	120 天前到 28 天前，适用于广告花费回报 (ROAS)
`LAST_ND_180_29`	180 天前到 28 天前，适用于广告花费回报 (ROAS)
`LAST_ND_LIFETIME_29`	从开始投放到 28 天前，适用于广告花费回报 (ROAS)

`attribution_window`

attribution_window 筛选条件确定要汇总哪个回溯窗口期的成效分析指标。详情请参阅《成效分析 API》文档的统计时间窗部分。

目前，我们仅支持使用一个 attribution_window，该筛选条件适用于规则中的所有统计数据筛选条件。attribution_window 支持的唯一运算符是 EQUAL，仅排期类规则支持该筛选条件。

无论是否指定，attribution_window 唯一支持的 value 是 ACCOUNT_DEFAULT。

{
  "field": "attribution_window",
  "value": "ACCOUNT_DEFAULT",
  "operator": "EQUAL"
}

统计时间窗值	描述
`ACCOUNT_DEFAULT`	使用账户层级统计时间窗设置

元数据筛选条件

通过元数据筛选条件，您可以根据对象的元数据字段当前状态来筛选对象。这些元数据筛选条件还支持多层级筛选，这意味着您可以使用前缀对对象的父对象或祖父对象应用元数据筛选条件。这不会影响其他筛选条件。成效分析筛选条件仍适用于正常对象。

排期类规则支持所有元数据筛选条件，但触发类规则仅支持一部分元数据筛选条件。

例如，如果您想将一项规则应用到目标为 WEBSITE_CLICKS 的广告系列中的广告组，可添加以下两个筛选条件：

 "filters" : [
  {
    "field": "entity_type",
    "value": "ADSET",
    "operator": "EQUAL",
  },
  {
    "field": "campaign.objective",
    "value": "WEBSITE_CLICKS",
    "operator": "EQUAL"
  }
]

触发类规则和排期类规则支持的元数据筛选条件

元数据字段	描述
`id`*	将应用此规则的特定静态对象。支持的前缀：广告、广告组、广告系列支持的值：`int`、`array(int)` 支持的运算符：`EQUAL`、`IN`、`NOT_IN`
`entity_type`*	将应用此规则的对象层级。支持的前缀：无支持的值：`AD`、`ADSET`、`CAMPAIGN` 支持的运算符：`EQUAL`
`name`	对象的名称，部分或完全匹配。支持的前缀：广告、广告组、广告系列支持的值：`string` 支持的运算符：`EQUAL`、`CONTAIN`、`NOT_CONTAIN`
`adlabel_ids`	对象的广告标签编号。支持的前缀：广告、广告组、广告系列支持的值：`array(int)` 支持的运算符：`ANY`、`ALL`、`NONE`
`objective`	对象所在广告系列的目标。支持的前缀：广告系列支持的值：`array(APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LINK_CLICKS, ...)` 支持的运算符：`IN`、`NOT_IN`
`start_time`	对象开始投放的时间（新纪元时间）。支持的前缀：广告组、广告系列支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`stop_time`	对象停止投放的时间（新纪元时间）。支持的前缀：广告组、广告系列支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`
`buying_type`	对象所在广告系列的购买类型。支持的前缀：广告系列支持的值：`array(AUCTION, FIXED_CPM, RESERVED)` 支持的运算符：`IN`、`NOT_IN`
`billing_event`	对象所在广告组的付费事件。支持的前缀：广告组支持的值：`array(APP_INSTALLS, LINK_CLICKS, IMPRESSIONS, ...)` 支持的运算符：`IN`、`NOT_IN`
`optimization_goal`	对象所在广告组的优化目标。支持的前缀：广告组支持的值：`array(APP_INSTALLS, LINK_CLICKS, IMPRESSIONS, ...)` 支持的运算符：`IN`、`NOT_IN`
`is_autobid`	对象所在广告组的自动竞价状态。支持的前缀：广告组支持的值：`array(bool)` 支持的运算符：`IN`、`NOT_IN`
`daily_budget`	对象所在广告组的单日预算。支持的前缀：广告组支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`lifetime_budget`	对象所在广告组的总预算。支持的前缀：广告组支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`spend_cap`	对象所在广告系列的花费上限。支持的前缀：广告系列支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`bid_amount`	对象的竞价金额。支持的前缀：广告、广告组支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`created_time`	对象的创建时间（新纪元时间）。支持的前缀：广告、广告组、广告系列支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`updated_time`	对象的更新时间（新纪元时间）。支持的前缀：广告、广告组、广告系列支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`

仅排期类规则支持的元数据筛选条件

元数据字段	描述
`effective_status`**	对象的有效状态。支持的前缀：广告、广告组、广告系列支持的值：`array(ACTIVE, PAUSED, ADSET_PAUSED, CAMPAIGN_PAUSED, PENDING_REVIEW, ARCHIVED, DELETED, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO)` 支持的运算符：`IN`、`NOT_IN`
`placement.page_types`	对象所在广告组版位所属的公共主页的类型。支持的前缀：广告组支持的值：`array(DESKTOPFEED, HOME, INSTAGRAMSTREAM, INSTAGRAMSTORY, ...)` 支持的运算符：`ANY`、`ALL`、`NONE`
`budget_reset_period`	对象所在广告组的预算重置时间间隔。支持的前缀：广告组支持的值：`array(DAY, LIFETIME)` 支持的运算符：`IN`、`NOT_IN`
`hours_since_creation`	对象从 `created_time` 开始存在的小时数。支持的前缀：广告、广告组、广告系列支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`estimated_budget_spending_percentage`	截至广告组排期结束时预计花费的广告组预算百分比。该选项使用的机制与我们广告组预算重调功能的机制相同，因此适用于任何预算类型，但要求每天投放 10 小时。支持的前缀：广告组支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`audience_reached_percentage`	广告组的覆盖人数占受众规模的预估百分比。支持的前缀：广告组支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`active_time`	从对象的 `ACTIVE` 状态生效开始经过的秒数。如果对象当前的状态不是 `ACTIVE`，该字段将返回 `0`。支持的前缀：广告、广告组、广告系列支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`
`current_time`	当前时间（新纪元时间）。支持的前缀：无支持的值：`int` 支持的运算符：`GREATER_THAN`、`LESS_THAN`、`IN_RANGE`、`NOT_IN_RANGE`

`entity_type` 和 `id`

对于评估类型为 SCHEDULE 或 TRIGGER 的每项规则，您必须指定一个 entity_type 或 id 筛选条件。

如果您指定 entity_type 筛选条件，这会确定要应用该规则的动态对象层级。例如，如果 entity_type 是 AD，该规则会自动评估添加到该广告账户的每个新广告。无论您何时创建该规则，都会发生这种情况。通过指定 id 筛选条件，该规则将仅应用于对象的静态清单。

如果您指定一个没有前缀的 id 筛选条件，我们会自动计算要应用该规则的对象层级。例如，如果您想将一项规则应用到广告 [123, 456]，您仅需要使用一个 field 为 id、value 为 [123, 456] 以及 operator 为 IN 的筛选条件。在这种情况下，您不需要提供 entity_type，因为您提供了对象的初始静态清单，我们可以利用这些对象来计算对象层级。

您可以将 entity_type 和 id 与多层级筛选结合使用。例如，如果您想将一项规则应用到某些指定广告组下的所有广告，可使用一个 entity_type 为 AD 的筛选条件和一个包含这些指定广告组的 adset.id 筛选条件。

默认情况下，如果您不指定 effective_status 筛选条件，我们在使用该规则进行评估时就会隐式添加 effective_status 筛选条件。

对于作用于投放中对象的所有执行类型，该默认筛选条件的 operator 为 IN，value 为 ['ACTIVE', 'PENDING_REVIEW']。这意味着，该规则仅会评估已经投放或即将投放的对象。对于不作用于投放中对象的执行类型 (UNPAUSE)，我们将添加 operator 为 NOT_IN 和 value 为 ['DELETED', 'ARCHIVED'] 的筛选条件。该默认筛选条件是我们执行类型的一个内部优化措施。

成效分析筛选条件

我们根据成效分析筛选条件，对成效分析 API 返回的给定 time_preset 的当前值进行评估。这些筛选条件直接应用于对象清单或对象层级，且不支持多层级筛选。所有成效分析筛选条件都支持以下运算符：GREATER_THAN、LESS_THAN、EQUAL、IN_RANGE、NOT_IN_RANGE。

此处显示的单位以市场营销 API 中的货币基本单位为依据。例如，美元的基本单位是美分，这意味着值为 1,000 的花费等于 10.00 美元。

有关下方每个字段的描述，请参阅成效分析 API 文档。排期类规则支持所有这些筛选条件。

下方是成效分析筛选条件清单以及这些筛选条件是否受触发类规则支持的情况：

成效分析字段	是否受触发类规则支持？
`mobile_app_purchase_roas`（示例）	否
`website_purchase_roas`（示例）	否
`impressions`	是
`unique_impressions`	是
`clicks`	是
`unique_clicks`	是
`spent`	是
`results`	是
`cost_per`	是
`cpc`	是
`cpm`	是
`ctr`	是
`cpa`	是
`cpp`	是
`reach`	是
`frequency`	是
`leadgen`	是
`link_ctr`	是
`cost_per_unique_click`	是
`result_rate`	是
`mobile_app_install`	是
`cost_per_mobile_app_install`	是
`app_custom_event`	是
`app_custom_event.fb_mobile_achievement_unlocked`	是
`app_custom_event.fb_mobile_activate_app`	是
`app_custom_event.fb_mobile_add_payment_info`	是
`app_custom_event.fb_mobile_add_to_cart`	是
`app_custom_event.fb_mobile_add_to_wishlist`	是
`app_custom_event.fb_mobile_complete_registration`	是
`app_custom_event.fb_mobile_content_view`	是
`app_custom_event.fb_mobile_initiated_checkout`	是
`app_custom_event.fb_mobile_level_achieved`	是
`app_custom_event.fb_mobile_purchase`	是
`app_custom_event.fb_mobile_rate`	是
`app_custom_event.fb_mobile_search`	是
`app_custom_event.fb_mobile_spent_credits`	是
`app_custom_event.fb_mobile_tutorial_completion`	是
`app_custom_event.other`	是
`cost_per_mobile_achievement_unlocked`	是
`cost_per_mobile_activate_app`	是
`cost_per_mobile_add_payment_info`	是
`cost_per_mobile_add_to_cart`	是
`cost_per_mobile_add_to_wishlist`	是
`cost_per_mobile_complete_registration`	是
`cost_per_mobile_content_view`	是
`cost_per_mobile_initiated_checkout`	是
`cost_per_mobile_level_achieved`	是
`cost_per_mobile_purchase`	是
`cost_per_mobile_rate`	是
`cost_per_mobile_search`	是
`cost_per_mobile_spent_credits`	是
`cost_per_mobile_tutorial_completion`	是
`offline_conversion`	否
`offline_conversion.add_payment_info`	否
`offline_conversion.add_to_cart`	否
`offline_conversion.add_to_wishlist`	否
`offline_conversion.complete_registration`	否
`offline_conversion.initiate_checkout`	否
`offline_conversion.lead`	否
`offline_conversion.other`	否
`offline_conversion.purchase`	否
`offline_conversion.search`	否
`offline_conversion.view_content`	否
`cost_per_offline_conversion`	否
`cost_per_offline_other`	否
`offsite_conversion`	是
`offsite_conversion.fb_pixel_add_payment_info`	是
`offsite_conversion.fb_pixel_add_to_cart`	是
`offsite_conversion.fb_pixel_add_to_wishlist`	是
`offsite_conversion.fb_pixel_complete_registration`	是
`offsite_conversion.fb_pixel_initiate_checkout`	是
`offsite_conversion.fb_pixel_lead`	是
`offsite_conversion.fb_pixel_purchase`	是
`offsite_conversion.fb_pixel_search`	是
`offsite_conversion.fb_pixel_view_content`	是
`offsite_conversion.fb_pixel_other`	是
`cost_per_add_payment_info_fb`	是
`cost_per_add_to_cart_fb`	是
`cost_per_add_to_wishlist_fb`	是
`cost_per_complete_registration_fb`	是
`cost_per_initiate_checkout_fb`	是
`cost_per_lead_fb`	是
`cost_per_purchase_fb`	是
`cost_per_search_fb`	是
`cost_per_view_content_fb`	是
`link_click`	是
`cost_per_link_click`	是
`like`	是
`offsite_engagement`	是
`post`	是
`post_comment`	是
`post_engagement`	是
`cost_per_post_engagement`	否
`post_like`	是
`post_reaction`	是
`view_content`	是
`video_play`	是
`vote`	是
`unique_clicks`	否
`reach`	否
`lifetime_impressions`	否
`lifetime_spent`	否
`today_spent`	否
`yesterday_spent`	否

高级筛选条件

您可以根据上方成效分析筛选条件和元数据筛选条件自定义和获取高级字段。详情请参阅高级评估参数筛选条件。

高级筛选条件支持以下运算符：GREATER_THAN、LESS_THAN、EQUAL、IN_RANGE、NOT_IN_RANGE。仅排期类规则支持高级筛选条件。

对于一些最常用的高级筛选条件，我们支持使用别名作为筛选条件：

高级字段别名	来源
`daily_ratio_spent`	`today_spent / adset.daily_budget`
`lifetime_ratio_spent`	`lifetime_spent / adset.lifetime_budget`

评估参数

特殊筛选条件

time_preset

attribution_window

元数据筛选条件

触发类规则和排期类规则支持的元数据筛选条件

仅排期类规则支持的元数据筛选条件

entity_type 和 id

成效分析筛选条件

高级筛选条件

`time_preset`

`attribution_window`

`entity_type` 和 `id`