> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 精細速率限制

> XBOX 服務精細速率限制 (FGRL) 的概觀，包括高載和持續限制、HTTP 429 回應，以及如何使用 XSTA 偵測節流。

本文提供 XBOX 服務精細速率限制 (FGRL) 的概觀。
除了摘要說明什麼是速率限制之外，本文也旨在協助您判斷自己是否遭到限制，以及如果遭到限制，有哪些工具和資源可供您使用。

**精細速率限制**的目的是促進不同遊戲之間**公平使用**共用的 XBOX 資源。
此解決方案類似於大多數傳統的限制系統，由服務記錄實體在指定期間內提出的要求數目。

達到服務指定限制的實體接著會移至拒絕狀態，來自該實體的所有傳入要求都會遭到拒絕。
實體只有在指定期間到期、導致實體的相關計數重設時，才能脫離此狀態。

精細速率限制使用上述相同的核心機制，不過 FGRL 追蹤的不是單一實體，而是**使用者和遊戲**的組合，並將相關計數與**兩個**不同的**限制** (而非一個) 進行比較。
FGRL 雙重限制是針對每個服務強制執行的，這表示 GameClips 的要求計數不會影響 Presence 的要求計數。

下列各節將更詳細地說明使用者和遊戲配對、雙重限制，以及 HTTP 429 限制回應物件。

## 精細速率限制的術語

| 詞彙 | 定義 |
| - | - |
| FGRL | 精細速率限制 (Fine-Grained Rate Limiting) |
| XSAPI | XBOX 服務應用程式開發介面 |
| CU | 內容更新 |
| 高載 | 代表在短時間內收到的要求量 |
| 持續 | 代表在一段時間內持續收到的大量呼叫 |
| 使用者 + 遊戲 | 代表將使用者和遊戲配對為一個實體 |
| XSTA | XBOX 服務 Trace Analyzer 工具，用於判斷您的遊戲是否受到速率限制 |

## 公平使用

XBOX 認為，無論使用者正在玩什麼遊戲 (或應用程式)，每位使用者都應該擁有相同的高品質體驗。
精細速率限制 (FGRL) 解決了下列案例：

開發人員 A 剛發行了一款遵循所有 XBOX 服務最佳做法、確保服務最佳使用的遊戲，而開發人員 B 也剛發行了一款遊戲，但這款遊戲有一個未知的錯誤。
此錯誤導致遊戲和每位使用者大量傳送線上狀態要求，使服務承受沉重的負載。
服務變慢並最終停止，破壞了開發人員 A 之使用者的體驗，即使造成問題的是開發人員 B 的錯誤。

如果實作了 FGRL，服務就能停止接收來自行為異常之遊戲的要求，讓它能為開發人員 A 的遊戲提供其應得的公平資源份額。

## 遊戲和使用者細微度

選擇遊戲和使用者作為索引鍵，是為了確保公平使用 XBOX 資源。

只追蹤使用者會造成使用者體驗受制於每個遊戲之整合的情況。
例如，大多數遊戲都已在使用 People 服務，因此就此範例而言，假設在 People 服務上設定了精細速率限制，允許 5 分鐘內不超過 100 個要求。

如果使用者玩的遊戲在 1 分鐘內提出 100 個要求，就會超過限制，使用者將無法再對 People 服務提出任何要求；想像一下，在同一期間內，使用者接著返回主畫面並按一下其好友清單：由於使用者已經超過限制，該好友清單呼叫會失敗，直到 5 分鐘的間隔過去為止，即使主畫面並不是讓使用者處於受限狀態的原因。

另一方面，只根據遊戲進行限制也會產生同樣不公平的結果。
為每個遊戲設定限制會忽略遊戲的熱門程度，而要求只會以先到先服務的方式處理，直到達到限制為止。

使用者和遊戲的配對可確保任何遊戲使用的資源都不會超過根據作用中使用者數目而言適當的資源，同時也為每位使用者提供一致的資源份額。

![速率限制要求和回應流程圖](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/services/FGRL.png?fit=max\&auto=format\&n=gzrdvT5kpqAXKEQt\&q=85\&s=239325bee1cba0140da0f07b0e0d4a54)

上圖顯示要求處理方式的高階檢視。
首先產生要求，然後由所需的服務接收。
收到要求時，系統會檢查使用者和遊戲一起存取服務的次數：

* 如果要求低於限制，則會正常處理。
* 如果發現要求已達到或超過限制，服務會捨棄該要求，並改為傳回 429 回應。

回應會指出期間還要多久才會重設，以及何時可以處理使用者和遊戲的要求。

## 高載和持續限制

傳統上，速率限制包含每個端點一個在指定期間內追蹤的限制。
此期間代表追蹤實體要求計數的時間長度。
期間結束時，實體的計數會重設為 0，以重新開始追蹤。

這種方法適用於大多數 API；不過，對於呼叫 XBOX 服務的遊戲和應用程式而言，這種方法的復原能力不足。
上述解決方案假設人們以一致、穩定、可預測的方式進行呼叫。
在 XBOX 服務的情況下，根據服務和提出要求的遊戲，呼叫模式會有很大的差異。

在此情況下只選擇一個限制，將需要在呼叫模式範圍的兩端都做出妥協。
XBOX 服務解決方案使用兩個期間和限制。
較短的期間稱為高載期間，而較長的期間則稱為持續期間。

FGRL 的高載期間一律為 15 秒，而持續期間一律為 300 秒 (5 分鐘)。
因此，在 5 分鐘的持續期間內，有 20 個高載期間。

高載和持續限制會同時追蹤，因此會同時計算要求。
高載和持續限制都設定在服務上，這表示每個服務都有自己的高載和持續計數。

為了協助您了解這兩個限制如何一起運作，下表顯示使用者在玩某個遊戲時，該遊戲對已實作 FGRL 的服務提出多個要求的情況。
在此案例中，高載限制為 15 秒內 30 個要求，而持續限制為 5 分鐘內 100 個要求。

| 時間期間 (秒) | 每個高載期間的要求數 | 每個持續期間的要求數 | 15 秒間隔內遭節流的要求數 | 哪個限制？(高載、持續或兩者) |
| - | - | - | - | - |
| 0-15 | 35 | 35 | 5 | 高載 |
| 15-30 | 28 | 63 | 0 | 不適用 |
| 30-45 | 21 | 84 | 0 | 不適用 |
| 45-60 | 36 | 120 | 20 | 兩者 |
| 60-75 | 24 | 144 | 24 | 持續 |
| … | … | … | | … |
| 285-300 | 4 | 148 | | 持續 |

此表格顯示，在前 15 秒內，使用者提出 35 個要求而觸發了高載限制。
那 5 個額外的要求會遭到捨棄，並傳送 5 個 429 回應。

這 5 個要求雖然遭到節流，但仍會計入持續限制。
一旦觸發任一限制，就不會讓任何要求通過，如兩個限制在第 45 秒時都被觸發，以及在第 285 秒時只提出 4 個要求的情況所示。

## HTTP 429 回應物件

當相關的使用者和遊戲計數達到或超過高載或持續限制時，服務將不會處理該要求，而是傳回 HTTP 429 回應。使用 XSAPI 時，這相當於 HRESULT 0x801901AD。
HTTP 429 代碼代表「要求過多」，並會隨附包含「在 X 秒後重試」值的標頭。

FGRL 429 回應物件包含 "retry after" 標頭，指定呼叫實體在重試之前應等待的時間長度。
使用 XSAPI 的開發人員不必擔心，因為 XSAPI 會遵守並處理 Retry-After 標頭。

實際的回應會包含下列欄位：

| 欄位名稱 | 值類型 | 範例 | 定義 |
| - | - | - | - |
| Version | Integer | `"version":1` | |
| currentRequests | Integer | `"currentRequests":13` | 傳送的要求總數 |
| maxRequests | Integer | `"maxRequests":10` | 允許的要求總數 |
| periodInSeconds | Integer | `"periodInSeconds":15` | 時間範圍 |
| Type | String | `"type":"burst"` | 節流限制類型 |

## 已實作的限制

下列服務已實作 FGRL 限制，且自 **2016 年 5 月**起已強制執行這些限制。
這些限制在所有沙箱和遊戲中都相同。

**任何透過 XBOX 開發人員平台或 Partner Center 發佈，且在 2016 年 5 月之前出貨的遊戲，都會被視為舊版，因此予以豁免。**

| **名稱** | **高載限制** (每位使用者每個遊戲 15 秒) | **持續限制** (每位使用者每個遊戲 300 秒) | **認證限制** (持續的 10 倍，每位使用者每個遊戲 300 秒) |
| - | - | - | - |
| Stats Read | 100 | 300 | 3000 |
| Profile | 10 | 30 | 300 |
| MPSD | 30 | 300 | 3000 |
| Search Handle (MPSD) | Read 1, Write 1 | Read 20, Write 20 | Read 20, Write 20 |
| MPA Recent Players | 3 | 50 | 50 |
| MPA Invites | 7 | 50 | 50 |
| MPA Activity | Create/Delete 10, Read/Query 20 | Create/Delete 100, Read/Query 200 | Create/Delete 100, Read/Query 200 |
| Presence | Read 10, Write 3 | Read 100, Write 30 | Read 1000, Write 300 |
| Social | 10 | 30 | 300 |
| Leaderboards | 30 | 100 | 1000 |
| Achievements | 100 | 300 | 3000 |
| Smart Match | 10 | 100 | 1000 |
| User Posts | 100 | 300 | 3000 |
| Stats Write | 100 | 300 | 3000 |
| Privacy | 10 | 30 | 300 |
| Clubs | 10 | 30 | 300 |
| Authentication (僅限 S2S) | 15 | 50 | 500 |

上表代表目前選定進行 FGRL 的服務清單。
此清單並非最終版本，因為可以新增新的服務和現有的服務。
當即將新增某個服務時，將會更新此表格並發出公告。

表格中的限制可能會變更。
隨著服務的變更和演進，限制也會隨之變更；不過，您會收到通知，且會進行必要的舊版豁免。

## 服務對應和速率限制對遊戲的影響

| **名稱** | **服務端點** | **FGRL 對遊戲的預期影響** |
| - | :-: | - |
| Stats Read | userstats.xboxlive.com | 成就或排行榜項目未更新或未擷取。 |
| Profile | profile.xboxlive.com | 玩家的資料未正確更新或顯示。 |
| MPSD | sessiondirectory.xboxlive.com | 加入/邀請無法正確完成，工作階段未正確建立或更新，可能導致遊戲失敗。 |
| MPA | multiplayeractivity.xboxlive.com | 加入/邀請無法正確完成，最近的玩家資訊無法正確運作。 |
| Presence | presence.xboxlive.com | 玩家的遊戲內線上狀態將不準確。 |
| Social | social.xboxlive.com | 影響所有好友寫入 (例如新增好友、將某人設為最愛等)，並可能影響好友讀取 (例如擷取我的好友清單)。建議開發人員呼叫 peoplehub 進行讀取，而不是 social.xboxlive.com。 |
| Leaderboards | leaderboards.xboxlive.com | 排行榜的遊戲內 UX 將不會填入/更新。 |
| Achievements | achievements.xboxlive.com | 已解除成就的遊戲內 UX 將不會更新。 |
| Smart Match | momatch.xboxlive.com | 無法成功設定比賽。 |
| User Posts | userposts.xboxlive.com | 使用者貼文將不會出現。 |
| Stats Write | statswrite.xboxlive.com | 成就或排行榜項目未更新。 |
| Privacy | privacy.xboxlive.com | 隱私權失敗可能會導致所有呼叫端的存取遭到封鎖。 |
| Clubs | Clubhub.xboxlive.com | 玩家可能無法看到其遊戲內俱樂部。 |
| Authentication (僅限 S2S) | title.mgt.xboxlive.com | 服務對服務呼叫驗證將會失敗。 |

\*\*注意：\*\*最新的 API 對應會定期更新，您可以在 [Live Trace Analyzer API 對應](https://github.com/Microsoft/xbox-live-trace-analyzer/blob/master/Source/XboxLiveTraceAnalyzer.APIMap.csv)下找到。

## 常見問題集

### 如何判斷我是否遭到節流，以及我可以採取哪些步驟？

請參閱[呼叫 XBOX 服務的最佳做法](https://docs.xbox.com/zh-TW/services/xbox-services/develop/best-practices/live-best-practices-calling-xbl.md)，其中包含改善呼叫模式的步驟，以及說明如何使用 XSAPI 判斷提示和 XSAPI 社交與多人遊戲管理員來通知您節流問題並緩解這些節流問題。

另一個選項是記錄 XBOX 服務呼叫的追蹤，然後使用 [XBOX 服務 Trace Analyzer 工具](https://learn.microsoft.com/windows/uwp/xbox-live/tools/analyze-service-calls)分析該追蹤。
若要記錄追蹤，您可以使用 Fiddler 記錄 .SAZ 檔案，或使用 XSAPI 的內建追蹤記錄。

若要在 XSAPI 中開啟及使用追蹤，請參閱[用於檢閱服務呼叫的 Trace Analyzer](https://docs.xbox.com/zh-TW/tools/tools-services/live-trace-analyzer.md)。
取得追蹤之後，XBOX 服務 Trace Analyzer 工具會在偵測到遭到節流的呼叫時發出警告。

### 限制會變更嗎？

我們的意圖是已發佈的限制不會隨時間變更。
不過，如果有需要，部分限制有可能會變得更嚴格；在此情況下，已發行至 RETAIL 的遊戲將不受更新後的限制約束。

### 是否會有更多服務設定限制？

是的，更多服務和新服務可以且將會建立限制。
不過，就像這第一次的 FGRL 發行一樣，您會收到通知，且會採取適當的預防措施。

### 這些變更何時生效？

速率限制自 **2016 年 5 月**起已強制執行。
自 **2018 年 4 月**起，超過指定持續限制 10 倍或以上的遊戲將無法通過 XBOX 認證程序。

### 如果我們無法遵守限制怎麼辦？

請參閱[呼叫 XBOX 服務的最佳做法](https://docs.xbox.com/zh-TW/services/xbox-services/develop/best-practices/live-best-practices-calling-xbl.md)，並確保您遵循這些步驟。
如果您在任何社交服務上遭到速率限制，也請考慮使用[社交管理員](https://docs.xbox.com/zh-TW/services/xbox-services/community/social-manager/live-social-manager-nav.md)

如果在遵循這些步驟之後，您仍然無法保持在限制以下，請連絡您的開發人員客戶經理。

**注意：2018 年 4 月之後，達到或超過指定限制的遊戲將不允許通過認證。**
例如，如果持續限制如上表所指定設定為 300 秒內 300 次呼叫，則在 300 秒內達到或超過 3000 次呼叫的遊戲將無法通過認證。
如需包括測試案例在內的詳細資訊，請參閱 [XR-132 服務存取限制](https://aka.ms/xrs)。

### 我現有的遊戲呢？

任何在 2018 年 4 月之前於 RETAIL 中的遊戲都會被視為舊版，因此予以豁免。

### 內容更新呢？

對於舊版或已豁免的遊戲，內容更新也會予以豁免，不過我們強烈建議您利用這些工具和資產來最佳化遊戲的服務整合層面。

### 在我能進行內容更新之前，可以為我的遊戲取得豁免嗎？

請與您的開發人員客戶經理洽談。


## Related topics

- [Microsoft Store API 的精細速率限制](https://docs.xbox.com/zh-TW/publishing/xstore-commerce/xstore-fgrl.md)
- [最佳做法](https://docs.xbox.com/zh-TW/services/xbox-services/develop/best-practices/index.md)
- [統計資料和成就](https://docs.xbox.com/zh-TW/build/steam-porting-guide/features/stats-and-achievements.md)
- [呼叫 XBOX 服務的最佳做法](https://docs.xbox.com/zh-TW/services/xbox-services/develop/best-practices/live-best-practices-calling-xbl.md)
- [與 PlayFab Lobby 和 Match 整合](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpa/concepts/live-mpa-playfab-integration.md)