限制與最佳操作實例

Facebook 洞察報告 API 提供有關 Facebook 營銷宣傳活動的成效資料。為保護系統運作效能與穩定性，我們採取了保護措施，在不同應用程式之間平均分配系統資源。我們在下方所述的所有政策都可能會改變。

每次呼叫資料的限制

我們採用每次呼叫資料的限制來防止單次查詢擷取超過系統能負荷的資料。共有 2 種資料限制類型：

1. 回應的列數，以及
2. 用於計算總和的資料點數量，例如摘要列。

這些限制適用於同步與非同步的 /insights 呼叫，我們也會傳回錯誤：

error_code = 100,  CodeException (error subcode: 1487534)

最佳操作實例：每次呼叫資料的限制

• 透過限制日期範圍或廣告編號的數字來限制查詢範圍您也可以設定限制，只查詢必要的衡量數據，或細分成多次查詢，在每次查詢要求衡量數據的子集。
• 避免含有高基數資料細節的帳戶級別查詢，例如查詢 action_target_id 或 product_id，以及日期範圍較大的查詢，例如查詢總期間。
• 直接以 /insights 關係連線配搭低階廣告物件來檢索該級別的細項資料。舉例來說，先使用帳戶級別的查詢配搭 level 與 filtering 參數，以擷取低階物件編號的清單。在此範例中，我們擷取記錄了一些展示次數的所有宣傳活動：

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'

• 然後，我們可以使用 /<campaign_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。在我們的系統中，自訂日期範圍的效率較低。
• 為多個同步呼叫及非同步呼叫使用批次要求，以避免在查詢大量資料時發生逾時情況。
• 請先試用同步呼叫，並於同步呼叫逾時的情況下，改用非同步呼叫
• 洞察報告每 15 分鐘會重新整理一次，報告彙整 28 天後的就不會再有變化

洞察報告呼叫載入上限

我們變更了廣告帳戶級別的限速要求，以更準確地反映所需的 API 呼叫數量；此變更將於 v3.3 版發佈當日起 90 天生效，並適用於所有公開版本。我們將計算您的推廣 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。

我們採用載入上限，以便提供最佳的報告體驗。我們會衡量 API 呼叫的傳輸率，以及這些呼叫所需的資源。我們允許每個應用程式每秒都有一個固定的載入上限。超出此上限後，您的要求就會失敗。

查看每一個 API 回應傳回的 x-fb-ads-insights-throttle HTTP 標題，以了解應用程式還差多少就會超出限額，並且估計個別查詢有多大。顯示於 x-ad-account-usage HTTP 標題的預設廣告帳戶限制亦適用於洞察報告呼叫。請參閱推廣 API 最佳操作實例了解更多詳情

應用程式達到上限後，呼叫就會收到含有 error_code = 4, CodedException 的錯誤回應。您應該保留足夠的限額。若應用程式達到允許的上限，則只有特定百分比的要求能通過，視乎查詢和傳輸率而定。

限速要求適用於每個應用程式傳送的同步與非同步 /insights 呼叫總和。兩個主要參數限制分別是根據應用程式與根據廣告帳戶來計算。

以下是 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 端點的全球負載升高期間，系統可為要求設立限速，以保護後端。在極少數情況下，當過多高度複雜的查詢（長時間範圍、複雜衡量數據和／或大量廣告物件編號）同時出現時，便會發生這種情況，並導致類似以下的錯誤：

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

在這些期間，我們建議您減少呼叫次數，等待一段時間後再次查詢。

限速最佳操作實例

• 一次傳送多個查詢較有可能觸發我們的限速機制。請嘗試於執行任務時加入等待時間來調節速度，分開不同時間發出您的各個 /insights 查詢。
• 使用 HTTP 回應標題中的傳輸率資訊來調整您的呼叫。當您的應用程式或廣告帳戶快要達到 100% 用量時，加入延遲機制以減緩或暫停 /insights 查詢。
• 我們會以廣告帳戶的時區回報廣告洞察報告資料。若要每天擷取相關廣告帳戶的洞察報告資料，請考慮使用帳戶的時區來記錄時間。這樣有助系統將查詢分配在一日的不同時間執行。
• 勾選讓您可以存取推廣 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"
    }
  }
}
    

此工作會取得帳戶所有的統計資料，並傳回非同步工作編號：

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

非同步工作狀態

匯出報告

我們提供了一個便利的端點，方便您將 <AD_REPORT_RUN_ID> 匯出為人類可讀的本地化格式。

注意：這個端點不包含在我們有版本之分的 Graph 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/'