メモリストアハッシュマップ | 文書 - Roblox クリエーターハブ

ハッシュマップは、ソートされたマップに似ていて、メモリ内データをキーと値のペアとして保存することができます。ソートされたマップとは異なり、ハッシュマップは順序の保証を維持しません。このデータ構造は、共有インベントリ、物理オークションハウスなどの単純なデータキャッシングや迅速なアクセスを必要とするケースに役立ちます。ハッシュマップは自動的にデータのパーティショニングを処理し、1,000を超えるキーがある場合に非常に便利です。キー空間が小さい場合は、ソートされたマップを推奨します。

制限

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

それ以外に、ハッシュマップは他のメモリストアデータ構造と同じAPIリクエストおよびメモリクォータの制限を使用します。

ハッシュマップを取得する

ハッシュマップを取得するには、MemoryStoreService:GetHashMap()を呼び出し、ハッシュマップの名前を指定します。この名前はゲーム内でグローバルであるため、この名前を使用して任意のスクリプトから同じハッシュマップにアクセスできます。

ハッシュマップを取得する

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

ハッシュマップを取得した後、以下の関数のいずれかを呼び出してデータを読み書きできます：

関数	アクション
MemoryStoreHashMap:SetAsync()	追加新しいキーを追加するか、キーが既に存在する場合は値を上書きします。
MemoryStoreHashMap:GetAsync()	読み取る特定のキー。
MemoryStoreHashMap:ListItemsAsync()	リストハッシュマップ内のアイテム。
MemoryStoreHashMap:UpdateAsync()	更新ハッシュマップから取得した後にキーの値を更新します。
MemoryStoreHashMap:RemoveAsync()	削除ハッシュマップからキーを削除します。

各関数に関する詳細なドキュメントについては、MemoryStoreHashMapを参照してください。

メモリストア内のデータ構造にアクセスするすべての関数は、非同期のネットワーク呼び出しであり、稀に失敗することがあります。これらの呼び出しをpcall()でラップしてエラーをキャッチおよび処理することをお勧めします。コードサンプルに示されているように。

データを追加または上書きする

ハッシュマップに新しいキーを追加するか、キーの値を上書きするには、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("セットに成功しました。")
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("セットに成功しました。")
end

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

複数のキーと値のペアでデータを取得する

ハッシュマップからすべてのキーと値のペアを1回の操作で取得するには、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()を呼び出し、キーの名前、キーを更新するためのコールバック関数、および有効期限（秒単位）を指定します。

ほとんどのゲームでは、複数のサーバーが同じキーを同時に更新し、値を変更することができます。MemoryStoreHashMap:UpdateAsync()は常に更新する前に最新の値を修正するため、コールバック関数の入力として最新の値を読むのに使用すべきです。

たとえば、次のコードサンプルは、共有インベントリ内のリソースのカウントを更新します。MemoryStoreHashMap: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

MemoryStoreHashMap:UpdateAsync()の待機時間は、MemoryStoreHashMap:GetAsync()およびMemoryStoreHashMap:SetAsync()と類似ですが、競合が発生した場合は異なります。

競合が発生すると、システムは処理を自動的に再試行します。以下のいずれかの状況になるまで再試行します：処理が成功した、コールバック関数がnilを返した、または最大再試行回数に達した。システムが最大再試行回数に達した場合、競合を返します。

データを削除する

MemoryStoreHashMap:RemoveAsync()を使用することで、ハッシュマップから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("セットに成功しました。")
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("すべてのデータの削除が完了しました。")
			break
		else
			print("----------")
			-- 次のページに進む
			pages:AdvanceToNextPageAsync()
		end
	end
end