Mapa haszowy magazynu pamięci | Dokumentacja

Mapy haszowe, podobnie jak mapy posortowane, pozwalają na przechowywanie danych w pamięci w postaci par klucz-wartość. W przeciwieństwie do map posortowanych, nie utrzymują one żadnych gwarancji porządku. Ta struktura danych jest przydatna w przypadkach wymagających prostej pamięci podręcznej danych i szybkiego dostępu, takich jak wspólne inwentarze, fizyczne domy aukcyjne i inne. Mapy haszowe automatycznie zajmują się partycjonowaniem Twoich danych i są bardzo przydatne, jeśli masz więcej niż 1000 kluczy. Dla mniejszych przestrzeni kluczowych, zalecamy mapy posortowane.

Limity

Mapy haszowe mają limit rozmiaru klucza wynoszący 128 znaków i limit rozmiaru wartości wynoszący 32 KB.

W przeciwnym razie mapy haszowe korzystają z tych samych limitów żądania API i kwoty pamięci co inne struktury danych w magazynach pamięci.

Uzyskiwanie mapy haszowej

Aby uzyskać mapę haszową, wywołaj MemoryStoreService:GetHashMap() z nazwą dla mapy haszowej. Nazwa ta jest globalna w obrębie gry, więc możesz uzyskać dostęp do tej samej mapy haszowej w dowolnym skrypcie, używając tej nazwy.

Uzyskiwanie mapy haszowej
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Po uzyskaniu mapy haszowej, wywołaj dowolną z następujących funkcji, aby odczytać lub zapisać dane w niej:

Funkcja	Akcja
MemoryStoreHashMap:SetAsync()	Dodaj nowy klucz lub nadpisz wartość, jeśli klucz już istnieje.
MemoryStoreHashMap:GetAsync()	Odczytaj określony klucz.
MemoryStoreHashMap:ListItemsAsync()	Wylistuj elementy w mapie haszowej.
MemoryStoreHashMap:UpdateAsync()	Zaktualizuj wartość klucza po jej odczytaniu z mapy haszowej.
MemoryStoreHashMap:RemoveAsync()	Usuń klucz z mapy haszowej.

Aby uzyskać szczegółową dokumentację dotyczącą każdej funkcji, zobacz MemoryStoreHashMap.

Wszystkie funkcje uzyskujące dostęp do struktur danych w magazynach pamięci są asynchronicznymi wywołaniami sieciowymi, które mogą czasami zawieść. Powinieneś otoczyć te wywołania funkcją pcall(), aby wychwycić i obsługiwać błędy, jak pokazano w przykładach kodu.

Dodawanie lub nadpisywanie danych

Aby dodać nowy klucz lub nadpisać wartość klucza w mapie haszowej, wywołaj MemoryStoreHashMap:SetAsync() z nazwą klucza, jego wartością i czasem wygaśnięcia w sekundach. Pamięć automatycznie się oczyszcza po wygaśnięciu klucza. Maksymalny czas wygaśnięcia wynosi 3 888 000 sekund (45 dni).

Zgodnie z ogólnym rozporządzeniem o ochronie danych osobowych UE (RODO), jeśli Twoje magazyny pamięci zawierają dane użytkowników objęte prawem do bycia zapomnianym, musisz usunąć te dane w ciągu 30 dni, nawet jeśli ustawisz czas wygaśnięcia klucza magazynu pamięci na 45 dni.

Dodawanie danych do mapy haszowej
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("Ustawienie zakończone sukcesem.")
end

Odczyt danych

Możesz uzyskać wartość powiązaną z określonym kluczem lub uzyskać wiele par klucz-wartość w mapie haszowej.

Odczyt danych z jednym kluczem

Aby uzyskać wartość powiązaną z jednym kluczem z mapy haszowej, wywołaj MemoryStoreHashMap:GetAsync() z nazwą klucza.

Uzyskiwanie określonego klucza z mapy haszowej
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("Ustawienie zakończone sukcesem.")
end

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

Odczyt danych z wieloma parami klucz-wartość

Aby uzyskać wszystkie pary klucz-wartość z mapy haszowej w jednolitym operacji, wywołaj MemoryStoreHashMap:ListItemsAsync() z pożądaną wielkością strony. Ta funkcja wyświetla wszystkie istniejące klucze w sposób stronnicowany. Na przykład, poniższy przykład kodu pobiera do 32 elementów z mapy haszowej.

Wylistowanie elementów w mapie haszowej
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Pobierz listę elementów, 32 elementy na raz
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Pobierz bieżącą stronę
		local entries = pages:GetCurrentPage()
		-- Iteruj przez wszystkie pary klucz-wartość na stronie
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Sprawdź, czy osiągnięto ostatnią stronę
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Przejdź do następnej strony
			pages:AdvanceToNextPageAsync()
		end
	end
end

Aktualizowanie danych

Aby pobrać wartość klucza z mapy haszowej i ją zaktualizować, wywołaj MemoryStoreHashMap:UpdateAsync() z nazwą klucza, funkcją zwrotną do aktualizacji klucza oraz czasem wygaśnięcia w sekundach.

W większości gier wiele serwerów może jednocześnie aktualizować ten sam klucz i zmieniać wartość. Ponieważ UpdateAsync() zawsze modyfikuje najnowszą wartość przed aktualizacją, powinieneś użyć go do odczytywania najnowszej wartości jako wejścia dla funkcji zwrotnej.

Na przykład, poniższy przykład kodu aktualizuje liczbę zasobów w zasobie w wspólnym inwentarzu. UpdateAsync() zapewnia, że wszelkie wkłady graczy zostaną uwzględnione w tym wspólnym inwentarzu, nawet jeśli te wkłady są dokonywane jednocześnie. W tej funkcji narzuca się również maksymalną liczbę zasobów wynoszącą 500.

Aktualizowanie liczby zasobów dla zasobu w wspólnym inwentarzu
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

			-- upewnij się, że nie przekraczamy maksymalnej liczby zasobów
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

Opóźnienie dla UpdateAsync() jest podobne do GetAsync() oraz SetAsync() chyba, że wystąpi kontestacja.

Gdy występuje kontestacja, system automatycznie ponawia operację, aż jedno z trzech zdarzeń będzie miało miejsce: operacja zakończy się sukcesem, funkcja zwrotna zwróci nil, lub osiągnięto maksymalną liczbę prób. Jeśli system osiągnie maksymalną liczbę prób, zwraca konflikt.

Usuwanie danych

Możesz użyć MemoryStoreHashMap:RemoveAsync() zarówno do usunięcia jednego klucza z mapy haszowej, jak i do usunięcia wszystkich danych z mapy haszowej magazynu pamięci.

Usunięcie klucza

Aby usunąć klucz z mapy haszowej, wywołaj MemoryStoreHashMap:RemoveAsync() z nazwą klucza.

Usunięcie klucza z mapy haszowej
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("Ustawienie zakończone sukcesem.")
end

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

Usunięcie wszystkich danych

Aby usunąć wszystkie dane w mapie haszowej, wylistuj wszystkie swoje elementy za pomocą MemoryStoreHashMap:ListItemsAsync(), a następnie usuń je za pomocą MemoryStoreHashMap:RemoveAsync().

Usunięcie wszystkich danych w mapie haszowej
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Pobierz listę elementów, 32 elementy na raz
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Pobierz bieżącą stronę
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Iteruj przez wszystkie pary klucz-wartość na stronie
		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
		-- Sprawdź, czy osiągnięto ostatnią stronę
		if pages.IsFinished then
			print("Zakończono usuwanie wszystkich danych.")
			break
		else
			print("----------")
			-- Przejdź do następnej strony
			pages:AdvanceToNextPageAsync()
		end
	end
end