您對數據存儲的請求可能因為連接不良或其他問題而失敗。要處理錯誤並返回帶有錯誤代碼的消息,請將數據存儲函數包裝在 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 | 因為未啟用 API 訪問,無法從 Studio 寫入 DataStore。 | 必須啟用 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 體驗級別速率限制。 |
限制
數據模型有 限制。如果體驗超過這些限制,服務會自動限制體驗的數據存儲使用,並使未來的請求放入以下隊列之一:
- 設置
- 有序設置
- 獲取
- 有序獲取
隊列中的請求按接收順序處理。調用的函數在請求仍在隊列中時會繼續讓步。如果數據存儲鍵本身被限制,請求將被放入隊列,但會暫時跳過。
每個隊列的請求限制為 30 個請求。當隊列的限制達到時,請求將以 301-306 範圍內的錯誤代碼失敗,表示請求已完全丟棄。
訪問限制
數據存儲受 體驗和伺服器級別限制 的約束。體驗級別限制隨著體驗中的總並發用戶數而變化,而伺服器級別限制是可配置的,旨在作為創作者的工具。
體驗限制
每個體驗根據數據存儲類型、請求類型和並發用戶數允許一定數量的數據存儲請求。對於每種類型的數據存儲和請求類型,限制在所有列出的函數之間共享。
- 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('The API_KEY environment variable is not set.');
}
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(`\nProcessing entry: ${path}`);
const currentData = await getEntry(path);
currentData.value.currency += 10;
const payload = { value: currentData.value };
const updateResponse = await updateEntry(path, payload);
console.log(`Status: ${updateResponse.status}`);
console.log(`Response: ${await updateResponse.text()}`);
}
} catch (error) {
console.error('An error occurred during execution:', 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 |
| 刪除版本(已棄用) | 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 |
數據限制
數據存儲限制每個條目可以使用的數據量。
數據存儲名稱、鍵名和 範圍 必須都在一定的字符長度之下。使用 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 錯誤,具體取決於是否超過了單個數據存儲或鍵的吞吐量限制。這些錯誤消息適用於有序和標準數據存儲。
存儲限制
為了保持存儲穩定和可擴展,數據存儲對您的存儲使用量使用遊戲級別的限制。
此限制由每個遊戲的基本分配加上基於終身用戶數的額外分配組成。終身用戶是指至少加入過您的遊戲一次的任何用戶。
存儲限制的計算公式為 Total latest version storage limit = 500 MB + 1 MB × lifetime user count。
存儲使用量是使用每個鍵的最新版本的 壓縮大小 來衡量的。數據存儲在存儲之前會自動壓縮您的數據,因此請避免自己進行預壓縮。預壓縮會增加不必要的 CPU 開銷,並可能降低數據存儲內置壓縮的有效性。通過存儲未壓縮的數據,您自動受益於 Roblox 的壓縮算法和未來基於架構的優化的改進。
只有每個鍵的最新版本計入您的存儲使用量。已刪除的鍵和被取代的版本在其保留期間內仍可通過版本 API 訪問,但不計入您的存儲使用量。然而,通過開放雲 DeleteDataStore 方法刪除的數據存儲在其 30 天刪除處理期間內仍計入存儲使用量,直到它們被永久刪除。