ハッシュマップは、ソートされたマップと同様に、メモリ内データをキーとバリューのペアとして保存することができます。ソートされたマップとは異なり、順序の保証は行われません。このデータ構造は、共有インベントリや物理オークションハウスなど、シンプルなデータキャッシングや迅速なアクセスが必要なケースに便利です。ハッシュマップは自動的にデータのパーティション分割を処理し、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を参照してください。
データを追加または上書きする
新しいキーを追加するか、ハッシュマップ内の既存のキーの値を上書きするには、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
データを取得する
特定のキーに関連付けられた値を取得するか、ハッシュマップ内の複数のキーとバリューのペアを取得できます。
一つのキーでデータを取得する
ハッシュマップから特定のキーに関連付けられた値を取得するには、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
複数のキーとバリューのペアでデータを取得する
ハッシュマップから全てのキーとバリューのペアを単一の操作で取得するには、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()を使用して、ハッシュマップから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