Peta hash penyimpanan memori | Dokumentasi

Peta hash, mirip dengan peta terurut, memungkinkan Anda menyimpan data dalam memori sebagai pasangan kunci-nilai. Berbeda dengan peta terurut, mereka tidak mempertahankan jaminan urutan. Struktur data ini berguna untuk kasus yang memerlukan caching data sederhana dan akses cepat, seperti inventaris bersama, rumah lelang fisik, dan banyak lagi. Peta hash secara otomatis menangani pemartisian data Anda dan sangat berguna jika Anda memiliki lebih dari 1.000 kunci. Untuk ruang kunci yang lebih kecil, kami merekomendasikan peta terurut.

Batasan

Peta hash memiliki batas ukuran kunci 128 karakter dan batas ukuran nilai 32 KB.

Selain itu, peta hash menggunakan batasan permintaan API dan kuota memori yang sama seperti struktur data penyimpanan memori lainnya.

Mendapatkan peta hash

Untuk mendapatkan peta hash, panggil MemoryStoreService:GetHashMap() dengan nama untuk peta hash. Nama ini bersifat global dalam permainan, sehingga Anda dapat mengakses peta hash yang sama di skrip mana pun menggunakan nama ini.

Mendapatkan Peta Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Setelah Anda mendapatkan peta hash, panggil salah satu fungsi berikut untuk membaca atau menulis data di dalamnya:

Fungsi	Tindakan
MemoryStoreHashMap:SetAsync()	Tambahkan kunci baru atau timpa nilai jika kunci sudah ada.
MemoryStoreHashMap:GetAsync()	Baca kunci tertentu.
MemoryStoreHashMap:ListItemsAsync()	Daftar item dalam peta hash.
MemoryStoreHashMap:UpdateAsync()	Perbarui nilai kunci setelah mengambilnya dari peta hash.
MemoryStoreHashMap:RemoveAsync()	Hapus kunci dari peta hash.

Untuk dokumentasi mendalam tentang masing-masing fungsi, lihat MemoryStoreHashMap.

Semua fungsi yang mengakses struktur data dalam penyimpanan memori adalah panggilan jaringan asinkron yang mungkin kadang-kadang gagal. Anda harus membungkus panggilan ini dalam pcall() untuk menangkap dan menangani kesalahan, seperti yang ditunjukkan dalam contoh kode.

Tambahkan atau timpa data

Untuk menambahkan kunci baru atau menimpa nilai kunci dalam peta hash, panggil MemoryStoreHashMap:SetAsync() dengan nama kunci, nilainya, dan waktu kedaluwarsa dalam detik. Memori secara otomatis membersihkan setelah kunci kedaluwarsa. Waktu kedaluwarsa maksimum adalah 3.888.000 detik (45 hari).

Di bawah Peraturan Perlindungan Data Umum Uni Eropa (GDPR), jika penyimpanan memori Anda memiliki data pengguna yang tunduk pada hak untuk dilupakan Anda harus menghapus data tersebut dalam waktu 30 hari, bahkan jika Anda menetapkan waktu kedaluwarsa kunci penyimpanan memori Anda hingga 45 hari.

Menambahkan Data ke Peta Hash
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("Penyetelan berhasil.")
end

Dapatkan data

Anda dapat mengambil nilai yang terkait dengan kunci tertentu atau mendapatkan beberapa pasangan kunci-nilai dalam peta hash.

Dapatkan data dengan satu kunci

Untuk mendapatkan nilai yang terkait dengan satu kunci dari peta hash, panggil MemoryStoreHashMap:GetAsync() dengan nama kunci.

Mendapatkan Kunci Tertentu dari Peta Hash
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("Penyetelan berhasil.")
end

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

Dapatkan data dengan beberapa pasangan kunci-nilai

Untuk mendapatkan semua pasangan kunci-nilai dari peta hash sebagai satu operasi, panggil MemoryStoreHashMap:ListItemsAsync() dengan ukuran halaman yang diinginkan. Fungsi ini mencantumkan semua kunci yang ada dengan cara yang dipaginasikan. Misalnya, contoh kode berikut mengambil hingga 32 item dari peta hash.

Mendaftar item dalam Peta Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Dapatkan daftar item, 32 item sekaligus
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Dapatkan halaman saat ini
		local entries = pages:GetCurrentPage()
		-- Iterasi melalui semua pasangan kunci-nilai di halaman
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Periksa apakah halaman terakhir telah dicapai
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Maju ke halaman berikutnya
			pages:AdvanceToNextPageAsync()
		end
	end
end

Perbarui data

Untuk mengambil nilai kunci dari peta hash dan memperbaruinya, panggil MemoryStoreHashMap:UpdateAsync() dengan nama kunci, fungsi callback untuk memperbarui kunci, dan waktu kedaluwarsa dalam detik.

Untuk sebagian besar permainan, beberapa server dapat memperbarui kunci yang sama secara bersamaan dan mengubah nilai. Karena UpdateAsync() selalu memodifikasi nilai terbaru sebelum memperbarui, Anda harus menggunakannya untuk membaca nilai terbaru sebagai input untuk fungsi callback Anda.

Misalnya, contoh kode berikut memperbarui jumlah sumber daya dari sebuah sumber daya di inventaris bersama. UpdateAsync() memastikan bahwa semua kontribusi pemain akan masuk ke inventaris bersama ini, bahkan jika kontribusi ini dilakukan secara bersamaan. Dalam fungsi ini, juga ditegakkan jumlah maksimum sumber daya sebanyak 500.

Memperbarui Jumlah Sumber Daya untuk Sumber Daya dalam Inventaris Bersama
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

			-- pastikan kita tidak melebihi jumlah sumber daya maksimum
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

Latensi untuk UpdateAsync() mirip dengan GetAsync() dan SetAsync() kecuali ada kontensi.

Ketika kontensi terjadi, sistem secara otomatis mencoba ulang operasi sampai salah satu dari tiga hal ini terjadi: operasi berhasil, fungsi callback mengembalikan nil, atau jumlah maksimum percobaan dicapai. Jika sistem mencapai jumlah maksimum percobaan, ia mengembalikan konflik.

Hapus data

Anda dapat menggunakan MemoryStoreHashMap:RemoveAsync() untuk menghapus satu kunci dari peta hash dan menghapus semua data dalam peta hash penyimpanan memori.

Hapus kunci

Untuk menghapus kunci dari peta hash, panggil MemoryStoreHashMap:RemoveAsync() dengan nama kunci.

Menghapus Kunci dari Peta Hash
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("Penyetelan berhasil.")
end

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

Hapus semua data

Untuk menghapus semua data dalam peta hash, daftar semua item Anda dengan MemoryStoreHashMap:ListItemsAsync(), lalu hapus mereka dengan MemoryStoreHashMap:RemoveAsync().

Hapus semua data dalam Peta Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Dapatkan daftar item, 32 item sekaligus
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Dapatkan halaman saat ini
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Iterasi melalui semua pasangan kunci-nilai di halaman
		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
		-- Periksa apakah halaman terakhir telah dicapai
		if pages.IsFinished then
			print("Selesai menghapus semua data.")
			break
		else
			print("----------")
			-- Maju ke halaman berikutnya
			pages:AdvanceToNextPageAsync()
		end
	end
end