圖形 API 的限速

限速定義的是在指定時間範圍內可以發出的 API 呼叫次數限制。限速是針對每個應用程式。

可能會停用過度或持續超過其限速的應用程式。

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

應用程式會遭遇的限速有四種主要類型:

請參閱我們的部落格文章,深入瞭解應用程式主控板中的限速工具。

廣告帳號層級限速

廣告帳號層級限速是行銷 API 限速邏輯的一部分,與圖形 API 限速是分開的。如果發出行銷 API 呼叫,這不會計入圖形 API 限速內。如需詳細資訊,請參閱行銷 API 限速文件

超過限速後,應用程式發出的所有行銷 API 呼叫都會遭到限速,並且會發生 Error code 17, error_subcode=2446079 失敗。當過去一小時的使用量低於限制時,將再次開始成功進行呼叫。限速會在特定時間範圍內即時發生。

限速主控板

應用程式主控板上的廣告帳號層級限速卡中,點擊「檢視詳細資訊」,檢視目前使用限制的百分比和重設使用量的時間。點擊每個帳號的 > 形箭號,檢視過去 7 天的平均活動。將滑鼠移到圖表上方任一點,查看更多有關該特定時刻使用量的詳細資訊。因為使用量取決於呼叫量,此圖表可能不會顯示完整 7 天。呼叫量較高的應用程式將顯示較多天數。

限制

限速設定可在給定的時間範圍內於廣告帳號層級即時進行。系統會為每個行銷 API 呼叫指派一個分數,您的分數為 API 呼叫總數。系統會強制使用分數上限,達到分數上限時,系統便會擲回限速處理錯誤。

注意:更新比建立要多耗費 10 到 100 倍的資源。

建議處理方式

  • 切換到其他廣告帳號,稍後再回到這個帳號。
  • 相較於變更現有廣告,建立新廣告是更好的作法。

限速標頭

對行銷 API 發出之呼叫的所有回應都會附加 x-ad-account-usage HTTP 標頭。這個標頭會包含廣告帳號目前的使用量百分比。

限速標頭為 JSON 格式的字串。以下範例顯示為其限制 9.67% 的廣告帳號。

x-ad-account-usage: {"acc_id_util_pct":9.67} 

當百分比值超過 100 時,廣告帳號將遭到限速。

應用程式層級限速

對於使用粉絲專頁存取權杖以外的任何存取權杖所發出的呼叫,都會受到這種限速的影響。

超過限速後,應用程式發出的所有 API 呼叫都會遭到限速,並且會發生 Error code = 4, CodedException 失敗。當過去一小時的使用量低於限制時,將再次開始成功進行呼叫。系統會在捲動的一小時期間計算限制,您可以在應用程式主控板中看到目前的使用率百分比。

限速主控板

應用程式主控板上的應用程式層級限速卡中,點擊「檢視詳細資訊」,檢視目前使用限制的百分比和過去 7 天的平均活動。將滑鼠移到圖表上方任一點,查看更多有關該特定時刻使用量的詳細資訊。因為使用量取決於呼叫量,此圖表可能不會顯示完整 7 天。呼叫量較高的應用程式將顯示較多天數。

限制

應用程式每小時可以發出的呼叫總數是用戶的 200 倍。這不是針對用戶的限制,只要所有用戶總數不超過應用程式數量上限,任何單一用戶每小時可以發出超過 200 次呼叫。舉例來說,如果應用程式有 100 名用戶,該應用程式每小時可以發出 20,000 次呼叫。不過,互動最頻繁的前 10 名用戶可以發出其中的 19,000 次呼叫。

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

使用每日活躍用戶人數和當天新登入人數來計算應用程式的用戶人數。如果發生每日使用量緩慢的情況,將使用每週活躍用戶或甚至每月活躍用戶來計算應用程式的用戶人數。無論實際的應用程式安裝數量有多少,相較於每日互動低的應用程式,每日互動高的應用程式具有較高的限速。

注意事項:

  • 並非所有 API 呼叫都會受到限速的影響,所以您發出的呼叫次數可能會與限速工具中顯示的資訊不符。
  • 我們也會根據使用的 CPU 時間和總時間來限速呼叫。儘管低於呼叫量限制,需要大量處理的端點可能會使您的應用程式達到這些限制。除了特殊端點以外,應用程式很少會達到 CPU 時間和總時間限制。您可以在歷史圖表中(如果有的話),查看使用大量 CPU 時間或總時間的端點資訊。

建議處理方式

若要避免限速:

  • 將查詢平均分佈在兩個時間間隔,避免在高峰傳送流量。
  • 使用篩選條件限制資料回應大小,並避免發出要求重複資料的呼叫。
  • 使用限速標頭,動態平衡呼叫量。

限速標頭

對圖形 API 發出之呼叫的所有回應都會附加 X-App-Usage HTTP 標頭。這個標頭會包含應用程式目前的使用量百分比。這個百分比和限速圖表中顯示的使用量相同。請使用這個數字來動態平衡呼叫負載,以避免遭到限速。

限速標頭為 JSON 格式的字串,如下所示:

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

x、y 和 z 的值皆為整數,代表各指標的使用百分比值。當任一指標超過 100,應用程式就會遭到限速。

粉絲專頁層級限速

對於使用粉絲專頁存取權杖所發出的呼叫,都會受到這種限速的影響。

超過限速後,應用程式發出的所有 API 呼叫都會遭到限速,並且會發生「錯誤代碼 32」失敗。深入瞭解粉絲專頁層級限速

限速主控板

應用程式主控板上的粉絲專頁層級限速卡中,點擊「檢視詳細資訊」,檢視目前使用限制的百分比。點擊每個粉絲專頁的 > 形箭號,檢視過去 7 天的平均活動以及最活躍的端點。將滑鼠移到圖表上方任一點,查看更多有關該特定時刻使用量的詳細資訊。因為使用量取決於呼叫量,此圖表可能不會顯示完整 7 天。呼叫量較高的應用程式將顯示較多天數。

限制

限速會加諸在每個粉絲專頁上,而非應用程式身上。每 24 小時,每位每日互動用戶可代表粉絲專頁累計發出 4,800 次呼叫。舉例來說,如果粉絲專頁每日有 100 位互動用戶人數,則在 24 小時期間內代表粉絲專頁發出的呼叫數量可為 480,000 次。這個 24 小時期間為滑動範圍,每數分鐘會更新一次。這個呼叫限制為每個粉絲專頁限制,所以如果某個應用程式發出 400,000 次呼叫,另一個應用程式可發出 80,000 次呼叫。如果粉絲專頁遭到限速,只有使用該粉絲專頁存取權杖的應用程式呼叫會受到限制。這表示應用程式的其他呼叫仍可正常運作。

每日與粉絲專頁互動的用戶人數為在 24 小時期間內與粉絲專頁互動的不重複用戶人數。與粉絲專頁的互動包括點擊粉絲專頁或粉絲專頁內容。

前 24 小時內的互動用戶人數會用於計算目前 24 小時期間的限速。

粉絲專頁呼叫次數的計算方式為每日使用粉絲專頁存取權杖的預估呼叫次數。每日呼叫次數越多的粉絲專頁,計算出來的限速就越準確。每日呼叫次數過少的粉絲專頁可能會遇到限速問題。

注意事項:

  • 並非所有的 API 呼叫都會受到限速的影響,所以您發出的呼叫次數可能會與限速工具中顯示的資訊不完全相符。
  • Facebook 也會根據使用的 CPU 時間和總時間來限速呼叫。點擊主控板上限速工具中的圖表,即可取得詳細資訊。
  • 廣告洞察報告 API行銷 API 可能使用不同組限速。如需有關行銷 API 的詳細資訊,請參閱行銷 API 限速文件
  • 粉絲專頁限速是由管理相同粉絲專頁的所有應用程式所共享。請參閱主控板詳細資訊,瞭解您的應用程式與所有其他應用程式在每頁面使用量部分的比較。

建議處理方式

一旦粉絲專頁遭到限速,呼叫者對於後續呼叫都會發生以下錯誤:Error code = 32, CodedException。可能需要一個小時之後,才能再次接受您對該粉絲專頁的要求。

若要避免遭到限速:

  • 將查詢平均分佈在兩個時間間隔,避免在高峰傳送流量。
  • 使用篩選條件限制資料回應大小,並避免發出要求重複資料的呼叫。
  • 使用限速標頭,動態平衡呼叫量。

限速標頭

如果代表粉絲專頁發出足夠的呼叫次數,而被我們的系統考慮加以限速時,我們會傳回 X-Page-Usage HTTP 標頭。這個標頭會包含該粉絲專頁目前的使用量百分比。如果您使用某個粉絲專頁存取權杖發出呼叫,只會取得該粉絲專頁的 X-Page-Usage 值。這個百分比和針對該粉絲專頁的限速圖表中顯示的使用量相同。請使用這個數字來動態平衡呼叫負載,以避免遭到限速。

限速標頭為 JSON 格式的字串,如下所示:

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

x、y 和 z 的值皆為整數,代表各指標的使用百分比值。當任一衡量指標超過 100,應用程式就會遭到限速。

用戶層級限速

對於使用用戶存取權杖所發出的呼叫,都會受到這種限速的影響。

超過限速後,應用程式發出的所有 API 呼叫都會遭到限速,並且會發生 Error code 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,該怎麼做?

如果您的錯誤回應包含 error_subcode 1996,Facebook 會注意到應用程式 API 要求量存在不一致的行為。如果您最近進行了任何會影響 API 要求量的變更,可能會遇到此錯誤。

如果沒有看到子代碼,表示您的應用程式超過自訂限速。請聯絡業務經理,請求協助解決此問題。


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

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