F8 2019 Day 1 當天，Graph API v3.3 正式上線，在這一新版本下，除一如往例的進行了一系列 API 的新增與 deprecated 之外，還引入了一套全新的 API Rate Limiting 機制，名為：Business Use Case rate limiting system，而這全新的 Rate Limiting 系統涵蓋了 Page-level、Instagram account 以及 Ad Account 等三大 API 集，在進行詳細說明前，#Nova編 先簡單的摘要如下

• Instagram 相關 API 的 Rate Limiting 計算基準將由原本計算 App 的使用者人數改為計算Instagram帳號在過去24小時所取得的曝光數（Impressions）
• Page-level 的 Rate-Limiting 計算將與所有其他的 Graph API 切分開來，也就是說自 Graph API v3.3 開始，所有針對Page-level 的 API 請求將不計算入 Graph API 的節流機制（Throttling）
• 針對廣告系統相關的API的Rate Limiting機制被切分為兩個部分
  1. 讀取Ad Insights的API
  2. 讀取Ad Insights API之外的所有API（包含Campaign、Ad Set、Ad的CRUD等等…）

以下，就讓 #Nova編 一一的來為各位解釋

Business Use Case rate limiting system？

簡單說，如果你開發的應用會出現在臉書設定中的 Business Integration 裡的話，那你的App的應用場景就一定包含在Business Use Case這一全新的API Rate Limiting架構下，這主要包含

1. 透過取得Instagram相關權限去對Instagram account進行CRUD的API
2. 透過Page Access Token或是System User Access Token進行操作的Page相關APIs
3. 讀取Facebook廣告系統所有Insights相關APIs

在上述三種場景之外的API請求不論是在 v3.3 前後，都是延續套用原本的Application-level或是User-level的API Rate Limiting架構，在可見的未來，Whatspp相關的APIs應該也會是被涵蓋在這新架構下。

Instagram Rate Limiting

如前所述，凡跟Instagram相關的API都是排除在Graph API的閥流計算之外，並根據Instagram帳號在過去24小時內所取得的Impressions數量來決定開發者進行API請求的Rate Limiting值，有以下兩種情境，你的App所發出的API請求會進入Rate Limiting狀態

1. API請求次數超過允許的上限：App可以對Instagram account相關API發送請求次數的上限值決定於過去24小時內IG account取得的曝光數（Impressions）乘上4,800，也就是說在過去24小時，你的IG帳號每增加一個曝光，你的App就會增加4,800次API請求的Quota
2. CPU時間佔用達到許可上限：根據文件說明，這非常罕見會觸及，但對Facebook的Infra來說，有些API需要耗用的系統CPU資源會比其他的APIs來得高，如果你的App是大量集中的在請求那些會大量佔用Facebook Infra CPU運算資源的APIs，那你就有可能因此觸及CPU消耗時間許可的上限而進入Rate Limiting狀態

當你的App進入Rate Limiting狀態，你後續的API請求都會收到 Error code 80002，一但收到這，你就得啟動防衛機制，降低並分散你App對API的請求，直到你的App離開Rate Limiting狀態。

Page Level Rate Limiting

只要你的App是透過Page Access Token或是System User Access Token來進行API的操作，那你的所有API請求都將套用在Business Use Case的Rate Limiting架構，不會計入Graph API的Rate Limiting計算架構中，但要注意的是，只要你對Page相關API的存取不是使用上述的Page Access Token或是System User Access Token的話，你的API請求預設將會套用在App-level或是User-level的Rate Limiting架構，端看你用的是App Access Token還是User Access Token。

在以下情境下，你的App會進入Page-level的Rate Limiting的狀態

1. API請求次數超過允許的上限：Page-level的API請求上限計算是過去24小時的時間窗（Sliding Window）內你的粉絲團所取得的engaged user數量乘上4,800，假設在過去24小時的時間窗內你的Page有100位用戶被認定為是engaged user，那你的在當前時間窗內，你透過Page Access Token或是System User Access Token進行API請求的次數上限將會是 4,800 x 100 = 480,000次，一但超過這個數字，你的App就會進入Rate Limiting的狀態，這邊要額外特別說明的是，所謂的engaged user，指的是在過去24小時時間窗內有對Page進行過互動的user，包含對Page進行Like的user以及對Page貼文進行過like、comment以及share等等互動的user，於此同時要注意的是，Page engaged user的計算是每幾分鐘就會進行更新，因此Page在計算engaged user數量的24小時的開始與結束時間是持續在變動的，而不是以一個固定的開始與結束時間作為計算基準，這也就是為何要稱作24小時時間窗的原因。
2. CPU時間佔用達到許可上限：這其實跟上面所提到的IG account API裡的幾乎一樣，這邊就不贅述了

Ad Insights Level Rate Limiting

如同先前所提到的，自Open Graph API v3.3開始，Ad Insights API的Rate Limiting計算方式將與其他Marketing API切分開來並套用在全新的Business Use Case Rate Limiting架構之下，同時也跟Page-level與Instagram account一樣，API的請求並不與Open Graph API的Throttling一併計算，但除了上述相似點之外，Ad Insights API與其Page-level以及Instagram account有一個非常大的差異處，那就是在API請求次數的計算方式，Ad Insights API在計算可使用的API請求次數並不採用如同Page-level以及IG account一樣的24小時時間窗計算方式，而是綜合了App對Marketing API的Access Tier、廣告帳號中的廣告數量以及過去一段時間內對Marketing API發送請求的錯誤次數來計算出你的App可以對Ad Insights API進行API呼叫的次數。

所以，跟Page-level以及IG account一樣，當你的App發生

1. 超過Facebook透過App Access Tier、廣告帳號下廣告數量以及過去一段時間內針對Marketing API發出請求的錯誤次數等參數所綜合計算出來的API請求次數上限
2. CPU時間佔用達到許可上限（不贅述）

上述三種屬於Business Use Case的Rate Limit所套用的場景，可以透過API回傳的Header中的x-business-use-case-usage來進行防禦性的系統設計，如下圖所示

將該Header回傳的JSON解開來看會是如下圖的內容

我們可以用上圖中的資訊來決定是否接下來的API請求要進入調節與分散的防禦性操作

非Ad Insights之外的其他Marketing API

Marketing API有一套完全不同於其他Graph API的Rate Limiting計算邏輯，所以也如同前述的Page-level、Instagram account以及Ad Insights level一樣，他也不會列入Graph API的Rate Limiting計算中，但這組APIs相對於其他APIs多了以下一些特殊的Rate Limiting，記住，以下的限制都要把除了Ad Insights API排除在外

API Level Limit

API-level的Rate Limiting是套用在Ad Account Level上，每一次的Marketing API都會在被指派一個score，這個score就是你的App在一段特定的時間內（官方文件上沒有明確說是多長）所發出API請求次數的總和，Facebook有指定一個不知名的score數量限制，一但你發出去的API請求中包含的score超過這個謎之數字的話，你的App就會進入Rate Limit狀態，你可以透過檢查API請求是否收到Error Code 17來判斷是否你的App已經進入Rate Limit狀態，一但你的App進入Rate Limit狀態，你的App在一分鐘之內將無法再發送出API請求，在這段Rate Limit的期間，你的score會逐漸下降，並在五分鐘內下降至0這個數字，要注意的是，App透過Marketing API對廣告系統進行更新（Update）的操作相對於新增（Create）的操作是10 ~ 100倍的量級，所以官方文件上建議不要頻繁的進行廣告活動、行銷組合以及廣告的變更操作

在預防性的系統設計上，開發人員可以透過檢查Marketing API所回傳的Header中的 x-ad-account-usage，來做後續API的發送是否要進行節流與時間區間分散的依據

附註：以前在寫廣告系統的時候很多人行銷人員很喜歡假會的去頻繁更新Ad Set的預算、競價上限、預算搬移等等更新式的操作，以為可以勝過Facebook廣告系統的演算法，看來這些Rate Limit的限制很多是針對這些獵奇的操作而來的

App Level Limits

App透過Marketing API進行廣告系統的操作時，除了等會會提到的Ad Account、Ad Set以及Ad Level的限制之外，

Ad Account Level Limits

App在一段時間內（不知道詳細數字）透過API對Ad Account的spend_cap以及spend_cap_action等欄位進行變更的次數是受限（詳細次數也不知道），由於官方文件沒有說明詳細的限制數量，目前只能透過監測是否API呼叫回傳Error Code 17來決定是否你的App觸及到這個限制

Ad Set level Limits

App透過API每小時只能對Ad Set的daily_budget以及lifetime_budget欄位進行4次的變更，一但超過這個限制也就是收到Error Code 17，你的App就會被封鎖，一個小時後才能恢復對Ad Set進行變更的操作

Ad-level Limits

每一個App每日能建立的Ad數量受到Daily Spend Limit這一個參數的設定值所影響，當你發出的API請求收到Error code 1487225時，就代表你的App已經進入了Rate Limiting的狀態

小結一下

Facebook的Rate Limit可以說是一個我一直很想寫篇專文來分享的議題，這次正好藉著F8 2019後在Graph API v3.3開始引入的 Business Use Case Rate Limiting 這個新架構的機會來為各位簡單的整理了一下，我將會在後續的文章中更近一步的分享我過去在處理對 Facebook API 進行大量請求時針對各種不同層級的 Rate Limit 以及API端點請求限制時如何進行調節與分散API請求以利讓各種商業邏輯能夠不受Rate Limit而能繼續運作下去的一些實務，我畢竟只是略懂略懂，還望各位不吝賜教