記憶體儲存哈希地圖

哈希地圖 ，與排序地圖相似，讓您儲存在內存中的鑰匙值對。與排序的地圖不同，它們沒有排序保證。此數據結構對於需要簡單的數據緩存和快速存使用權 通行權 存取的情況，例如共享庫存、物理拍賣屋和更多，具有用處。哈希地圖會自動處理分割您的資料，如果您有超過 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