图谱 API 的流量限制

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

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

应用级流量限制

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

流量限制面板

您可以在应用面板中查看应用流量限制活动的图表。

限制

每款应用都应实施流量限制。流量限制工具会说明应用距离被节流还剩多少次调用。点击任意示例,详细了解使用类型。

应用每小时总计可向每位用户发出 200 次调用。 举例来说,如果应用有 100 位用户,则意味着可以发出 20,000 次调用。 这不是按用户设置的上限,因此一位用户可能发出 19,000 次调用,而另一位用户可能发出 1,000 次。该限制根据前一小时发出的调用次数计算。

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

应用用户的数量是指每日活跃用户的平均数加当天新登录数估计值。相较于用户数量较小的应用而言,用户数量较大的应用可能有更加精确的流量限制。用户数量非常小的应用可能会遇到流量限制问题。

注意事项:

  • 并非所有 API 调用都会受到流量限制,因此您发出的调用次数可能与您在流量限制工具中看到的不一致。
  • Facebook 还会根据所用的 CPU 时间和总时间对调用进行节流。这些限制很难达到,因此极少发生限制。这一信息显示在每个示例的详情窗格中。点击面板上流量限制工具中的图表了解详情。
  • 广告成效分析 API 市场营销 API 可能使用不同的流量限制集。请参阅市场营销 API 流量限制文档:https://developers.facebook.com/docs/marketing-api/api-rate-limiting,详细了解市场营销 API。

建议

流量限制定义了在指定时间段内可以发出 API 调用的次数限制。超出流量限制时,应用发出的所有 API 调用在短时间内将被节流,不能发出。应用被节流后,调用者再次发出调用时将收到错误 error code = 4, CodedException。 您的请求最多要 1 小时后才能再次被接受。

要避免出现流量限制:

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

流量限制标头

如果应用发出足够数量的调用,致使系统考虑实施流量限制,我们将返回 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 调用?

所有调用都会计入流量限制,而不仅仅是单独的 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,我该怎么做?

您的应用超出了自定义流量限制。请联系您的合作伙伴经理以帮助解决这一问题。

构建搜刮程序时需关注其他哪些问题?

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