評価の設定

ルールの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])

evaluation_specには、評価タイプTRIGGERのtriggerが必要です。トリガーには、タイプと基礎となるフィルター仕様が含まれています。フィルター仕様として使用できるのは、field、value、operatorです。

トリガーにより、ルールが評価されるかどうかが動的に決定されます。設定できるのは1つだけです。詳しくは、トリガーベースのルールをご覧ください。

使うことのできる特殊なフィルターと一般的なフィルターグループのいくつかについて、その定義を以下に示します。

特殊フィルター

`time_preset`

time_presetフィルターは、インサイト指標集計の対象となる期間を決定します。現在のところ、1つのtime_presetだけを指定できます。これは、トリガーに使われるものも含め、ルールのすべての統計フィルターに適用されます。

EQUALでサポートされる演算子はtime_presetだけです。これは、インサイトのフィルターまたはトリガーが存在する場合には必須です。トリガーベースのルールでサポートされるのは、TODAYを含む時間プリセットだけです(リアルタイム評価が実行されるため)。

ルールの時間プリセットの動作は、インターフェイスにより異なることがあります。ここに示されている時間プリセットの一部には、今日のデータが含まれます。実行間隔が1日より短いルールの場合、今日のデータが重要になるからです。その他のインターフェイスでは、一般にLAST_N_DAYSのプリセット値に今日のデータは含まれません。詳しくは、以下の説明をご覧ください。

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

時間プリセット値	説明
`LIFETIME`	オブジェクトのライフタイム
`TODAY`	広告アカウントのタイムゾーンで深夜0時から始まる現在日
`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`	`TODAY`を除く前日
`LAST_2D`	`TODAY`を除く過去2日間
`LAST_3D`	`TODAY`を除く過去3日間
`LAST_7D`	`TODAY`を除く過去7日間
`LAST_14D`	`TODAY`を除く過去14日間
`LAST_28D`	`TODAY`を除く過去28日間
`LAST_30D`	`TODAY`を除く過去30日間
`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フィルターは、インサイト指標集計の対象となるルックバック時間枠を決定します。詳しくは、インサイトのドキュメントの、アリビューションウィンドウに関する部分をご覧ください。

現在のところ指定できるattribution_windowは1つだけで、それがルール内のすべての統計フィルターに適用されます。attribution_windowでサポートされる演算子はEQUALだけで、これはスケジュールベースのルールでのみサポートされています。

任意でattribution_windowに使用できるvalueは、ACCOUNT_DEFAULTだけです。

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

アトリビューションウィンドウの値	説明
`ACCOUNT_DEFAULT`	アカウントレベルのアトリビューションウィンドウの設定を使用します

メタデータフィルター

メタデータフィルターを使うと、メタデータフィールドの現在の状態に基づいてオブジェクトをフィルタリングできます。複数レベルのフィルタリングがサポートされています。つまり、プレフィックスを使うことにより、メタデータフィルターをオブジェクトの親または親の親に適用することができます。これは他のフィルターには影響しません。インサイトフィルターは、引き続き通常のオブジェクトに適用されます。

スケジュールルールではすべてのメタデータフィルターがサポートされていますが、トリガールールでサポートされるのは一部だけです。

例えば、目的がWEBSITE_CLICKSである広告キャンペーンの広告セットにルールを適用する場合、以下の2つのフィルターを含めることができます。

 "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`	オブジェクトの広告ラベルID。サポートされるプレフィックス: 広告、広告セット、広告キャンペーンサポートされる値:`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`	オブジェクトの広告セットの1日当たりの予算。サポートされるプレフィックス: 広告セットサポートされる値:`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`	スケジュール終了までに消費される広告セットの予算の推定割合(パーセント)。広告セットの予算のリバランス機能と同じメカニズムが使用されるため、どの予算タイプでも機能しますが、1日当たり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]にルールを適用する場合は、1つのフィルターフィールドid、値[123, 456]、演算子INです。この場合、オブジェクトの初期静的リストが指定されており、それに基づいてオブジェクトレベルを計算できるので、entity_typeは不要です。

entity_typeとidは、複数レベルのフィルタリングと組み合わせて使うことができます。例えば、指定したいくつかの広告セットに含まれるすべての広告にルールを適用する場合、entity_typeフィルターをADとし、指定した広告セットをadset.idフィルターに設定します。

デフォルトでは、effective_statusフィルターを指定しない場合、ルールの評価時に暗黙的にeffective_statusフィルターが追加されます。

アクティブなオブジェクトを対象とするどの実行タイプについても、このデフォルトのフィルターの演算子はIN、値は['ACTIVE', 'PENDING_REVIEW']になります。つまり、ルールで評価するオブジェクトは、配信が現在アクティブであるか、今後アクティブになる予定のものだけです。アクティブなオブジェクトを対象としない実行タイプの場合(UNPAUSE)、演算子NOT_IN、値['DELETED', 'ARCHIVED']でこのフィルターが追加されます。デフォルトのフィルターは、実行タイプに対して内部最適化されます。

インサイトフィルター

インサイトフィルターは、指定されたtime_presetについてインサイトAPIから返される現在の値に対して評価されます。これらのフィルターは、オブジェクトのリストまたはレベルに対して直接適用されます。複数レベルのフィルタリングはサポートされていません。すべてのインサイトフィルターで、演算子GREATER_THAN、LESS_THAN、EQUAL、IN_RANGE、NOT_IN_RANGEがサポートされています。

ここでの表記に使われている単位は、マーケティングAPIの通貨ベースに基づいています。例えばUSDの場合、ベース単位はセントです。つまり、費用の値が1000なら、$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`