広告オブジェクトのステータスを管理する

広告キャンペーン、広告セット、広告のステータスのタイプは通常、次のいずれかになります:

ライブ(Live)
アーカイブ済み(Archived)
削除(Deleted)

詳しくは、広告開発者向けのブログ「Deleted versus Archived (削除とアーカイブの対比)」をご覧ください。

ライブ(LIVE)

ライブ広告オブジェクトには次のステータスがあります。

ACTIVE
PAUSED
PENDING_REVIEW
CREDIT_CARD_NEEDED
PREAPPROVED
DISABLED
PENDING_PROCESS
WITH_ISSUES

アーカイブ済み

広告オブジェクトのステータスをARCHIVEDに設定するには、statusフィールドをARCHIVEDに設定します。オブジェクトのステータスをARCHIVEDに設定しておくと、引き続きオブジェクトIDに基づいて詳細や統計情報をクエリできます。ただし、アーカイブできるオブジェクトの数には上限があります。この上限を超えないようにするため、不要になったオブジェクトのステータスをDELETEDに変更してください。

ARCHIVEDオブジェクトで変更できるフィールドはnameとstatusの2つだけです。statusはDELETEDにのみ変更できます。

削除済み

広告オブジェクトのステータスをDELETEDに設定するには、statusフィールドをDELETEDに設定するか、HTTP DELETEを該当するオブジェクトに送信します。一度オブジェクトのステータスをDELETEDに設定すると、ARCHIVEDに戻すことはできません。

削除されたオブジェクトのIDを残しておけば、そのオブジェクトIDをクエリすることによって、引き続き統計情報やオブジェクトの詳細を取得できます。ただし、削除オブジェクトを削除されていないノードやオブジェクトから接続オブジェクトとして取得することはできません。例えば、削除オブジェクトに<API_VERSION>/<AD_ID>/insightsを使用することはできますが、<API_VERSION>/act_<AD_ACCOUNT_ID>/insights?level=adを使用しても削除オブジェクトの統計情報は返されません。

広告を削除しても、最後の配信日から28日間はインプレッション数、クリック数、アクション数などがトラッキングされる場合があります。DELETEDオブジェクトのインサイトは、ad.effective_statusフィルターを使ってクエリできます。

2つの広告を持つ広告セットがあり、1つの広告を削除した場合は、次の2つのクエリから返される結果が異なります:

https://graph.facebook.com/v19.0/<AD_SET_ID>/insights
https://graph.facebook.com/v19.0/<AD_ID>/insights

この広告セットからは、削除された広告と削除されていない広告の両方の統計情報が返されます。しかし、広告セット内の広告をクエリすると、1つの広告しか表示されません:

https://graph.facebook.com/v19.0/<AD_SET_ID>/ads

このような状況を回避するには、統計情報が変更されることがないように、広告の最後の配信日から28日経過後に広告を削除することをおすすめします。また、広告を削除する前に、これらのオブジェクトの統計情報やIDを自分のシステムに保存しておいてください。以下の場合は、この推奨事項は任意となります:

アプリが統計情報の内訳を示さない場合、または
子オブジェクトを削除したために統計情報の内訳の合計が親オブジェクトの合計と一致しなくなっていても問題ない場合。

DELETEDオブジェクトの場合、nameフィールド以外のフィールドを変更することはできません。

ステータス管理する

以下は、オブジェクトステータスを管理する一般的な方法です:

広告オブジェクトを作成し、実行して配信を開始する
削除したオブジェクトは、Facebookによって自動的に削除される
アーカイブしたオブジェクト数の上限に達すると、それ以上オブジェクトをアーカイブできなくなります。
上限を超えないために、アーカイブされたオブジェクトをdeleted状態に移動します。

広告オブジェクトのステータスは、広告オブジェクトの階層に対して次のように機能します。

キャンペーンのステータスをwith_issues、paused、archived、deletedのいずれかに設定すると、下位のオブジェクトすべてが自動的にそのステータスを継承します。
例えば、広告キャンペーンをdeletedに設定すると、IDを明示的に指定しなければ、そのキャンペーンの下位の広告セットや広告は取得できません。
広告のステータスをwith_issues、paused、archived、deletedのいずれかに設定した場合、その広告が含まれる広告セットや広告キャンペーンの元のステータスは保持されるため、広告セットや広告キャンペーンは取得できます。

特定の広告アカウントのARCHIVEDオブジェクトには次の制限が適用されます。

広告キャンペーンの上限は100,000
広告セットの上限は100,000
広告の上限は100,000

archivedエッジはデフォルトでは返されないため、この状態のエッジを読み取る場合は、アーカイブオブジェクトを明確にフィルター処理する必要があります。広告オブジェクトの統計情報を読み取ると、すべての子オブジェクトの統計情報が(active、archived、deletedのいずれであるかを問わず)含められます。そのため、子オブジェクトのインサイトを得るためにフィルター処理する必要はありません。

異なるステータスの比較

ステータスがACTIVEやPAUSEDなどのオブジェクトは、ステータスがARCHIVEDやDELETEDであるオブジェクトとは異なります。主な違いは次のとおりです。

クエリ	ライブ(LIVE)	ARCHIVED	DELETED
データベース内の既存の項目	〇	〇	〇
広告アカウントあたりの上限	上限あり	100,000	上限なし
エッジとしてクエリ(フィルターなし)	〇	×	×
エッジとしてクエリ(ステータスフィルターあり)	〇(ステータスがフィルターに含まれるオブジェクトの場合)	〇(ステータスフィルターに`ARCHIVED`が含まれる場合)。	×(ステータスフィルターに`DELETED`が含まれない場合)。含まれる場合はエラー。
個別のIDによるクエリ	〇	〇	〇
`/<PARENT_OBJECT_ID>/insights`で集計された統計情報	〇	〇	〇
`/<PARENT_OBJECT_ID>/insights?level=<OBJECT_LEVEL>`の結果リストに含まれる統計情報	〇	×	×
delivery_infoフィルターで`/<PARENT_OBJECT_ID>/insights`の結果リストに含まれる統計情報	〇(ステータスがフィルターに含まれるオブジェクトの場合)	〇(ステータスがフィルターに含まれるオブジェクトの場合)	×
`/<OBJECT_ID>/insights`で表示されるインサイト	〇	〇	〇
変更可能なステータス	有効なステータスすべて	`DELETED`	変更不可

広告をアーカイブ済みに設定するには:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->archive();

from facebookads.adobjects.ad import Ad

ad = Ad(ad_id)
ad.remote_archive()

new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_ARCHIVED)
  .execute();

curl \
  -F 'status=ARCHIVED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>

広告を削除するには:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->deleteSelf();

from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad.remote_delete()

new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_DELETED)
  .execute();

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/

ライブオブジェクトのライブのサブオブジェクトを取得するには(例: 広告キャンペーンのすべてのライブ広告のうちARCHIVEDやDELETEDの広告を含まないもの):


curl -X GET \
  -d 'fields="name"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_CAMPAIGN_ID>/ads


'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Campaign = bizSdk.Campaign;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_CAMPAIGN_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
  'name',
];
params = {
};
const adss = (new Campaign(id)).getAds(
  fields,
  params
);
logApiCallResult('adss api call complete.', adss);


require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_CAMPAIGN_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
  'name',
);
$params = array(
);
echo json_encode((new Campaign($id))->getAds(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);


from facebook_business.adobjects.campaign import Campaign
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
  'name',
]
params = {
}
print Campaign(id).get_ads(
  fields=fields,
  params=params,
)


import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_CAMPAIGN_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Campaign(id, context).getAds()
      .requestNameField()
      .execute();

  }
}


require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

campaign = FacebookAds::Campaign.get(id)
adss = campaign.ads({
    fields: { 'name' },
})

ライブオブジェクトのARCHIVEDサブオブジェクトを取得するには(例: 広告セットのすべてのARCHIVED広告で、ステータスフィルターを必要とするもの):


curl -X GET \
  -d 'effective_status=[
       "ARCHIVED"
     ]' \
  -d 'fields="name"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_CAMPAIGN_ID>/ads


'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Campaign = bizSdk.Campaign;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_CAMPAIGN_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
  'name',
];
params = {
  'effective_status' : ['ARCHIVED'],
};
const adss = (new Campaign(id)).getAds(
  fields,
  params
);
logApiCallResult('adss api call complete.', adss);


require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_CAMPAIGN_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
  'name',
);
$params = array(
  'effective_status' => array('ARCHIVED'),
);
echo json_encode((new Campaign($id))->getAds(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);


from facebook_business.adobjects.campaign import Campaign
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
  'name',
]
params = {
  'effective_status': ['ARCHIVED'],
}
print Campaign(id).get_ads(
  fields=fields,
  params=params,
)


import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_CAMPAIGN_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Campaign(id, context).getAds()
      .setEffectiveStatus(\"[\\"ARCHIVED\\"]\")
      .requestNameField()
      .execute();

  }
}


require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

campaign = FacebookAds::Campaign.get(id)
adss = campaign.ads({
    fields: { 'name' },
    effective_status: ['ARCHIVED'],
})