限制和最佳作法

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 天後就不再變動資料。

洞察報告呼叫負載上限

在第 3.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。

我們會設定負載上限，以獲得最佳的分析報告體驗。我們會衡量 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 - 相關應用程式編號已耗用的配置容量百分比。
• acc_id_util_pct - 相關廣告帳號編號已耗用的配置容量百分比。
• 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> 匯出為能以人工讀取的本地化格式。

注意：此端點並不屬於我們各版本圖形 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/'