Graph API 的速率上限

速率上限會定義在特定時間內可以進行的 API 調用次數上限。每個應用程式都設有速率上限。

過度或持續超過速率上限的應用程式可能會遭到停用。

在 Facebook Graph API 中,應該只有在少數情況會限制速率。這份文件將描述限制為何且該如何處理。

您的應用程式可能會碰到兩種主要的速率上限類型:應用程式層級速率上限與專頁層級速率上限。

應用程式層級速率上限

這些限制適用於使用各種存取憑證(除專頁存取憑證以外)的調用。

凡是在超過速率上限後由應用程式進行的 API 調用,都會受到限速而失敗,並出現 error code = 4, CodedException。過去一小時用量回到上限以內時,調用才會繼續順利完成。上限是一小時接著一小時來計算,目前的用量百分比則可在應用程式管理中心查看。

速率上限管理中心

速率限制工具可以提供您有關應用程式距離限速門檻還有多近的相關資訊。透過應用程式管理中心的兩個圖表,您可以瞭解對應用程式有影響的速率上限。

  • 其中一個圖表會顯示對回傳的 Graph API 回應有影響的目前用量。Graph 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 的詳細資料。

建議事項

若要避免遭到限速:

  • 在兩個時間範圍內平均分配查詢次數,以避免傳送尖峰流量。
  • 使用篩選條件以限制資料回應的大小,並避免使用要求重複資訊的調用。
  • 使用速率上限標頭以便靈活控制調用數量的餘額。

速率上限標頭

凡是對 Graph 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 調用?

會依速率限制計算所有調用次數,而不只是個人 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 調用次數仍會計入速率上限的統計。


我的應用程式會看到哪些錯誤?
流速控制類型 至少 錯誤代碼

應用程式層級限速

200 次調用/用戶/小時

4

帳戶層級限速

不適用

17

專頁層級限速

4800 次調用/用戶/24 小時

32

自訂層級限速

不適用

613


我收到錯誤代碼 613,我該怎樣做?

如果您的錯誤回應包含 error_subcode 1996,表示 Facebook 發現您應用程式的 API 要求量出現不穩的情形。如果您最近已作出任何會影響 API 要求量的變更,可能就會看到這個錯誤。

如果您沒有看到子程式碼,表示您的應用程式超過了自訂傳輸率限制。請通知您的合作夥伴經理協助解決這個問題。


我正在建立擷取程式,有哪些注意事項?

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