MemoryStoreService 是一个高吞吐量和低延迟的数据服务,提供快速的内存数据存储,所有服务器在实时会话中均可访问。内存存储 适合频繁和短暂的数据,这些数据变化迅速且不需要持久化,因为它们访问更快,并在达到最大生命周期时消失。对于需要在会话之间持久化的数据,请使用 数据存储。
数据结构
内存存储有三种原始数据结构,供服务器共享以快速处理,而不是直接访问原始数据:排序映射、队列 和 哈希映射。每种数据结构适合某些用例:
- 基于技能的匹配 - 在服务器之间的共享 队列 中保存用户信息,例如技能水平,并使用大厅服务器定期进行匹配。
- 跨服务器交易和拍卖 - 启用不同服务器之间的通用交易,用户可以对实时变化价格的物品进行竞标,使用 排序映射 的键值对。
- 全球排行榜 - 在共享的 排序映射 中存储和更新用户排名。
- 共享库存 - 在共享的 哈希映射 中保存库存物品和统计数据,用户可以同时使用库存物品。
- 持久数据的缓存 - 将您的持久数据同步并复制到可以作为缓存的内存存储 哈希映射 中,从而提高游戏性能。
一般来说,如果您需要根据特定键访问数据,请使用哈希映射。如果您需要数据有序,请使用排序映射。如果您需要以特定顺序处理数据,请使用队列。
限制和配额
为了维护可扩展性和系统性能,内存存储对内存大小、API 请求和数据结构大小有数据使用配额。
内存存储有基于过期时间的驱逐策略,也称为生存时间(TTL)。项目在过期后被驱逐,内存配额被释放以供新条目使用。当您达到内存限制时,增加内存使用的请求将失败,直到您释放内存或增加配额。有关选项,请参见 从内存配额耗尽中恢复。
内存大小配额
内存配额限制游戏可以消耗的总内存量。它不是固定值;而是根据游戏中的用户数量随时间变化,公式为 64 KB + 1.2 KB * [用户数量]。配额适用于游戏级别,而不是服务器级别。
当用户加入游戏时,额外的内存配额会立即可用。当用户离开游戏时,配额不会立即减少。配额在八天的追溯期后重新评估为较低值。
在您的游戏达到内存大小配额后,任何增加内存大小的 API 请求都会失败。减少或不改变内存大小的请求仍然成功。
通过 可观察性 仪表板,您可以实时查看游戏的内存大小配额,使用 内存使用情况 图表。
API 请求限制
请求单位 配额适用于所有 MemoryStoreService API 调用。此配额为每分钟 1000 + 120 * [并发用户数量] 请求单位。
大多数 API 调用只消耗一个请求单位,少数例外:
MemoryStoreSortedMap:GetRangeAsync()
根据返回的项目数量消耗单位。例如,如果此方法返回 10 个项目,则调用计为 10 个请求单位。如果返回空响应,则计为一个请求单位。
根据返回的项目数量消耗单位,类似于 MemoryStoreSortedMap:GetRangeAsync(),但在读取时每两秒消耗一个额外单位。使用 waitTimeout 参数指定最大读取时间。
MemoryStoreHashMap:UpdateAsync()
消耗至少两个单位。
MemoryStoreHashMap:ListItemsAsync()
消耗 [扫描的分区数量] + [返回的项目数量] 单位。
请求配额也适用于游戏级别,而不是服务器级别。这提供了灵活性,可以在服务器之间分配请求,只要总请求速率不超过配额。如果您超过配额,当服务限制您的请求时,您将收到错误响应。
通过可观察性功能,您可以实时查看游戏的请求单位配额。
数据结构大小限制
对于单个排序映射或队列,适用以下大小和项目计数限制:
- 最大项目数量:1,000,000
- 最大总大小(包括排序映射的键):100 MB
每分区限制
除了游戏级别的 请求单位配额 外,内存存储还对每个分区施加请求限制,以保护所有游戏的服务稳定性。这些限制不是分配给您游戏的配额,也不是您游戏可以实现的吞吐量的硬上限。以下值是估算值。它们在 Roblox 后端配置,可能会更改,因此请不要将其视为固定数字。
每个请求都计入持有项目的 分区 的限制,无论数据结构是什么。您目前可以预计在单个分区的请求速率大约为 30,000 请求单位每分钟 时开始限流,因此请尽量保持在该速率以下。数据结构消耗该限制的多少取决于其项目的分布:
- 排序映射和队列 各自位于单个分区,因此对这些数据结构的每个请求都计入同一分区限制。
- 哈希映射 将其项目分散到多个分区,因此跨多个项目键的流量很少接近任何一个分区的限制。
哈希映射对每个项目键还有额外的限制,大约为 5,000 写请求单位每分钟 和 15,000 读请求单位每分钟。此每键限制适用于每个分区限制之上,因此频繁访问的键可能会触及其中一个。每键限制仅适用于单键操作:读取限制适用于 MemoryStoreHashMap:GetAsync(),写入限制适用于 MemoryStoreHashMap:SetAsync() 和 MemoryStoreHashMap:RemoveAsync(),而 MemoryStoreHashMap:UpdateAsync() 同时计入读取和写入限制。MemoryStoreHashMap:ListItemsAsync() 扫描分区而不是单个键,因此仅适用每分区限制。

如果您不需要排序或先进先出功能,哈希映射通常是最佳选择,因为它可以将负载分散到多个分区。
当请求超过分区或每键限制时,服务会限制它们并返回 PartitionRequestsOverLimit 状态代码,您可以通过 可观察性 仪表板进行监控。
如果您预计某个数据结构或项目键会接收高且持续的请求速率,请 分片 以便负载分散到更多分区或键。均匀分配读取和写入到多个项目键,以保持在每键限制内。您还可以通过在服务器上缓存值并在一段时间后重新检查它们、尽可能批量请求以及在收到限流响应时应用 指数退避 来减少请求速率。
从内存配额耗尽中恢复
如果您的游戏收到 TotalMemoryOverLimit 错误,请检查 可观察性仪表板 中的 内存使用情况 图表。要恢复增加内存使用的写入,请删除不需要的项目,等待项目过期,或使用以下选项之一。
使用开放云刷新内存存储
如果您不再需要存储的数据,请使用开放云 刷新内存存储 端点异步清除选定范围内的所有内存存储数据结构。
要刷新内存存储:
- 创建 API 密钥,并授予刷新内存存储和获取目标宇宙的刷新操作状态的权限。
- 向 https://apis.roblox.com/cloud/v2/universes/{universe_id}/memory-store:flush 发送 POST 请求,并在 x-api-key 头中包含 API 密钥。将 {universe_id} 替换为您游戏的宇宙 ID。将 scope 查询参数设置为 LIVE 以获取生产数据,或设置为 TEST 以获取 Studio 数据。如果省略 scope,则端点使用 LIVE。
- 使用 获取内存存储刷新操作 轮询刷新请求返回的操作,直到 done 为 true,并检查是否有 error。轮询时使用相同的范围。返回的 path 已包含 cloud/v2,因此在 https://apis.roblox.com/{path} 轮询时无需添加其他前缀。
Studio 和生产内存存储是 隔离的。刷新一个范围不会清除另一个范围。在清除不需要的数据后,请遵循 最佳实践,例如缩短过期时间和显式删除,以防止内存使用再次达到配额。
使用扩展服务增加容量
如果您的游戏需要保留数据并使用超过默认配额允许的更多存储,请为内存存储启用 扩展服务。扩展服务允许您为超出默认配额的内存存储和请求付费。
要开始,请满足 资格要求,添加帐户详细信息和付款方式,然后在 创作者仪表板 中选择您的游戏。在 扩展服务 下,启用内存存储并为所需资源设置每月预算。有关详细信息,请参见 启用服务 和 服务定价。
如果使用超过您的预算,扩展服务会限制服务。监控使用情况和计费,并继续 删除不需要的数据。
最佳实践
为了保持您的内存使用模式最佳并避免达到 限制,请遵循以下最佳实践:
删除已处理的项目。 使用 MemoryStoreQueue:RemoveAsync() 方法定期清理读取的项目(对于队列)和使用 MemoryStoreSortedMap:RemoveAsync()(对于排序映射)可以释放内存并保持数据结构的最新状态。
在添加数据时将过期时间设置为尽可能短的时间。 尽管 MemoryStoreQueue:AddAsync() 和 MemoryStoreSortedMap:SetAsync() 的默认过期时间为 45 天,但设置尽可能短的时间可以自动清理旧数据,以防止它们填满您的内存使用配额。
- 不要存储大量数据并设置长过期时间,因为这可能会导致超过内存配额,并可能导致问题,甚至破坏整个游戏。
- 始终显式删除不需要的项目或设置短的项目过期时间。
- 通常,您应该使用显式删除来释放内存,并将项目过期作为安全机制,以防止未使用的项目长时间占用内存。
仅在内存中保留必要的值。
例如,对于拍卖行游戏,您只需维护最高出价。您可以在一个键上使用 MemoryStoreSortedMap:UpdateAsync() 来保持最高出价,而不是在数据结构中保留所有出价。
使用 指数退避 来帮助保持在 API 请求限制以下。
例如,如果您收到 DataUpdateConflict,您可以在两秒后重试,然后是四秒、八秒等,而不是不断向 MemoryStoreService 发送请求以获取正确的响应。
通过 分片 将大型数据结构拆分为多个较小的数据结构。
通常在较小的结构中管理数据更容易,而不是将所有内容存储在一个大型数据结构中。这种方法还可以帮助避免使用和速率限制。例如,如果您有一个使用前缀作为键的排序映射,请考虑将每个前缀分离到自己的排序映射中。对于特别受欢迎的游戏,您甚至可以根据用户 ID 的最后几位数字将用户分成多个映射。
在哈希映射中对频繁访问的键进行 分片,使用多个键的副本来分散负载。
压缩存储的值。
例如,考虑使用 LZW 算法来减少存储值的大小。
注册扩展服务。
对于超出默认配额的存储或请求使用,请 为内存存储启用扩展服务。
可观察性
可观察性仪表板 提供了监控和故障排除内存存储使用情况的见解和分析。通过实时更新的图表,您可以跟踪游戏的内存使用模式,查看当前分配的配额,监控 API 状态,并识别潜在的性能优化问题。
下表列出了可在可观察性仪表板的 按状态的请求计数 和 按 API x 状态的请求 图表中找到的所有 API 响应状态代码及其描述。有关如何解决这些错误的更多信息,请参见 故障排除。有关错误相关的特定配额或限制,请参见 限制和配额。
| 状态代码 | 描述 |
|---|---|
| 成功 | 成功。 |
| DataStructureMemoryOverLimit | 超过数据结构级别内存大小限制(100 MB)。 |
| DataUpdateConflict | 由于并发更新而发生冲突。 |
| AccessDenied | 无权访问游戏数据。此请求不消耗请求单位或使用配额。 |
| InternalError | 内部错误。 |
| InvalidRequest | 请求没有所需的信息或信息格式错误。 |
| DataStructureItemsOverLimit | 超过数据结构级别项目计数限制(1M)。 |
| NoItemFound | 在 MemoryStoreQueue:ReadAsync() 或 MemoryStoreSortedMap:UpdateAsync() 中未找到项目。ReadAsync() 每 2 秒轮询一次,并在找到队列中的项目之前返回此状态代码。 |
| DataStructureRequestsOverLimit | 超过数据结构级别请求单位限制(每分钟 100,000 请求单位)。 |
| PartitionRequestsOverLimit | 超过 每分区或每键请求单位限制。 |
| TotalRequestsOverLimit | 超过宇宙级别请求单位限制。 |
| TotalMemoryOverLimit | 超过宇宙级别内存配额。 |
| ItemValueSizeTooLarge | 值大小超过限制(32 KB)。 |
下表列出了客户端状态代码,这些状态代码当前在可观察性仪表板上不可用。
| 状态代码 | 描述 |
|---|---|
| InternalError | 内部错误。 |
| UnpublishedPlace | 您必须发布此地点才能使用 MemoryStoreService。 |
| InvalidClientAccess | MemoryStoreService 必须从服务器调用。 |
| InvalidExpirationTime | 字段 'expiration' 时间必须在 0 到 3,888,000 之间。 |
| InvalidRequest | 无法将值转换为 json。 |
| InvalidRequest | 无法将 sortKey 转换为有效的数字或字符串。 |
| TransformCallbackFailed | 调用转换回调函数失败。 |
| RequestThrottled | 最近的 MemoryStores 请求触及一个或多个限制。 |
| UpdateConflict | 超过最大重试次数。 |
故障排除
下表列出了每个响应状态代码的推荐解决方案:
| 错误 | 故障排除选项 |
|---|---|
| DataStructureRequestsOverLimit / PartitionRequestsOverLimit |
|
| TotalRequestsOverLimit | |
| DataStructureItemsOverLimit |
|
| DataStructureMemoryOverLimit | |
| TotalMemoryOverLimit |
|
| DataUpdateConflict |
请求中止示例 |
| 内部错误 |
|
| 无效请求 |
|
| 项目值大小过大 |
|
在 Studio 中测试和调试
MemoryStoreService 中的数据在 Studio 和生产之间是隔离的,因此在 Studio 中更改数据不会影响生产行为。这意味着您从 Studio 的 API 调用不会访问生产数据,允许您在投入生产之前安全地测试内存存储和新功能。
Studio 测试具有与生产相同的 限制和配额。对于基于用户数量计算的配额,结果配额可能非常小,因为您是 Studio 测试的唯一用户。在 Studio 测试时,您可能还会注意到与生产使用相比,延迟略高且错误率上升,因为执行了一些额外检查以验证访问和权限。
有关如何在实时游戏或在 Studio 中测试时调试内存存储的信息,请使用 开发者控制台。