Mapa de hash de la tienda de recuerdos

Los mapas hash , similares a los mapas ordenados, te permiten almacenar datos en el almacenamiento como pares de valores clave. A diferencia de los mapas ordenados, no mantienen garantías de ordenación. Esta estructura de datos es útil para casos que requieren un almacenamiento en caché de datos simple y un acceso rápido, como inventarios compartidos, casas de subastas físicas y más. Los mapas hash manejan automáticamente la partición de tus datos y son muy útiles si tienes más de 1,000 teclas. Para espacios de teclas más pequeños, recomendamos mapas ordenados.

Límites

Los mapas hash tienen un límite de tamaño de clave de 128 caracteres y un límite de tamaño de valor de 32 KB.

De lo contrario, los mapas hash usan los mismos límites de solicitud de API y límites de cuota de almacenamiento que las otras estructuras de datos de almacenamiento de almacenamiento.

Obteniendo un mapa hash

Para obtener un mapa de hash, llama MemoryStoreService:GetHashMap() con un nombre para el mapa de hash. El nombre es global dentro de la experiencia, por lo que puede acceder al mismo mapa de hash en cualquier script usando este nombre.

Obteniendo un mapa hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Después de obtener un mapa hash, llame a cualquiera de las siguientes funciones para leer o escribir datos en él:

Añadir o sobrescribir datos

Para agregar una nueva clave o sobrescribir el valor de una clave en el mapa de hash, llame a MemoryStoreHashMap:SetAsync() con el nombre de la clave **** , su valor **** y un tiempo de expiración de **** en segundos. El almacenamiento se limpia automáticamente una vez que la clave expira. El tiempo máximo de expiración es de 3,888,000 segundos (45 días).

Añadiendo datos a un mapa 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("Set succeeded.")
end

Obteniendo datos

Puede obtener un valor asociado con una clave específica o obtener múltiples pares de valores de clave en el mapa de hash.

Obteniendo datos con una llave

Para obtener un valor asociado con una clave del mapa de hash, llame a MemoryStoreHashMap:GetAsync() con el nombre de la clave **** .

Obteniendo una llave particular de un mapa de 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("Set succeeded.")
end

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

Obteniendo datos con múltiples pares de teclas y valores

Para obtener todos los pares de claves y valores del mapa de hash como una sola operación, llame a MemoryStoreHashMap:ListItemsAsync() con el tamaño de página deseado. Esta función enumera todas las claves existentes de manera paginada. Por ejemplo, la siguiente muestra de código recupera hasta 32 elementos del mapa de hash.

Listando artículos en un mapa hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtener lista de elementos, 32 elementos a la vez
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtener la página actual
		local entries = pages:GetCurrentPage()
		-- Iterar a través de todos los pares de valores de clave en la página
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Compruebe si se ha alcanzado la última página
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avanzar a la siguiente página
			pages:AdvanceToNextPageAsync()
		end
	end
end

Actualizando Datos

Para recuperar el valor de una clave de un mapa de hash y actualizarlo, llame a MemoryStoreHashMap:UpdateAsync() con el nombre de la clave **** , una función de devolución de llamada **** para actualizar la clave y un tiempo de expiración **** en segundos.

Para la mayoría de las experiencias, varios servidores pueden actualizar la misma clave simultáneamente y cambiar el valor. Dado que UpdateAsync() siempre modifica el último valor antes de actualizar, debe usarlo para leer el último valor como entrada para su función de devolución de llamada.

Por ejemplo, la siguiente muestra de código actualiza el número de recursos de un recurso en un inventario compartido. UpdateAsync() garantiza que todas las contribuciones de los jugadores lleguen a este inventario compartido, incluso si estas contribuciones se hacen simultáneamente. En esta función, también hace cumplir un número máximo de recursos de 500.

Actualización del recuento de recursos de un recurso en un inventario compartido
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

			-- nos aseguramos de no exceder la cantidad máxima de recursos
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

La latencia de UpdateAsync() es similar a GetAsync() y SetAsync() a menos que haya controversia.

Cuando se produce una contienda, el sistema intenta automáticamente la operación hasta que ocurra uno de estos tres: la operación tiene éxito, la función de devolución de llamada devuelve nulo o se alcanza el número máximo de intentos. Si el sistema alcanza el número máximo de intentos, devuelve un conflicto.

Eliminando datos

Puede usar MemoryStoreHashMap:RemoveAsync() para eliminar una clave del mapa de hash y eliminar todos los datos en un mapa de hash de almacenamiento.

Eliminando una llave

Para eliminar una llave del mapa de hash, llama a MemoryStoreHashMap:RemoveAsync() con un nombre de llave **** .

Quitar una llave de un mapa 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("Set succeeded.")
end

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

Eliminando todos los datos

Para eliminar todos los datos de un mapa hash, enumera todos tus elementos con MemoryStoreHashMap:ListItemsAsync(), luego elimínalos con MemoryStoreHashMap:RemoveAsync().

Borrar todos los datos en un mapa hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtener lista de elementos, 32 elementos a la vez
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtener la página actual
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Iterar a través de todos los pares de valores de clave en la página
		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
		-- Compruebe si se ha alcanzado la última página
		if pages.IsFinished then
			print("Finished deleting all data.")
			break
		else
			print("----------")
			-- Avanzar a la siguiente página
			pages:AdvanceToNextPageAsync()
		end
	end
end