图谱 API 的流量限制

流量限制定义了在指定时间段内可以发出 API 调用的次数限制。每款应用都应实施流量限制。

过度或持续超过流量限制的应用可能会被禁用。

Facebook 图谱 API 的流量限制只应在少数情况下遇到。本文档说明了这些限制是什么及处理方式。

应用会遇到两种主要类型的流量限制:应用级流量限制和主页级流量限制。

应用级流量限制

这些限制适用于使用主页访问口令以外的任意访问口令发出的调用。

超出流量限制后,应用发出的所有 API 调用将被节流,并显示错误 error code = 4, CodedException。当过去一小时的使用量回落到限制以下时,调用才会再次成功。这些限制是按一小时时间窗滚动计算的,您可访问应用面板查看当前的使用量百分比。

流量限制面板

流量限制工具会说明应用距离被节流还剩多少次调用。您可通过应用面板中的两个图谱,查看影响应用的流量限制的相关信息。

  • 一个图谱显示了影响图谱 API 所返回响应的当前使用量。此图谱直观地反映了图谱 API 请求中返回的标头值。
显示应用即将超出流量限制的图谱
  • 另一个图谱显示了历史流量限制。您可选择显示过去 24 小时或过去 7 天的数据。您可以点击历史图谱中的任何示例,查看有关使用量的更多详情,包括按方法细分的数据。并非所有应用都有历史数据,因为是否有历史数据取决于调用量。调用量越高,应用拥有历史数据的可能性越大。
过去 24 小时应用超出流量限制的历史数据

限制

应用每小时可调用的总量是用户人数的 200 倍。这不是按用户设置的限制,因为每位用户每小时都可发出 200 次以上调用,只要所有用户的总调用量未超出应用的最高限制。举例来说,如果应用有 100 位用户,则应用每小时可以发出 20,000 次调用。但前 10 位使用率最高的用户可能发出了其中 19,000 次调用。

如果应用被限制流量,则该应用的所有调用都将被限制,而不是针对特定用户限制。

应用用户人数是根据日活跃用户人数和当天新登录数计算的。如果用户每日使用应用的时间较少,则应用用户人数可能使用周活跃用户甚至是月活跃用户计算。无论实际应用安装量如何,每日使用率高的应用都会比每日使用率低的应用拥有更高的流量限制。

注意事项:

  • 并非所有 API 调用都会受到流量限制,因此您发出的调用次数可能与您在流量限制工具中看到的不一致。
  • 我们还会根据所用的 CPU 时间和总时间对调用进行节流。如果端点需要大量处理,即便应用没有超出调用量限制,也可能会导致应用达到这些限制。除了专门的端点以外,很少有应用会达到 CPU 时间和总时间限制。有关使用大量 CPU 时间和总时间的端点的信息,请参见历史图谱(如有)。
  • 广告成效分析 API 市场营销 API 可能使用不同的流量限制集。请参阅市场营销 API 流量限制文档:https://developers.facebook.com/docs/marketing-api/api-rate-limiting,详细了解市场营销 API。

建议

要避免出现流量限制:

  • 在两次时间间隔之间均匀分配查询,避免出现流量发送峰值。
  • 使用筛选条件限制数据响应大小,并避免请求重叠数据的调用。
  • 使用流量限制标头动态平衡调用量。

流量限制标头

所有对图谱 API 调用的响应均包含一个 X-App-Usage HTTP 标头。该标头包含应用当前的使用量百分比。此百分比与流量限制图谱上显示的用量相同。使用该数字可动态平衡调用负载,避免被节流。

流量限制标头是 JSON 格式的字符串,形式如下:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

x、y 和 z 是代表每个指标使用量的百分比值的整数。当任意指标超出 100 时,应用将被限制流量。

主页级流量限制

这些限制适用于使用主页访问口令发出的调用。如果达到这些限制,您的应用将收到错误代码 32

以下博文详细说明了主页级流量限制:https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/

流量限制面板

对于访问口令被应用用于发出调用的每个主页,您可以查看它的流量限制图表。

限制

流量限制的实施对象为每个主页而非应用。流量限制工具将为您提供以下信息:多少应用使用该主页的访问口令,主页被节流前还剩多少次调用。点击任意示例,详细了解使用类型。

使用主页的每日参与用户数量是 24 小时内与主页有过互动的独立用户数量。与主页的互动包含点击主页或主页内容。

在过去 24 小时内参与的用户数量将被用于计算当前 24 小时时间窗的流量限制。

每位每日参与用户每 24 小时可以代表主页发出共 4800 次调用。举例来说,如果主页有 100 位每日参与用户,那么在 24 小时内可以代表主页发出的调用次数为 480,000 次。这 24 小时是一个滑动时间窗,每几分钟更新一次。调用限制是按主页设置的限制,因此一个应用可能发出 400,000 次调用,而另一个应用可能发出 80,000 次。如果主页被实施流量限制,只有使用该主页访问口令发出的应用调用才会被限制。这意味着您的应用仍可正常发出其他调用。

主页调用数量根据每天使用主页访问口令执行的调用的预计数量进行计算。相较于每日调用数量较少的主页而言,每日调用数量较多的主页可能有更加精确的流量限制。每日调用数量非常少的主页可能会遇到流量限制问题。

注意事项:

  • 并非所有 API 调用都会受到流量限制,因此您发出的调用次数可能与您在流量限制工具中看到的不一致。
  • Facebook 还会根据所用的 CPU 时间和总时间对调用进行节流。点击面板上流量限制工具中的图表了解详情。
  • 广告成效分析 API 市场营销 API 可能使用不同的流量限制集。请参阅市场营销 API 流量限制文档,详细了解市场营销 API。

建议

主页被节流后,调用者再次发出调用时将收到错误 error code = 32, CodedException。您对该主页的请求最长要 1 小时后才能再次被接受。

要避免出现流量限制:

  • 在两次时间间隔之间均匀分配查询,避免出现流量发送峰值。
  • 使用筛选条件限制数据响应大小,并避免请求重叠数据的调用。
  • 使用流量限制标头动态平衡调用量。

流量限制标头

如果代表主页发出了足够数量的调用,致使系统考虑实施流量限制,我们将返回 X-Page-Usage HTTP 标头。该标头包含主页当前的使用量百分比。如果您使用主页访问口令发出调用,您将仅获得该主页的 X-Page-Usage 值。该百分比与主页流量限制图表上显示的用量相同。使用该数字可动态平衡调用负载,避免被节流。

流量限制标头是 JSON 格式的字符串,形式如下:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

x、y 和 z 是代表每个指标使用量的百分比值的整数。当任意指标超出 100 时,应用将被限制流量。

帐户层级流量限制

这些限制适用于通过用户访问口令发出的调用。超出此限制后,您的应用将收到错误代码 17。当特定的用户帐户调用 API 的次数太多时,便会出现这种情况。

注意:

包括用户通过许多其他应用发出的调用,并非是仅仅通过您的应用发出的调用。

当用户达到流量限制后,该用户发出的 API 调用将被中止。

要避免出现流量限制:

您无法完全防止超出流量限制。用户调用次数太多(包括通过其他应用发出调用),便会受流量限制的约束。 但如果这种情况发生在同款应用的许多用户身上,则很可能是通过该应用发出的 API 调用所导致。在这种情况下,您应该减少用户调用的次数或更加均衡地分配调用。

头像网址

通过图谱 API 返回的头像网址可能有不同的流量限制。达到这些限制后,请求将返回 HTTP 响应代码 429(请求太多)。如果您多次达到流量限制:

  • 在多个时间间隔之间均匀地发出查询。
  • 从客户端加载图片,而非从服务器端。
  • 如果需要从服务器端加载图片,建议缓存图片。

常见问题

如何看待 API 调用?

所有调用都会计入流量限制,而不仅仅是单独的 HTTPS API 请求。例如,您可以调用一次 API 并指定多个编号,但每个编号都将算作是它自己的 API 调用,即使您只发出了一个 HTTPS API 请求。

要彻底理解这一概念,请看下方示例:

示例请求 API 调用数量

GET https://graph.facebook.com/photos?id=4
GET https://graph.facebook.com/photos?id=5
GET https://graph.facebook.com/photos?id=6

3

GET https://graph.facebook.com/photos?id=4,5,6

3

需要按编号遍历多个对象时,强烈建议您使用第二种方法,因为它会提高 API 响应的性能,但它不会改善计算流量限制时统计的调用发出数量。

您也可以使用批量 API 来批量处理请求,但请注意:每个子请求都是其自身的 API 调用,如果指定了多个编号甚至会是多个 API 调用。

如果您的应用或主页受到流量限制,遇到流量限制错误的 API 调用也会计入流量限制。


我的应用将收到哪些错误消息?
节流类型 最低 错误代码

应用级节流

200 次调用/人/小时

4

帐户级节流

不适用

17

主页级节流

4800 次调用/人/24 小时

32

自定义级节流

不适用

613


我收到错误代码 613,我该怎么做?

如果响应包含 error_subcode 1996,表示 Facebook 注意到您应用的 API 请求在数量方面的行为不一致。如果您近期做出的任何更改影响了 API 请求的数量,可能会遇到这一错误。

如果您未看到子代码,表示您的应用超出了自定义流量限制。请联系您的合作伙伴经理以帮助解决这一问题。


构建抓取程序时需关注其他哪些问题?

如果您正在构建抓取数据的服务,请参阅 Facebook 抓取条款