API呼び出し

広告ルールエンジンを使うためのAPI呼び出しの例をご覧ください。

アカウントのルールをすべて読む

curl -G   \
-d 'fields=name,evaluation_spec,execution_spec,status'   \
-d 'access_token=<ACCESS_TOKEN>'   \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library

ルールを読む

curl -G   \
-d 'fields=name,evaluation_spec,execution_spec,status'   \
-d 'access_token=<ACCESS_TOKEN>'   \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>

ルールを更新する

仕様を更新するには、変更されないものも含めてすべてのフィールドに入力します。以下の例では、ルールトリガーを1000インプレッションごとにするよう更新します。ルールのステータスを更新しても仕様の変更は必要ありません。

curl \
-F 'evaluation_spec={
      "evaluation_type": ...,
      "trigger" : {
        "type": "STATS_MILESTONE",
        "field": "impressions",
        "value": 1000,
        "operator": "EQUAL"
      },
      "filters": ...
     ]
   }' \
-F 'access_token=<ACCESS_TOKEN>'   \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>

この例では、200クリックを超えるすべての広告を選択するようフィルターを更新しています。entity_typeやtime_presetなどのほかのフィルターもこの更新に含める必要があります。

curl \
-F 'evaluation_spec={
      "evaluation_type": ...,
      "filters" : [
       {
         "field": "clicks",
         "value": 200,
         "operator": "GREATER_THAN",
       },
       {
       ...
     ]
   }' \
-F 'access_token=<ACCESS_TOKEN>'   \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>

ルールを削除する

curl -X DELETE \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>

ルールの実行履歴にアクセスする

各ルールの実行の履歴データにアクセスするエンドポイントがあります。デフォルトでは、このエンドポイントは結果やアクションなど、関連するデータを提供します。編集のトラッキングのために、実行するたびにルールのステータスを確認することもできます。

curl -G   \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>/history

さらに、このエンドポイントでは、object_id、action、hide_no_changesデータ用の3つのフィルタリングメカニズムをサポートしています。object_idやactionで結果をフィルタリングすると、その object_idまたはactionタイプの結果のみが表示されます。

hide_no_changesフラグを使用して結果をフィルタリングして、変更がないすべての実行を除外したりすることもできます。これらのフィルターを組み合わせれば、さらに検索結果を絞り込むことができます。

curl -G   \
-d 'object_id=123' \
-d 'action=CHANGED_BID' \
-d 'hide_no_changes=true' \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>/history

アカウントの実行履歴にアクセスする

アカウントのすべてのルールの集計履歴データにアクセスするエンドポイントがあります。デフォルトでは、このエンドポイントはルールの実行履歴と同じ関連データのほか、各エントリのルールのIDも提供します。

このエンドポイントのエントリは、新しいものから古いものの順に並べられます。このエンドポイントでは、上記と同じフィルタリングメカニズムである、object_id、action、hide_no_changesもサポートしています。

curl -G   \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_history

ルールをプレビューする

スケジュールベースルールの評価をプレビューするエンドポイントがあります。POSTリクエストを送信すると、このエンドポイントは、指定されたルールのフィルターの条件をその時点で満たすオブジェクトのリストを返します。

curl \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>/preview

ルールを手動で実行する

スケジュールベースルールを手動で実行するエンドポイントがあります。このエンドポイントにPOSTリクエストを送信すると、そのルールの実行がすぐにスケジュールされます。

curl \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>/execute

ルールの実行完了後、実行履歴から結果を取得することができます。

オブジェクトの管理ルールを読み込む

各広告、広告セット、広告キャンペーンを管理するすべてのルールを読み込むエンドポイントがあります。デフォルトでは、ルールはidフィルターによって静的に参照されるオブジェクトや、entity_typeフィルターによって動的に参照されるオブジェクトを管理します。

このエンドポイントでは、オプションのpass_evaluationもサポートしています。このため、オブジェクトが参照時にルールのフィルターを渡すかどうかによって、ルールのリストをさらに制限することができます。pass_evaluationがtrueになっている場合、オブジェクトを返すすべてのプレビュー済みのルールが返されます。falseになっている場合、オブジェクトを返さないすべてのルールが返されます。

curl \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_OBJECT_ID>/adrules_governed