マーケティングAPI

制限とベストプラクティス

FacebookインサイトAPIでは、Facebookマーケティングキャンペーンからのパフォーマンスデータが提供されます。システムのパフォーマンスと安定性を維持するため、Facebookではシステムリソースがアプリケーション間で均等に分散されるよう予防策を講じています。以下に説明するすべてのポリシーは、変更される場合があります。

呼び出しあたりのデータ制限

Facebookでは、1回の呼び出しでシステムの処理能力を超える大量のデータをクエリできないよう、呼び出しあたりのデータ制限を設けています。データ制限には2つのタイプがあります。

  1. 応答の行数によるデータ制限と、
  2. サマリー行など、合計を算出するのに必要なデータポイントの数によるデータ制限。

これらの制限は、/insightsの同期と非同期の呼び出しに適用され、次のエラーが返されます。

error_code = 100,  CodeException (error subcode: 1487534)

呼び出しあたりのデータ制限のベストプラクティス

  • 日付範囲または広告IDの数を制限することによって、クエリを制限します。必要な指標をクエリするよう制限したり、1回につき少数の指標をリクエストするようクエリを複数に分けることもできます。
  • action_target_id、product_id、通算などの広い日付範囲といった、データ量の多い内訳を含むアカウントレベルのクエリは避けてください。
  • 下位レベルの広告オブジェクトに直接/insightsエッジを使用して、そのレベルの詳細データを取得します。例えば、アカウントレベルのクエリでlevelパラメーターとfilteringパラメーターを使って下位レベルのオブジェクトIDのリストを取得するなど。この例では、インプレッションが記録されたすべてのキャンペーンを取得します。
curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=campaign' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0}]' \
'https://graph.facebook.com/v2.7/act_<ACCOUNT_ID>/insights'

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[ \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_1>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_2>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_3>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  } \
]' \
'https://graph.facebook.com'
  • filteringパラメーターは、データのある広告オブジェクトのインサイトを取得する場合にのみ使用します。filteringで指定したフィールド値は、ドット表記を使用してオブジェクトのフィールドを表します。STARTS_WITHとCONTAINによるフィルタリングでは概要データが変更されません。この場合は、IN演算子を使用します。filteringリクエストの例をご覧ください。
curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=ad' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0},]' \
'https://graph.facebook.com/v21.0/act_<ACCOUNT_ID>/insights'
  • date_presetを使用します(該当する場合)。カスタム期間は、Facebookのシステムでは実行の効率が下がります。
  • 複数の同期呼び出しと非同期呼び出しの場合、大量のデータのクエリでタイムアウトが発生しないよう、バッチリクエストを使用します。
  • まず同期呼び出しを行い、同期呼び出しがタイムアウトする場合は、その後に非同期呼び出しを行います。
  • インサイトは15分ごとに更新され、報告から28日経過した後は変更されません。

インサイトの呼び出しのデータ通信量の制限

v3.3のリリースから90日で、すべての公開バージョンにおいて、広告アカウントレベルのレート制限を、必要なAPI呼び出しの量がより正確に反映されるように変更します。マーケティングAPIアクセス層とアプリを所有しているビジネスのレート制限割り当てが計算されます。アクセスと認証をご覧ください。この変更は、すべての広告インサイトAPIエンドポイント(GET {adaccount_ID}/insights、GET {campaign_ID}/insights、GET {adset_ID}/insights、GET {ad_ID}/insights、POST {adaccount_ID}/insights、POST {campaign_ID}/insights、POST {adset_ID}/insights、POST {ad_ID}/insights)に適用されます。

Facebookでは、最適なレポートサービスを提供するためにデータ通信量の制限を設けており、各レートのAPI呼び出しと、必要なリソースを測定しています。アプリケーションごとに1秒あたりの固定のデータ通信量の制限を設定できます。その制限を超えると、リクエストは失敗します。

各API応答のx-fb-ads-insights-throttle HTTPヘッダーから、制限までの猶予を確認でき、同時にデータ量が著しく多いクエリを把握することもできます。インサイト呼び出しもx-ad-account-usage HTTPヘッダーに表示されるデフォルトの広告アカウント制限の対象になります。詳しくは、マーケティングAPI、ベストプラクティスをご覧ください

アプリが上限に達すると、呼び出しにはerror_code = 4, CodedExceptionというエラーが返されます。この制限を十分下回るようにしてください。アプリが上限に達すると、クエリとレートに応じて一定の割合のリクエストのみ許可されます。

Facebookでは、同期と非同期の/insights呼び出しを組み合わせて送信するアプリごとにレート制限が適用されます。2つのメインパラメーターの制限は、アプリケーションごとと広告アカウントごとにカウントされます。

アプリが獲得したスコアを制限の割合として示すHTTPヘッダーの例は次のとおりです。

X-FB-Ads-Insights-Throttle: { "app_id_util_pct": 100, "acc_id_util_pct": 10, "ads_api_access_tier": "standard_access" }

「x-fb-ads-insights-throttle」のヘッダーは次の情報を含むJSON値です。

  • app_id_util_pct — 割り当てられた容量に対して関連付けられたapp_idが消費した割合。
  • acc_id_util_pct — 割り当てられた容量に対して関連付けられたad account_idが消費した割合。
  • ads_api_access_tier — さまざまなレベルに基づいて、アプリのマーケティングAPIへのアクセスが許可されます。standard_accessにより、低レート制限が可能になります。

グローバルなレート制限

/insightsエンドポイントへのグローバル負荷が上昇している間、システムはバックエンドを保護するためにリクエストをスロットリングできます。これは、非常に複雑なクエリ(長い時間範囲、複雑な指標、および/または多数の広告オブジェクトID)が同時に多数生じる場合に、まれに発生することがあります。これは次のようなエラーとして現れます。

error_code = 4,  CodeException (error subcode: 1504022), error_title: Too many API requests

これらの期間中は、呼び出しを減らし、少し待ってから再度クエリを送信することをおすすめします。

レート制限のベストプラクティス

  • 一度に複数のクエリを送信すると、レート制限に達する可能性が高くなります。待機時間を調整して/insightsクエリを分散してください。
  • HTTP応答ヘッダーにあるレート情報を使って、呼び出しを調整します。アプリや広告アカウントで100 %に到達しそうになった場合は、バックオフメカニズムを追加して/insightsクエリの頻度を下げるか一時停止します。
  • Facebookでは、広告インサイトのデータを広告アカウントの時間帯で報告します。関連付けられた広告アカウントのインサイトデータを毎日取得する場合は、アカウントの時間帯を使用して時間を指定するようにしてください。これにより、1日を通してクエリを調整できます。
  • マーケティングAPIへのアクセスを許可するads_api_access_tierをチェックしてください。デフォルトでは、アプリはdevelopment_access レベルにあり、standard_accessによって低レート制限が可能になります。広告管理スタンダードアクセス機能への「アドバンスアクセス」を申請すれば、高レート制限を取得し、スタンダードレベルを維持することができます。

インサイトAPI非同期ジョブ

多くのオブジェクトに関する統計情報を取得し、フィルタリングと並べ替えの処理を適用します。非同期ワークフローがよりシンプルになりました。

  1. POSTリクエストを<AD_OBJECT>/insightsエンドポイントに送信します。広告レポートの実行のidが返されます。
{
  "report_run_id": 6023920149050,
}

report_run_idは30日後に有効期限が切れるので、保存して長期間使用することはできません。

  1. 広告レポートの実行には、async_statusなど、この非同期ジョブに関する情報が含まれます。このフィールドに対するポーリングは、async_statusがJob Completedに、async_percent_completionが100になるまで実行されます。 
{
  "id": "6044775548468",
  "account_id": "1010035716096012",
  "time_ref": 1459788928,
  "time_completed": 1459788990,
  "async_status": "Job Completed",
  "async_percent_completion": 100
}
  1. その後、<AD_REPORT_RUN_ID>/insightsエッジに対してクエリを実行し、最終結果をフェッチできます。
{
  "data": [
    {
      "impressions": "9708",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    },
    {
      "impressions": "18841",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

このジョブによって、アカウントのすべての統計情報が取得され、非同期ジョブIDが返されます。

curl \
  -F 'level=campaign' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CAMPAIGN_ID>/insights
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000002
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000003/insights

非同期ジョブのステータス

ステータス説明

Job Not Started

ジョブはまだ開始されていません。

Job Started

ジョブは開始されましたが、まだ実行されていません。

Job Running

ジョブの実行が開始されました。

Job Completed

ジョブは成功しました。

Job Failed

ジョブは失敗しました。クエリを確認して、もう一度実行してください。

Job Skipped

ジョブの有効期限が切れ、スキップされました。ジョブを再送信して、もう一度実行してください。

レポートのエクスポート

Facebookでは、<AD_REPORT_RUN_ID>を、人間が読める、ローカライズ済みのフォーマットにエクスポートするのに便利なエンドポイントをご用意しています。

注: このエンドポイントはバージョン管理されたグラフAPIの一部ではないため、最新の変更ポリシーには準拠していません。エンドポイントは予期せず変更される可能性があるため、スクリプトやプログラムが結果のフォーマットに依存しないようにしてください。

  curl -G \
  -d 'report_run_id=<AD_REPORT_RUN_ID>' \
  -d 'name=myreport' \
  -d 'format=xls' \
'https://www.facebook.com/ads/ads_insights/export_report/'
名前説明

name

文字列

ダウンロードされたファイルの名前

format

enum{csv,xls}

ファイルの形式

report_run_id

integer

実行するレポートのID

access_token

文字列

ログイン済みユーザーが付与したアクセス許可。別のユーザーにレポートをエクスポートする際に指定します。