限制圖形 API 速率

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

大幅或持續超出速限的應用程式可能會遭到停用。

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

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

應用程式層級限速

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

應用程式在超出限速後的所有 API 呼叫都會遭到限制,並發生 error code = 4, CodedException 而無法執行。過去一小時用量降回限速以下時,便可再次成功呼叫。限速會以每小時為計算單位,您可在應用程式主控板查看目前使用的百分比。

限速主控板

限速工具會提供有關應用程式是否接近限速的資訊。您可以運用應用程式主控板的兩張圖表,查看影響您應用程式的限速相關資訊。

  • 其中一張圖表會顯示目前使用率,這會影響您傳回圖形 API 回應。這是以視覺方式呈現圖形 API 要求傳回的標頭值。
即將達到限速的應用程式圖表
  • 另一張圖表會顯示歷史限速資料。您可以選擇顯示過去 24 小時或過去 7 天的資料。點擊歷史資料圖表的任一樣本可查看詳細的使用情形,包括檢視每種方法的資料解析。有無顯示歷史資料須視呼叫次數而定,因此某些應用程式可能沒有歷史資料。呼叫次數多的應用程式比較可能有歷史資料。
過去 24 小時超出限速的應用程式歷史資料圖表

限制

應用程式每小時可呼叫的總次數為用戶人數的 200 倍,但不是說每位用戶每小時最多只能呼叫 200 次;只要所有用戶的總呼叫次數未超過應用程式上限,任一用戶每小時都能呼叫超過 200 次。舉例來說,如果應用程式有 100 位用戶,應用程式每小時可以發出 20,000 次呼叫,但互動最多的前十名用戶可能就佔了 19,000 次。

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

應用程式用戶人數是以每日活躍用戶人數和當天新登入人數計算。若每日使用量偏低,也會使用每週甚至每月活躍用戶來計算應用程式用戶人數。無論應用程式實際擁有多少安裝次數,相較於每日互動少的應用程式,每日互動多的應用程式會有較高的限速。

注意事項:

  • 並非所有的 API 呼叫都會受到限速的影響,所以您發出的呼叫次數可能會與限速工具中顯示的資訊不完全相符。
  • 我們也會根據使用的 CPU 時間和總時間來限制呼叫。若端點須進行大量處理,則儘管低於呼叫次數限制,還是可能讓應用程式達到限速。除了特定端點外,應用程式鮮少達到 CPU 時間和總時間限制。若有使用大量 CPU 時間或總時間的端點資訊,可在歷史資料圖表中查看。
  • 廣告洞察報告 API行銷 API 可能使用不同組限速。如需有關行銷 API 的詳細資訊,請參閱行銷 API 限速文件(https://developers.facebook.com/docs/marketing-api/api-rate-limiting)。

建議處理方式

若要避免遭到限速:

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

限速標頭

所有圖形 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 回應的效能,但是無法為了限速的目的而降低呼叫次數。

您也可以使用 Batch API 來批次發出要求,但是請注意,每個子要求都會計為一次 API 呼叫,在指定多個編號的情況下甚至會計為多次 API 呼叫。

如果應用程式或粉絲專頁遭到限速,發生限速錯誤的 API 呼叫仍會計入限速次數。


我的應用程式會看到什麼錯誤?
限速類型 至少 錯誤代碼

應用程式層級限速

每小時、每用戶 200 次呼叫

4

帳號層級限速

不適用

17

粉絲專頁層級限速

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

32

自訂層級限速

不適用

613


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

如果錯誤回應含 error_subcode 1996,表示 Facebook 已注意到您的應用程式 API 要求數量不一致。如果您最近進行了會影響 API 要求數量的變更,可能就會遭遇這個錯誤。

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


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

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