限制圖形 API 速率

在極少情況下才會發生 Facebook 圖形 API 限速。這份文件描述限制為何且該如何處理。

應用程式會遭遇的限速有兩種主要類型:應用程式層級限速和粉絲專頁層級限速。

應用程式層級限速

對於使用粉絲專頁存取權杖以外的任何存取權杖所發出的呼叫,都會受到這種限速的影響。如果您達到限制,應用程式就會發生錯誤代碼 4

限速主控板

您可在應用程式的應用程式主控板中檢視應用程式限速活動的圖表。

限制

限速是針對每個應用程式。限速工具會提供有關應用程式是否接近限速的資訊。點擊任何樣本即可取得使用類型的詳細資訊。

對於每位用戶,應用程式每小時可以發出總共 200 次呼叫。 舉例來說,如果應用程式有 100 位用戶,這表示應用程式每小時可以發出 20,000 次呼叫。 這並非針對個別用戶進行限制,所以某位用戶可能發出 19,000 次呼叫,而另一位發出 1,000 次呼叫。這個限制是依據前一個小時所發出的呼叫數量來計算。

當應用程式遭到限速時,該應用程式發出的所有呼叫都會受到限制,而非只針對特定用戶發出的呼叫。

應用程式用戶人數的計算方式,是將每日平均活躍用戶人數加上當天新登入人數作為預估值。應用程式的用戶人數越多,計算出來的限速就越準確。用戶人數過少的應用程式可能會遇到限速問題。

注意事項:

  • 並非所有的 API 呼叫都會受到限速的影響,所以您發出的呼叫次數可能會與限速工具中顯示的資訊不完全相符。
  • Facebook 也會根據使用的 CPU 時間和總時間來限速呼叫。不過不太容易達到這些限制,在極少的情況下才會發生。這項資訊會顯示在每個樣本的詳細資料窗格中。點擊主控板上限速工具中的圖表,即可取得詳細資訊。
  • 廣告洞察報告 API行銷 API 可能使用不同組限速。如需有關行銷 API 的詳細資訊,請參閱行銷 API 限速文件(https://developers.facebook.com/docs/marketing-api/api-rate-limiting)。

建議處理方式

限速定義的是在指定時間範圍內可以發出的 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

粉絲專頁層級限速

每 24 小時、每用戶 4800 次呼叫

32

自訂層級限速

不適用

613

我看到錯誤代碼 613,該怎麼做?

您的應用程式超過自訂限速。請聯絡業務經理,請求協助解決此問題。

我正在建立資料抓取程式,其他還有什麼我需要注意的事項嗎?

如果您正在建立抓取資料的服務,請參閱資料抓取條款