> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.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 | 内容更新 (Content Update) | | Burst(突发) | 表示短时间内接收到的请求量 | | Sustain(持续) | 表示在一段时间内持续接收到的大量调用 | | User + Title | 表示用户与标题作为一个实体的配对 | | XSTA | XBOX 服务跟踪分析器工具,用于确定您的标题是否被速率限制 | ## 公平使用 XBOX 认为,无论用户玩什么游戏(或应用),每位用户都应获得相同的高质量体验。 细粒度速率限制 (FGRL) 解决了以下场景: 开发者 A 刚刚发布了一款遵循所有 XBOX 服务最佳实践的标题,可确保最佳地使用服务;而开发者 B 也刚刚发布了一款标题,但存在未知错误。 此错误导致该标题及每个用户不断发送 Presence 请求,使服务承受重负载。 服务变慢并最终停止,破坏了开发者 A 用户的体验,尽管问题是由开发者 B 的错误引起的。 如果实施了 FGRL,该服务本可停止接收来自行为异常标题的请求,从而使开发者 A 的标题能够获得其应有的资源份额。 ## 标题与用户粒度 之所以选择"标题与用户"作为关键,是为了确保 XBOX 资源的公平使用。 仅跟踪用户会造成用户体验受制于每个标题集成方式的场景。 例如,大多数标题已使用 people 服务,在此假设情况下,假定细粒度速率限制在 people 服务上设置为 5 分钟内不超过 100 次请求。 如果用户玩一款在 1 分钟内发出 100 次请求的游戏,则会超过限制,用户将无法再向 people 服务发出更多请求;设想在同一时段内用户随后返回主屏幕并点击好友列表:由于用户已经超过限制,该好友列表调用将失败,直到 5 分钟间隔过去,即使主屏幕并未导致用户进入受限状态。 或者,仅基于标题限制也会产生同样不公平的结果。 按标题设置限制会忽略标题的热门程度,请求将只是按先到先得的顺序处理,直到达到限制。 用户与标题的配对可确保任何标题都不会使用超出其活跃用户数量所对应的适当资源,同时也让每位用户获得一致的资源份额。 速率限制请求和响应流程图 上图展示了请求处理的高层视图。 首先生成请求,然后由目标服务接收。 收到请求后,系统会检查用户和标题共同访问该服务的次数: * 如果请求低于限制,则按正常方式处理。 * 如果发现请求达到或超过限制,则服务将丢弃该请求并返回 429 响应。 响应将指示还需多长时间才能滚动到下一个周期,以便处理该用户和标题的请求。 ## 突发和持续限制 传统上,速率限制包含每个端点在给定时间段内跟踪的一个限制。 此时间段代表跟踪实体请求计数的持续时长。 在此期间结束时,实体计数将重置为 0,以便重新开始跟踪。 此方法适用于大多数 API;但是,这种方法对调用 XBOX 服务的游戏和应用来说不够稳健。 上述解决方案假设人们以稳定、一致、可预测的方式调用。 对于 XBOX 服务的情况,根据服务和请求标题的不同,调用模式差别很大。 在这种情况下只选择一个限制,需要在调用模式频谱的两端都作出妥协。 XBOX 服务解决方案使用两个时间段和两个限制。 较短的时间段称为突发 (Burst) 时段,较长的称为持续 (Sustain) 时段。 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 Developer Platform 或 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 only) | 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 only) | title.mgt.xboxlive.com | 服务到服务的调用身份验证将失败。 | **注意:** 最新的 API 映射会定期更新,可在 [Live 跟踪分析器 API 映射](https://github.com/Microsoft/xbox-live-trace-analyzer/blob/master/Source/XboxLiveTraceAnalyzer.APIMap.csv)中查看。 ## 常见问题 ### 如何确定我正在被限流,以及可以采取哪些措施? 请参见[调用 XBOX 服务的最佳实践](/services/xbox-services/develop/best-practices/live-best-practices-calling-xbl),其中包含改进调用模式的步骤,以及如何使用 XSAPI 断言和 XSAPI Social 与 Multiplayer 管理器来通知您有关限流问题并缓解这些问题的说明。 另一种选择是记录 XBOX 服务调用的跟踪,然后使用 [XBOX 服务跟踪分析器工具](https://learn.microsoft.com/windows/uwp/xbox-live/tools/analyze-service-calls)分析该跟踪。 要记录跟踪,您可以使用 Fiddler 记录 .SAZ 文件,或使用 XSAPI 内置的跟踪日志记录。 要在 XSAPI 中打开并使用跟踪,请参见[用于查看服务调用的跟踪分析器](/tools/tools-services/live-trace-analyzer)。 获得跟踪后,XBOX 服务跟踪分析器工具会在检测到被限流的调用时发出警告。 ### 限制会更改吗? 其意图是随着时间的推移,已公布的限制不会更改。 但是,如有必要,某些限制可能会变得更严格;在这种情况下,已发行至零售版本的标题将免受更新后限制的影响。 ### 是否会有更多服务实施限制? 是的,更多服务和新服务都可能并将会实施限制。 就像此次 FGRL 首次发布一样,您将得到通知,并采取相应的预防措施。 ### 这些更改何时生效? 速率限制自 **2016 年 5 月**起开始实施。 自 **2018 年 4 月**起,超出指定持续限制 10 倍或更多的标题将无法通过 XBOX 认证流程。 ### 如果我们无法遵守限制怎么办? 请参见[调用 XBOX 服务的最佳实践](/services/xbox-services/develop/best-practices/live-best-practices-calling-xbl),并确保您遵循这些步骤。 如果您在使用任何社交服务时被速率限制,还可考虑使用 [Social Manager](/services/xbox-services/community/social-manager/live-social-manager-nav) 如果按照这些步骤后您仍然无法保持在限制之下,请联系您的开发者客户经理 (Developer Account Manager)。 **注意:2018 年 4 月之后,达到或超过指定限制的标题将不允许通过认证。** 例如,如果如上表所示,持续限制设定为 300 秒内 300 次调用,那么 300 秒内达到或超过 3000 次调用的标题将无法通过认证。 有关详细信息(包括测试用例),请参见 [XR-132 服务访问限制](https://aka.ms/xrs)。 ### 我的现有标题呢? 任何在 2018 年 4 月之前已进入零售的标题都被视为遗留标题,并可豁免。 ### 内容更新? 对于遗留或已豁免的标题,内容更新也将豁免,不过我们强烈建议您利用相应工具和资源来优化游戏的服务集成方面。 ### 在完成内容更新之前,能否为我的游戏获得豁免? 请与您的开发者客户经理联系。 ## Related topics - [Microsoft Store API 的细粒度速率限制](/zh-CN/publishing/xstore-commerce/xstore-fgrl.md) - [Stats 与成就](/zh-CN/build/steam-porting-guide/features/stats-and-achievements.md) - [排行榜](/zh-CN/build/steam-porting-guide/features/steam-leaderboards.md) - [调用 XBOX 服务的最佳实践](/zh-CN/services/xbox-services/develop/best-practices/live-best-practices-calling-xbl.md) - [与 PlayFab Lobby 和 Match 集成](/zh-CN/services/xbox-services/multiplayer/mpa/concepts/live-mpa-playfab-integration.md)