Bellek deposu hash haritası | Dokümantasyon

Hash haritaları, sıralı haritalara benzer şekilde, bellek içi verileri anahtar-değer çiftleri olarak saklamanızı sağlar. Sıralı haritalardan farklı olarak, herhangi bir sıralama garantisi sağlamazlar. Bu veri yapısı, paylaşılmış envanterler, fiziksel açık artırma evleri ve daha fazlası gibi basit veri önbellekleme ve hızlı erişim gerektiren durumlar için faydalıdır. Hash haritaları, verilerinizi otomatik olarak parçalara ayırır ve 1.000'den fazla anahtarınız varsa çok faydalıdır. Daha küçük anahtar alanları için sıralı haritaları öneriyoruz.

Sınırlar

Hash haritalarının anahtar boyutu limiti 128 karakter ve değer boyutu limiti 32 KB'dir.

Aksi belirtilmedikçe, hash haritaları diğer bellek depolama veri yapılarıyla aynı API isteği ve bellek kotası limitlerini kullanır.

Bir hash haritası al

Bir hash haritası almak için, MemoryStoreService:GetHashMap() çağrısını yaparak hash haritası için bir isim belirtin. İsim oyun içinde küreseldir, dolayısıyla bu ismi kullanarak herhangi bir betikte aynı hash haritasına erişebilirsiniz.

Hash Haritası Almak
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Bir hash haritası aldıktan sonra, içinde veri okumak veya yazmak için aşağıdaki fonksiyonlardan birini çağırabilirsiniz:

Fonksiyon	İşlem
MemoryStoreHashMap:SetAsync()	Ekle yeni bir anahtar veya anahtar zaten varsa değeri üstüne yazın.
MemoryStoreHashMap:GetAsync()	Oku belirli bir anahtarı.
MemoryStoreHashMap:ListItemsAsync()	Listele bir hash haritasındaki öğeleri.
MemoryStoreHashMap:UpdateAsync()	Güncelle bir anahtarın değerini hash haritasından aldıktan sonra.
MemoryStoreHashMap:RemoveAsync()	Kaldır hash haritasından bir anahtarı.

Her fonksiyon hakkında detaylı belgeler için MemoryStoreHashMap'ı görün.

Bellek deposundaki veri yapılarına erişen tüm fonksiyonlar, zaman zaman başarısız olabilecek asenkron ağ çağrılarıdır. Bu çağrıları pcall() içinde sarmalamalısınız, böylece hataları yakalayabilir ve işleyebilirsiniz; bunu örnek kodda gösterildiği gibi yapın.

Veri ekle veya üzerine yaz

Bir hash haritasına yeni bir anahtar eklemek veya bir anahtarın değerini üzerine yazmak için, MemoryStoreHashMap:SetAsync() çağrısını anahtar adı, değeri ve sona erme süresi ile birlikte yapın. Anahtar süresi dolduğunda bellek otomatik olarak temizlenir. Maksimum sona erme süresi 3.888.000 saniyedir (45 gün).

AB Genel Veri Koruma Yönetmeliği (GDPR) altında, eğer bellek depolarınız unutulma hakkına tabi kullanıcı verileri içeriyorsa, verilerinizi 30 gün içinde kaldırmalısınız; bu, bellek depo anahtarınızın sona erme süresini 45 güne ayarlasınız bile geçerlidir.

Hash Haritasına Veri Eklemek
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("Ayarlama başarılı.")
end

Veri al

Belirli bir anahtarla ilişkili bir değeri alabilir veya hash haritasındaki birden fazla anahtar-değer çiftini alabilirsiniz.

Bir anahtarla veri al

Hash haritasından bir anahtarla ilişkili bir değeri almak için, MemoryStoreHashMap:GetAsync() çağrısını anahtar adı ile yapın.

Hash Haritasından Belirli Bir Anahtar Almak
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("Ayarlama başarılı.")
end

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

Birden fazla anahtar-değer çifti ile veri al

Hash haritasından tüm anahtar-değer çiftlerini tek bir işlemle almak için, MemoryStoreHashMap:ListItemsAsync() çağrısını istenen sayfa boyutu ile yapın. Bu fonksiyon, tüm mevcut anahtarları pagine edilmiş bir şekilde listeler. Örneğin, aşağıdaki kod örneği, hash haritasından en fazla 32 öğeyi alır.

Hash Haritasındaki Öğeleri Listelemek
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Öğelerin listesi, her seferde 32 öğe
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Mevcut sayfayı al
		local entries = pages:GetCurrentPage()
		-- Sayfadaki tüm anahtar-değer çiftleri üzerinde döngü
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Son sayfanın ulaşılıp ulaşılmadığını kontrol et
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Bir sonraki sayfaya geç
			pages:AdvanceToNextPageAsync()
		end
	end
end

Veriyi güncelle

Bir hash haritasından bir anahtarın değerini almak ve güncellemek için, MemoryStoreHashMap:UpdateAsync() çağrısını anahtar adı, bir geri çağırma fonksiyonu ve sona erme süresi ile yapın.

Birçok oyunda, birden fazla sunucu aynı anahtarı eşzamanlı olarak güncelleyebilir ve değeri değiştirebilir. UpdateAsync() her zaman en son değeri güncellemeden önce değiştirerek okur, bu nedenle geri çağırma fonksiyonunuz için girdi olarak en son değeri okumak için bunu kullanmalısınız.

Örneğin, aşağıdaki kod örneği paylaşılmış bir envanterdeki bir kaynağın miktarını günceller. UpdateAsync() tüm oyuncu katkılarının bu paylaşılmış envantere dahil olmasını sağlarken, bu fonksiyonda aynı zamanda maksimum kaynak miktarı 500 olarak belirlenmiştir.

Paylaşılan Envanterdeki Bir Kaynağın Miktarını Güncelleme
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

			-- maksimum kaynak sayısını aşmadığımızdan emin olun
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

UpdateAsync() için gecikme, GetAsync() ve SetAsync() ile benzerdir, aksi takdirde herhangi bir çelişki yoksa.

Çelişki oluştuğunda, sistem otomatik olarak işlemi tekrar eder ve bunlardan biri gerçekleşene kadar devam eder: işlem başarılı olur, geri çağırma fonksiyonu nil döner veya maksimum tekrar sayısına ulaşılır. Eğer sistem maksimum tekrar sayısına ulaşırsa, bir çelişki döner.

Veriyi kaldır

Hash haritasından bir anahtarı kaldırmak ve bellek deposu hash haritasındaki tüm verileri silmek için MemoryStoreHashMap:RemoveAsync() kullanabilirsiniz.

Bir anahtarı kaldır

Hash haritasından bir anahtarı kaldırmak için, MemoryStoreHashMap:RemoveAsync() çağrısını içerisinde bir anahtar adı ile yapın.

Hash Haritasından Bir Anahtarı Kaldırmak
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("Ayarlama başarılı.")
end

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

Tüm verileri sil

Hash haritasındaki tüm verileri silmek için, önce MemoryStoreHashMap:ListItemsAsync() ile tüm öğelerinizi listeleyin, ardından bunları MemoryStoreHashMap:RemoveAsync() ile kaldırın.

Hash Haritasındaki Tüm Verileri Silmek
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Öğelerin listesi, her seferde 32 öğe
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Mevcut sayfayı al
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Sayfadaki tüm anahtar-değer çiftleri üzerinde döngü
		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
		-- Son sayfanın ulaşılıp ulaşılmadığını kontrol et
		if pages.IsFinished then
			print("Tüm verileri silme işlemi tamamlandı.")
			break
		else
			print("----------")
			-- Bir sonraki sayfaya geç
			pages:AdvanceToNextPageAsync()
		end
	end
end