Graph API 的速率上限

在 Facebook Graph 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 調用次數仍會計入速率上限的統計。

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

應用程式層級限速

200 次調用/用戶/小時

4

帳戶層級限速

不適用

17

專頁層級限速

4800 次調用/用戶/24 小時

32

自訂層級限速

不適用

613

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

您的應用程式超過了自訂速率限制。請通知您的合作夥伴經理協助解決這個問題。

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

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