数据存储 | 文档 - Roblox 创作者中心

Class.DataStoreService 允许您存储在不同会话之间需要持续的数据，例如玩家的物品栏或技能点。数据存储是按体验一致的，因此在体验中的任何地方都可以访问并更改相同的数据，包括在不同服务器上的地点。

如果您想要将粒度权限控制添加到您的数据存储和在 Studio 或 Roblox 服务器之外访问它们，您可以使用使用云端 API 为数据存储添加粒度权限控制。

对于您需要更新或访问频繁的临时数据，请使用内存存储。

启用工作室访问

默认情况下，在 Studio 中测试的体验无法访问数据存储，因此您必须先启用它们。在 Studio 中访问数据存储可能会对实时体验有危险，因为 Studio 访问客户端应用程序的同一数据存储。要避免覆盖生产数据，请不要为实时体验启用此设置。相反，请为独立测试版本的体验启用它。

要在发布体验中启用 Studio 访问：

前往主页 > 游戏设置 > 安全。
启用启用 Studio 访问 API 服务切换。
单击保存。

访问数据存储

要访问体验中的数据存储：

将 DataStoreService 添加到服务器端 Script 。
使用 GetDataStore() 函数，指定要使用的数据存储。如果数据存储不存在，Studio 会在您首次保存体验数据时创建一个。


local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

服务器只能通过 Scripts 访问数据存储。尝试客户端通过 LocalScript 访问时会发生错误。

创建数据

数据存储其实是一个词典，类似于 Lua 表。独特的钥匙索引在数据存商店中的每个值，像用户的独特 Player.UserId 或用户名为一个体验促销的命名字串。

用户数据钥匙	值值
31250608	50
351675979	20
505306092	78000
促销数据钥匙	值值
特殊活动	夏季派对 2
激活促销代码	奖励123
可以访问 party place	真的

要创建一个新的条目，请使用 SetAsync() 使用键名和一个值。


local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, errorMessage = pcall(function()
	experienceStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

像 SetAsync() 这样的函数，可能会时常发生网络调用。为了检查和处理错误，请确保这些调用被包围在 pcall() 中。

更新数据

要更改数据存商店中的任何存储值，请使用 UpdateAsync() 使用入口的钥匙名和一个回调函数来更新该条目。此回调使用当前值并基于逻辑返回新值。如果回调返回 nil，写入操作已取消，值不更新。

你通过 UpdateAsync() 传递的回调函数不具备权限来生成。它不能包含任何生成功效，例如 Library.task.wait() 。


local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("Uppercase Name:", updatedName)
end

设置对更新

使用 set 快速更新特定键。 SetAsync() 函数：

如果两个服务器尝试同时设置相同的钥匙，可能会导致数据不一致
只会计算写入限制

使用更新来处理多服务器尝试。 UpdateAsync() 函数：

读取最后更新时从服务器上读取的当前钥匙值
因为它在写之前读取
对读取和写入限制进行双重计算

读取数据

要读取数据存储入口的值，请使用 GetAsync() 使用入口的钥匙名。


local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, currentExperience = pcall(function()
	return experienceStore:GetAsync("User_1234")
end)
if success then
	print(currentExperience)
end

使用 GetAsync() 获取的值可能会因caching行为而与后端同步失败。有关更多信息，请参阅禁用 caching。

增加数据

要在数据存商店中增加整数，请使用 IncrementAsync() 使用入口的钥匙名称和一个数量来更改值。 IncrementAsync() 是一个方便函数，可以让您避免调用 UpdateAsync() 并


local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, newExperience = pcall(function()
	return experienceStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newExperience)
end

移除数据

要将一个键值删除并返回与其关联的值，请调用 RemoveAsync() 。


local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

金属

订购的数据存储不支持版本和金属，因此DataStoreKeyInfo总是是nil对于键在1> Class.OrderedDataStore|OrderedDataStore1>中。如果您需要支持版本和金属，请使用4> Class.DataStore|DataStore4>。

钥匙与两种类型的数据类型相关的数据类型：

服务定义 : 默认只读的数据，例如最新的更新时间和创建时间。每个对象都有服务定义的数据。
用户定义 : 用户标记和分类的自定义数据。定义使用 DataStoreSetOptions 对象和 SetMetadata() 函数。

要管理元数据，请扩展 SetAsync() ， UpdateAsync() ， GetAsync() ， 1> Class.GlobalDataStore:IncrementAsync()|IncrementAsync()1> 和 4>

SetAsync() 接受第三个和第四个可选参数：

Class.Player.UserId|UserIds 的桌子。这可以帮助 with 内容版权和知识产权跟踪和移除。

一个 DataStoreSetOptions 对象，在该对象中您可以使用 SetMetadata() 函数定义自定义金属数据。


local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local setOptions = Instance.new("DataStoreSetOptions")
setOptions:SetMetadata({["ExperienceElement"] = "Fire"})

local success, errorMessage = pcall(function()
    experienceStore:SetAsync("User_1234", 50, {1234}, setOptions)
end)
if not success then
    print(errorMessage)
end

GetAsync() , IncrementAsync() , 和 RemoveAsync() 在 0> Class.DataStoreKeyInfo0> 对象中返回第二个值。此第二个值包含服务定义的属性和函数以获取用户

Class.DataStoreKeyInfo:GetUserIds()|GetUserIds() 函数从 UserIds 表中获取您传递给 SetAsync() 的表。
Class.DataStoreKeyInfo:GetMetric()|GetMetric() 函数通过 SetAsync() 通过 SetMetadata() 通过 1>Class.DataStoreSetOptions:SetMetric()|SetMetric()1> 通过 4>Class.DataStoreSetOptions:SetMetric()|setMetric()4> 通过 7>Class.DataStoreSetOptions:setMetric()|setMetric()7> 通过 0>
Class.DataStoreKeyInfo.Version|Version 属性获取钥键的版本。
Class.DataStoreKeyInfo.CreatedTime|CreatedTime 属性获取钥匙创建时间，按时间格式表示自从世纪开始的千秒。
Class.DataStoreKeyInfo.UpdatedTime|UpdatedTime 属性获取最后一次钥匙更新时的时间，以时间为每秒计数，从时间到时代。


local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, currentExperience, keyInfo = pcall(function()
    return experienceStore:GetAsync("User_1234")
end)
if success then
    print(currentExperience)
    print(keyInfo.Version)
    print(keyInfo.CreatedTime)
    print(keyInfo.UpdatedTime)
    print(keyInfo:GetUserIds())
    print(keyInfo:GetMetadata())
end

Class.GlobalDataStore:UpdateAsync()|UpdateAsync() 的回调函数在 DataStoreKeyInfo 对象中增加一个额外参数，描述当前关键状态。它返回修改的值，与 UserIds 关键的关键。它还返回键的元数据。


local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName, keyInfo)
    local nameUpper = string.upper(currentName)
    local userIDs = keyInfo:GetUserIds()
    local metadata = keyInfo:GetMetadata()
    return nameUpper, userIDs, metadata
end

local success, updatedName, keyInfo = pcall(function()
    return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
    print(updatedName)
    print(keyInfo.Version)
    print(keyInfo.CreatedTime)
    print(keyInfo.UpdatedTime)
    print(keyInfo:GetUserIds())
    print(keyInfo:GetMetadata())
end

当调用 SetAsync() 、 IncrementAsync() 和 UpdateAsync() 时，您必须总是更新元数据定义，即使当前值无变更。如果您不这样做，您会失去当前值。

对于定义元数据时，请参阅元数据限制。

订购的数据存储

默认情况下，数据存储不会排序其内容。如果您需要获得数据以特定排序方式，例如在持久排行榜统计中，请使用 GetOrderedDataStore() 而不是 GetDataStore()。


local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

订购数据存储支持与默认数据存储相同的基本功能，包括 GetSortedAsync() 独特功能。这会根据特定排序顺序、页面大小和最低/最大值来恢复多个排序键。

下面的例子将角色数据分为三个入口，每个入口由下降顺序，然后循环通过页面和输出每个角色的名称和年龄。


local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- 订购数据存商店
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- 按照从下到上的顺序排列数据
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- 获取当前页 (首页)
		local entries = pages:GetCurrentPage()
		-- 遍历页面上的所有键值对
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- 检查上一页是否已到达
		if pages.IsFinished then
			break
		else
			print("------------")
			-- 前进到下一页
			pages:AdvanceToNextPageAsync()
		end
	end
end

使用 GetOrderedDataStore() 使用 AdvanceToNextPageAsync() 限制请求的上限是与您设置的订购数据存商店的最大页面大小相同。 Class.Pages:AdvanceToNextPageAsync()|AdvanceToNextPageAsync