此页面列出了数据存储对请求、数据、吞吐量和存储施加的限制,随后是失败请求返回的错误代码。
限制
数据模型有限制。如果体验超出这些限制,服务会自动限制体验的数据存储使用,并导致未来的请求被放置在以下队列之一:
- 设置
- 有序设置
- 获取
- 有序获取
队列中的请求按接收顺序处理。调用的函数会继续让出控制权,只要其请求仍在队列中。如果数据存储键本身被限制,请求将被放置在队列中,但会被暂时跳过。
每个队列的请求限制为30个。当队列的限制达到时,请求将以301-306范围内的错误代码失败,表示请求已被完全丢弃。
数据限制
数据存储限制每个条目可以使用的数据量。
数据存储名称、键名称和范围都必须在一定字符长度之内。使用string.len()检查它们的长度。
数据(键值)也作为字符串存储,无论其初始类型如何。您可以使用JSONEncode()函数检查数据的大小,该函数将Luau数据转换为序列化的JSON表。
| 组件 | 最大字符数 |
|---|---|
| 数据存储名称 | 50 |
| 键名称 | 50 |
| 范围 | 50 |
| 数据(键值) | 每个键4,194,304 |
元数据限制
用户定义的元数据字符数限制。
| 组件 | 最大字符数 |
|---|---|
| 键名称 | 50 |
| 值 | 250 |
| 键值对 | 300 |
吞吐量限制
每个键的吞吐量限制确保Roblox服务器的性能最佳。每个限制适用于体验中所有服务器的每个单独键,并会随着时间的推移而刷新。
Roblox检查与该键相关的配额在过去60秒内的使用情况。如果使用量(包括当前请求)在吞吐量限制内,请求将被批准。如果使用量超过限制,请求将被拒绝。
| 请求类型 | 游戏服务器API | 开放云API | 限制 |
|---|---|---|---|
| 读取 | GetAsync() GetVersionAsync() GetVersionAtTimeAsync() ListVersionsAsync() UpdateAsync() | 获取数据存储条目 | 每分钟25 MB |
| 写入 | SetAsync() IncrementAsync() UpdateAsync() RemoveAsync() | 创建、更新、增量、删除数据存储条目 | 每分钟4 MB |
除了上述吞吐量限制外,Roblox根据内部架构将数据组织成分区。因此,当后端服务器接收到对同一数据存储的高请求量时,可能会导致进一步的限制。无论原因如何,限制表现为DatastoreThrottled或KeyThrottled错误,具体取决于是单个数据存储还是键的吞吐量限制被超出。这些错误消息适用于有序和标准数据存储。
存储限制
为了保持存储的稳定性和可扩展性,数据存储在您的存储使用上使用游戏级限制。
此限制由每个游戏的基本分配加上基于终身用户数量的额外分配组成。终身用户是指至少加入过您游戏的任何用户。
存储限制的计算公式为总最新版本存储限制 = 500 MB + 1 MB × 终身用户数量。
存储使用量是通过每个键的压缩大小来衡量的。数据存储在存储之前会自动压缩您的数据,因此请避免自己进行预压缩。预压缩会增加不必要的CPU开销,并可能降低数据存储内置压缩的有效性。通过存储未压缩的数据,您将自动受益于Roblox压缩算法的改进和未来基于架构的优化。
只有每个键的最新版本计入您的存储使用量。已删除的键和被取代的版本在其保留期内仍可通过版本API访问,但不计入您的存储使用量。然而,通过开放云DeleteDataStore方法删除的数据存储在其30天的删除处理期间仍会计入存储使用量,直到它们被永久删除。
访问限制
数据存储受体验和服务器级限制的约束。体验级限制随着体验中的总并发用户数量而变化,而服务器级限制是可配置的,旨在作为创作者的工具。
体验限制
每个体验允许根据数据存储类型、请求类型和并发用户数量进行一定数量的数据存储请求。对于每种数据存储类型和请求类型,限制在所有列出的函数之间共享。
- UpdateAsync()同时消耗读取和写入请求预算。单个调用将减少两个限制。
- 游戏服务器和开放云共享预算;开放云流量可能会受到体验内使用的限制(反之亦然)。有关进一步指导,请参见控制速率限制。
标准数据存储
| 请求类型 | 游戏服务器API | 开放云API | 共享限制(每分钟请求数) |
|---|---|---|---|
| 读取 | GetAsync() GetVersionAsync() GetVersionAtTimeAsync() UpdateAsync() | 获取数据存储条目 | 300 + concurrentUsers × 40 |
| 写入 | SetAsync() IncrementAsync() UpdateAsync() | 创建、更新、增量数据存储条目 | 300 + concurrentUsers × 20 |
| 列出 | ListDataStoresAsync() ListKeysAsync() ListVersionsAsync() | 列出数据存储、列出数据存储条目、列出数据存储条目修订版 | 300 + concurrentUsers × 2 |
| 删除 | RemoveAsync() | 删除数据存储条目、删除数据存储、恢复数据存储 | 300 + concurrentUsers × 40 |
有序数据存储
| 请求类型 | 游戏服务器API | 开放云API | 共享限制(每分钟请求数) |
|---|---|---|---|
| 读取 | GetAsync() BatchGetAsync() UpdateAsync() | 获取有序数据存储条目 | 300 + concurrentUsers × 40 |
| 写入 | SetAsync() IncrementAsync() UpdateAsync() | 创建、更新、增量有序数据存储条目 | 300 + concurrentUsers × 20 |
| 列出 | GetSortedAsync() | 列出有序数据存储条目 | 300 + concurrentUsers × 2 |
| 删除 | RemoveAsync() | 删除有序数据存储条目 | 300 + concurrentUsers × 40 |
控制速率限制
由于开放云和游戏服务器请求是共享的,因此独立控制每个请求可以消耗多少预算非常重要。
游戏服务器
单个服务器具有内置限制,如上所述。使用SetRateLimitForRequestType()和GetRequestBudgetForRequestType()的组合来保持对单个服务器对总预算贡献的细粒度控制。
开放云
开放云请求需要外部速率限制解决方案。我们推荐以下方法之一:
- (简单)在每个请求后添加短暂的超时,特别是在连续循环中调用相同的API。将此超时设置为60 / (每分钟所需预算消耗)秒,作为上限。请注意,这种方法不允许请求以突发方式发送。
- (稳健)使用漏桶策略实现本地速率限制器。
以下Node.js代码示例包括参考实现。
const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error('API_KEY环境变量未设置。');
}
const apiHeaderKey = 'x-api-key';
const universeId = '';
const dataStoreId = 'Inventory';
const baseUrl = 'https://apis.roblox.com/cloud/v2/';
// --- 每个操作的速率限制配置(每分钟请求数)---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;
// 每个操作的上限间隔:60 / (每分钟请求数)秒。
const LIST_INTERVAL_MS = (60 / LIST_RATE_PER_MIN) * 1000;
const GET_INTERVAL_MS = (60 / GET_RATE_PER_MIN) * 1000;
const UPDATE_INTERVAL_MS = (60 / UPDATE_RATE_PER_MIN) * 1000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 执行请求,然后在返回之前等待该操作自己的间隔。
async function throttledFetch(url, options, intervalMs) {
const response = await fetch(url, options);
await sleep(intervalMs);
return response;
}
async function listEntries(universe, dataStore) {
const listPath = `universes/${universe}/data-stores/${dataStore}/entries`;
const url = baseUrl + listPath;
const response = await throttledFetch(url, {
headers: { [apiHeaderKey]: apiKey }
}, LIST_INTERVAL_MS);
return response.json();
}
async function getEntry(path) {
const url = baseUrl + path;
const response = await throttledFetch(url, {
headers: { [apiHeaderKey]: apiKey }
}, GET_INTERVAL_MS);
return response.json();
}
async function updateEntry(path, payload) {
const url = baseUrl + path;
const response = await throttledFetch(url, {
method: 'PATCH',
headers: {
[apiHeaderKey]: apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload) // 请求体必须是字符串
}, UPDATE_INTERVAL_MS);
return response;
}
(async () => {
try {
const entries = await listEntries(universeId, dataStoreId);
for (const entry of entries.dataStoreEntries) {
const path = entry.path;
console.log(`\n处理条目: ${path}`);
const currentData = await getEntry(path);
currentData.value.currency += 10;
const payload = { value: currentData.value };
const updateResponse = await updateEntry(path, payload);
console.log(`状态: ${updateResponse.status}`);
console.log(`响应: ${await updateResponse.text()}`);
}
} catch (error) {
console.error('执行期间发生错误:', error);
}
})();服务器限制
每个服务器对每种请求类型都有可配置的速率限制,基于该服务器中的玩家数量。服务器在首次创建时会获得一次性启动突发的额外请求预算。使用GetRequestBudgetForRequestType()确认当前服务器在任何给定时间可以发出的数据存储请求数量。
这些限制是可由创作者配置的,使用 SetRateLimitForRequestType() API。使用此API,创作者可以为每种请求类型配置自己的数据存储速率限制。
如果未调用API,则适用以下默认速率限制:
标准数据存储
| 请求类型 | DataStoreRequestType枚举 | 游戏服务器API | 每分钟请求数 |
|---|---|---|---|
| 读取 | StandardRead | GetAsync() GetVersionAsync() GetVersionAtTimeAsync() UpdateAsync() | 60 + numPlayers × 40 |
| 写入 | StandardWrite | SetAsync() IncrementAsync() UpdateAsync() | 60 + numPlayers × 40 |
| 列出 | StandardList | ListDataStoresAsync() ListKeysAsync() ListVersionsAsync() | 5 + numPlayers × 2 |
| 删除 | StandardRemove | RemoveAsync() | 60 + numPlayers × 40 |
| RemoveVersion (已弃用) | RemoveVersionAsync | RemoveVersionAsync() | 5 + numPlayers × 2 |
有序数据存储
| 请求类型 | DataStoreRequestType枚举 | 游戏服务器API | 每分钟请求数 |
|---|---|---|---|
| 读取 | OrderedRead | GetAsync() BatchGetAsync() UpdateAsync() | 60 + numPlayers × 40 |
| 写入 | OrderedWrite | SetAsync() IncrementAsync() UpdateAsync() | 30 + numPlayers × 5 |
| 列出 | OrderedList | GetSortedAsync() | 5 + numPlayers × 2 |
| 删除 | OrderedRemove | RemoveAsync() | 30 + numPlayers × 5 |
错误代码参考
您对数据存储的请求可能由于连接不良或其他问题而失败。要处理错误并返回带有错误代码的消息,请将数据存储函数包装在pcall()中。
例如,UpdateAsync()的写入调用失败,意味着游戏服务器未收到成功响应。这并不总是保证后端写入未发生。在某些失败场景中,最终写入状态可能在通过后续读取(无缓存)验证之前对调用者未知。
| 错误代码 | 错误名称 | 错误消息 | 备注 | |
|---|---|---|---|---|
| 101 | KeyNameEmpty | 键名称不能为空。 | 检查输入到数据存储函数的键是否为空字符串。 | |
| 102 | KeyNameLimit | 键名称超过50个字符的限制。 | 检查输入到数据存储函数的键是否超过50的长度。 | |
| 103 | ValueNotAllowed | 无法在DataStore中允许X。 | 一个错误的更新函数返回了类型为X的值。 | |
| 104 | CantStoreValue | 无法在DataStore中存储X。 | 更新函数返回了一个类型为X的值,该值无法序列化。 | |
| 105 | ValueTooLarge | 序列化值超过X限制。 | 如果您使用SetAsync()或UpdateAsync()设置值,则序列化的值长度不能超过X的大小。要检查数据的序列化长度,请使用JSONEncode()。 | |
| 106 | MaxValueInvalid | MaxValue必须是整数。 | 如果您为GetSortedAsync()传递最大值,则它必须是整数。 | |
| 106 | MinValueInvalid | MinValue必须是整数。 | 如果您为GetSortedAsync()传递最小值,则它必须是整数。 | |
| 106 | PageSizeGreater | PageSize必须在预定义范围内。 | 对于OrderedDataStore,最小页面大小为1。 | |
| 106 | PageSizeLesser | PageSize必须在预定义范围内。 | 对于OrderedDataStore,最大页面大小为100。 | |
| 107 | MinMaxOrderInvalid | MaxValue必须大于或等于MinValue。 | 对于GetSortedAsync(),最大值必须大于或等于最小值。 | |
| 301 | GetAsyncThrottle | GetAsync请求被丢弃。请求被限制但队列已满。 | GetAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | |
| 302 | SetAsyncThrottle | SetAsync请求被丢弃。请求被限制但队列已满。 | SetAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | |
| 303 | IncreAsyncThrottle | IncrementAsync请求被丢弃。请求被限制但队列已满。 | IncrementAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | |
| 304 | UpdateAsyncThrottle | UpdateAsync请求被丢弃。请求被限制但队列已满。 | UpdateAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | |
| 304 | TransformThrottle | UpdateAsync请求被丢弃。请求被限制但队列已满。 | UpdateAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | |
| 305 | GetSortedThrottle | GetSorted请求被丢弃。请求被限制但队列已满。 | GetSortedAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | |
| 306 | RemoveAsyncThrottle | RemoveAsync请求被丢弃。请求被限制但队列已满。 | RemoveAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | |
| 401 | DataModelNoAccess | 请求失败。DataModel在体验关闭时无法访问。 | DataModel未初始化,因为体验正在关闭。 | |
| 402 | LuaWebSrvsNoAccess | 请求失败。LuaWebService在体验关闭时无法访问。 | LuaWebService未初始化,因为体验正在关闭。 | |
| 403 | StudioAccessToApisNotAllowed | 无法从Studio写入DataStore,因为未启用API访问。 | 必须激活API访问才能在Studio中使用数据存储。 | |
| 404 | InternalError | OrderedDataStore不存在。 | 与此请求相关的OrderedDataStore未找到。这可能是数据损坏的迹象。请稍后再试。 | |
| 501 | InternalError | 无法解析响应,因为数据可能已损坏。 | 服务器无法解析对您请求的响应。这可能是数据损坏的迹象。请稍后再试。 | |
| 502 | RequestRejected | API服务拒绝了请求,错误X。 | 处理Roblox服务器时发生错误X。请稍后再试。 | |
| 503 | InternalError | 数据存储请求成功,但未找到键。 | 请求的键在数据存储中未找到。这可能是数据损坏的迹象。请稍后再试。 | |
| 504 | InternalError | 数据存储请求成功,但响应格式不正确。 | 服务器无法解析对您请求的响应。这可能是数据损坏的迹象。请稍后再试。 | |
| 505 | InternalError | OrderedDataStore请求成功,但响应格式不正确。 | 服务器无法解析对您的OrderedDataStore请求的响应。这可能是数据损坏的迹象。请稍后再试。 | |
| 509 | OperationNotAllowed | 在个人RCC上运行时,数据存储操作被阻止,以防止可能的数据损坏。 | 在私有RCC通道上阻止数据存储写入。 | |
| 511 | AttributeSizeTooLarge | 元数据属性大小超过X限制。 | 序列化的元数据大小超过X的限制。值X是动态的。如果大小发生变化,值也会变化。 | |
| 512 | UserIdLimitExceeded | UserID大小超过X限制。 | 用户提供的用户ID数组的长度超过X的限制。 | |
| 513 | AttributeFormatError | 属性userId格式无效。 | 提供的用户ID不是数字。 | |
| 513 | AttributeFormatError | 属性元数据格式无效。 | 元数据不是表。 | |
| GetVersionAsyncThrottle | GetVersionAsync请求被丢弃。请求被限制。 | GetVersionAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | ||
| GetVersionAtTimeAsyncThrottle | GetVersionAtTimeAsync请求被丢弃。请求被限制。 | GetVersionAtTimeAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | ||
| ListDataStoresAsyncThrottle | ListDataStoresAsync请求被丢弃。请求被限制。 | ListDataStoresAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | ||
| ListKeysAsyncThrottle | ListKeysAsync请求被丢弃。请求被限制。 | ListKeysAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | ||
| ListVersionsAsyncThrottle | ListVersionsAsync请求被丢弃。请求被限制。 | ListVersionsAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | ||
| RemoveVersionAsyncThrottle | RemoveVersionAsync请求被丢弃。请求被限制。 | RemoveVersionAsync()请求已超过最大队列大小,Roblox无法在当前吞吐量下处理请求。 | ||
| InvalidTimestamp | 时间戳必须为正数且不超过十分钟。 | 提供给GetVersionAtTimeAsync()的时间戳无效。 | ||
| StandardReadExperienceThrottled | StandardRead请求被体验限制限制。 | 对GetAsync()、GetVersionAsync()、GetVersionAtTimeAsync()或标准数据存储的UpdateAsync()的请求超过了StandardRead体验级速率限制。 | ||
| StandardWriteExperienceThrottled | StandardWrite请求被体验限制限制。 | 对SetAsync()、IncrementAsync()或标准数据存储的UpdateAsync()的请求超过了StandardWrite体验级速率限制。 | ||
| StandardListExperienceThrottled | StandardList请求被体验限制限制。 | 对标准数据存储的ListKeysAsync()、ListVersionsAsync()或ListDataStoresAsync()的请求超过了StandardList体验级速率限制。 | ||
| StandardRemoveExperienceThrottled | StandardRemove请求被体验限制限制。 | 对标准数据存储的RemoveAsync()的请求超过了StandardRemove体验级速率限制。 | ||
| OrderedReadExperienceThrottled | OrderedRead请求被体验限制限制。 | 对GetAsync()、BatchGetAsync()或有序数据存储的UpdateAsync()的请求超过了OrderedRead体验级速率限制。 | ||
| OrderedWriteExperienceThrottled | OrderedWrite请求被体验限制限制。 | 对SetAsync()、IncrementAsync()或有序数据存储的UpdateAsync()的请求超过了OrderedWrite体验级速率限制。 | ||
| OrderedListExperienceThrottled | OrderedList请求被体验限制限制。 | 对有序数据存储的GetSortedAsync()的请求超过了OrderedList体验级速率限制。 | ||
| OrderedRemoveExperienceThrottled | OrderedRemove请求被体验限制限制。 | 对有序数据存储的RemoveAsync()的请求超过了OrderedRemove体验级速率限制。 | ||
| StandardReadGameServerThrottled | StandardRead请求被游戏服务器限制或请求队列已满。 | 对GetAsync()、GetVersionAsync()、GetVersionAtTimeAsync()或标准数据存储的UpdateAsync()的请求超过了StandardRead游戏服务器级速率限制。 | ||
| StandardWriteGameServerThrottled | StandardWrite请求被游戏服务器限制或请求队列已满。 | 对SetAsync()、IncrementAsync()或标准数据存储的UpdateAsync()的请求超过了StandardWrite游戏服务器级速率限制。 | ||
| StandardListGameServerThrottled | StandardList请求被游戏服务器限制或请求队列已满。 | 对标准数据存储的ListKeysAsync()、ListVersionsAsync()或ListDataStoresAsync()的请求超过了StandardList游戏服务器级速率限制。 | ||
| StandardRemoveGameServerThrottled | StandardRemove请求被游戏服务器限制或请求队列已满。 | 对标准数据存储的RemoveAsync()的请求超过了StandardRemove游戏服务器级速率限制。 | ||
| OrderedReadGameServerThrottled | OrderedRead请求被游戏服务器限制或请求队列已满。 | 对GetAsync()、BatchGetAsync()或有序数据存储的UpdateAsync()的请求超过了OrderedRead游戏服务器级速率限制。 | ||
| OrderedWriteGameServerThrottled | OrderedWrite请求被游戏服务器限制或请求队列已满。 | 对SetAsync()、IncrementAsync()或有序数据存储的UpdateAsync()的请求超过了OrderedWrite游戏服务器级速率限制。 | ||
| OrderedListGameServerThrottled | OrderedList请求被游戏服务器限制或请求队列已满。 | 对有序数据存储的GetSortedAsync()的请求超过了OrderedList游戏服务器级速率限制。 | ||
| OrderedRemoveGameServerThrottled | OrderedRemove请求被游戏服务器限制或请求队列已满。 | 对有序数据存储的RemoveAsync()的请求超过了OrderedRemove游戏服务器级速率限制。 |
服务器错误代码
| 错误名称 | 错误消息 | 备注 |
|---|---|---|
| DatastoreDeleted | 数据存储已被删除。 | 无法对数据存储执行操作,因为数据存储之前已被删除。 |
| DatastoreThrottled | 请求速率超过datastore允许的最大值。 | 对单个数据存储发送了太多请求。 |
| InternalServerError | 发生内部服务器错误。 | Roblox服务器上偶尔发生的错误。请再试一次,最好使用指数退避。 |
| InvalidExclusiveStartKey | 提供的独占起始键无效。 | 提供给诸如ListKeysAsync()的列表操作的独占起始键(光标)无效。 |
| InvalidPlace | 提供的地点无效。 | 该地点没有匹配的宇宙ID。请稍后再试。 |
| InvalidTarget | 提供的目标无效。 | 有序数据存储键名称超过50个字符的限制。 |
| InvalidUniverse | 提供的宇宙无效。 | 该宇宙没有匹配的地点ID。请稍后再试。 |
| InvalidUserIds | 提供的用户ID格式无效。 | 解析用户ID失败。 |
| KeyThrottled | 请求速率超过该键允许的最大值。 | 请求速率超过单个键允许的最大请求速率。 |
| KeyNotFound | 请求的键不存在。 | 该键不存在。 |
| N/A | 没有页面可以继续。 | 当您在最后一页上调用Pages:AdvanceToNextPageAsync()时会发生此错误。 |
| StandardReadExperienceThrottled | 标准读取请求速率超过体验允许的最大值。 | 对GetAsync()、GetVersionAsync()、GetVersionAtTimeAsync()或标准数据存储的UpdateAsync()的请求超过了StandardRead体验级速率限制。 |
| StandardWriteExperienceThrottled | 标准写入请求速率超过体验允许的最大值。 | 对SetAsync()、IncrementAsync()或标准数据存储的UpdateAsync()的请求超过了StandardWrite体验级速率限制。 |
| StandardListExperienceThrottled | 标准列出请求速率超过体验允许的最大值。 | 对标准数据存储的ListKeysAsync()、ListVersionsAsync()或ListDataStoresAsync()的请求超过了StandardList体验级速率限制。 |
| StandardRemoveExperienceThrottled | 标准删除请求速率超过体验允许的最大值。 | 对标准数据存储的RemoveAsync()的请求超过了StandardRemove体验级速率限制。 |
| OrderedReadExperienceThrottled | 有序读取请求速率超过体验允许的最大值。 | 对GetAsync()、BatchGetAsync()或有序数据存储的UpdateAsync()的请求超过了OrderedRead体验级速率限制。 |
| OrderedWriteExperienceThrottled | 有序写入请求速率超过体验允许的最大值。 | 对SetAsync()、IncrementAsync()或有序数据存储的UpdateAsync()的请求超过了OrderedWrite体验级速率限制。 |
| OrderedListExperienceThrottled | 有序列出请求速率超过体验允许的最大值。 | 对有序数据存储的GetSortedAsync()的请求超过了OrderedList体验级速率限制。 |
| OrderedRemoveExperienceThrottled | 有序删除请求速率超过体验允许的最大值。 | 对有序数据存储的RemoveAsync()的请求超过了OrderedRemove体验级速率限制。 |