メモリストアハッシュマップ

ハッシュマップ 、ソートされたマップに似て、メモリ内のデータをキー-バリューペアとして保存できます。ソートされたマップとは異なり、順序保証は維アクセス, 書き込み権限 (write access)しません。このデータ構造は、共有インベントリ、物理オークションハウスなど、シンプルなデータキャッシュと迅速なアクセスが必要なケースに便利です。ハッシュマップはデータの分割を自動的に処理し、1,000以上のキーを持っている場合は非常に便利です。小さいキースペースの場合、ソートされたマップ をお勧めします。

制限

ハッシュマップには、128文字のキーサイズ制限と 32KBの値サイズ制限があります。

そうでない場合、ハッシュマップは、他のメモリストデータ構造と同じ 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

データを取得する

特定のキーに関連する値を取得するか、ハッシュマップで複数のキー-値ペアを取得できます。

1つのキーでデータを取得する

ハッシュマップから 1つのキーに関連する値を取得するには、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() にキーの名前 name 、 コールバック関数 でキーを更新する、および秒単位の 有効期限時間 を呼び出します。

ほとんどのエクスペリエンスでは、複数のサーバーが同時に同じキーを更新し、値を変更できます。As 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() に似ています。

競合が発生すると、システムはこれらのうちの 1つが発生するまで、操作を自動的に再試行します：操作が成功し、コールバック関数が nil を返すか、リトライの最大数に達します。システムが最大リトライ数に達すると、コンフリクトが返されます。

データを削除

は、ハッシュマップから 1 つのキーを削除し、メモリストハッシュマップのすべてのデータを削除するときに両方使用できます。

キーを削除する

ハッシュマップからキーを削除するには、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