限制和最佳实践

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 — 表示相关广告 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. 向 <AD_OBJECT>/insights 端点发送 POST 请求，响应中将提供待运行广告报告的 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/'