内存存储哈希地图

哈希地图 , 类似于排序地图, 让你存储在内存中的数据为键值对。与排序的地图不同，它们没有排序保证。这种数据结构对那些需要简单数据缓存和快速1) 使用权 2）通行证 3）访问权限问的情况有用，例如共享库存、物理拍卖屋和更多。哈希地图自动处理分割数据，如果您有超过 1,000 个键，非常有用。对于更小的键空间，我们推荐 排序地图。

限制

哈希地图有 128 个字符的键大小限制和 32 KB 的值大小限制。

否则，散列地图使用与其他内存存储数据结构相同的 API 请求 和 内存限额 限制。

获取哈希地图

要获取哈希地图，请调用 MemoryStoreService:GetHashMap() 并为哈希地图提供名称。名称在体验中是全球的，因此您可以使用此名称访问任何脚本的相同哈希地图。

获取哈希地图
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

在获得哈希地图后，调用以下任意函数来在其中阅读或写入数据：

有关每个函数的深度文档，请参阅 MemoryStoreHashMap。

添加或覆盖数据

要添加新的键或覆盖哈希地图中键的值，请使用 MemoryStoreHashMap:SetAsync() 键 名称 、其 值 以及在秒内的 过期时间 来调用。一旦钥匙过期，内存会自动清理。最大有效期为 3,888,000 秒（45 天）。

将数据添加到哈希地图
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

获取数据

您可以获得与特定键相关的值或在哈希地图中获得多个键值对。

使用一个键获取数据

要从哈希地图中获取与一个键相关的值，请使用 MemoryStoreHashMap:GetAsync() 键 名称 调用。

从哈希地图中获取特定键
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

local item
local getSuccess, getError = pcall(function()
	item = hashMap:GetAsync("User_1234")
end)
if getSuccess then
	print(item)
else
	warn(getError)
end

获取多个键值对的数据

要将哈希地图中的所有键值对组合为单个操作，请调用 MemoryStoreHashMap:ListItemsAsync() 并设置所需的页面尺寸。该函数列出所有现有键的分页方式。例如，以下代码示例从哈希地图中检索最多 32 个项目。

在哈希地图中列出项目
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- 获取物品列表，一次 32 个物品
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- 获取当前页
		local entries = pages:GetCurrentPage()
		-- 在页面上遍历所有键值对的所有对象
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- 检查最后一页是否已达到
		if pages.IsFinished then
			break
		else
			print("----------")
			-- 前往下一页
			pages:AdvanceToNextPageAsync()
		end
	end
end

更新数据

要从哈希地图中检索键的值并更新它，请使用 MemoryStoreHashMap:UpdateAsync() 键 名称 调用 回调函数 来更新键，并在秒内设置 过期时间 。

对于大多数体验，多个服务器可以同时更新相同的键并更改值。由于 UpdateAsync() 总是在更新前修改最新值，您应该使用它来阅读最新值作为调用函数的输入。

例如，以下代码示例更新了共享库中资源的数量。UpdateAsync() 确保所有玩家贡献都会进入这个共道具存，即使这些贡献是同时进行的。在这个函数中，它还强制执行最大资源数量为 500。

更新共享库中资源的资源数量
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("ResourceInventory")

local function contributeResources(itemResource, addedCount)
	local success, newResourceCount = pcall(function()
		return hashMap:UpdateAsync(itemResource, function(resource)
			resource = resource or {count = 0}
			resource.count = resource.count + addedCount

			-- 确保我们不超过最大资源数
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

UpdateAsync() 的延迟与 GetAsync() 和 SetAsync() 相似，除非存在竞争。

当竞争发生时，系统会自动重试操作，直到其中一个三者之一发生：操作成功，回调函数返回 nil 或最大重试次数达到。如果系统达到最大重试次数，它将返回冲突。

删除数据

您可以使用 MemoryStoreHashMap:RemoveAsync() 来从哈希地图中删除一个键和从内存存储哈希地图中删除所有数据。

删除钥键

要从哈希地图中删除钥匙，请使用键 MemoryStoreHashMap:RemoveAsync() 调用 **** 。

从哈希地图中删除一个键
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

local removeSuccess, removeError = pcall(function()
	hashMap:RemoveAsync("User_1234")
end)
if not removeSuccess then
	warn(removeError)
end

删除所有数据

要删除哈希地图中的所有数据，列出所有带有 MemoryStoreHashMap:ListItemsAsync() 的项目，然后用 MemoryStoreHashMap:RemoveAsync() 移除它们。

删除哈希地图中的所有数据
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- 获取物品列表，一次 32 个物品
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- 获取当前页
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- 在页面上遍历所有键值对的所有对象
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
			removeSuccess, removeError = pcall(function()
				hashMap:RemoveAsync(entry.key)
			end)

			if not removeSuccess then
				warn(removeError)
			end
		end
		-- 检查最后一页是否已达到
		if pages.IsFinished then
			print("Finished deleting all data.")
			break
		else
			print("----------")
			-- 前往下一页
			pages:AdvanceToNextPageAsync()
		end
	end
end