Carte de hachage du magasin de mémoire | Documentation

Les cartes de hachage, semblables aux cartes triées, vous permettent de stocker des données en mémoire sous forme de paires clé-valeur. Contrairement aux cartes triées, elles ne maintiennent aucune garantie d'ordre. Cette structure de données est utile pour les cas nécessitant une mise en cache de données simple et un accès rapide, comme les inventaires partagés, les maisons de vente aux enchères physiques, et plus encore. Les cartes de hachage gèrent automatiquement le partitionnement de vos données et sont très utiles si vous avez plus de 1 000 clés. Pour des espaces de clés plus petits, nous recommandons les cartes triées.

Limites

Les cartes de hachage ont une limite de taille de clé de 128 caractères et une limite de taille de valeur de 32 Ko.

Sinon, les cartes de hachage utilisent les mêmes limites de demande d'API et de quota de mémoire que les autres structures de données du magasin de mémoire.

Obtenir une carte de hachage

Pour obtenir une carte de hachage, appelez MemoryStoreService:GetHashMap() avec un nom pour la carte de hachage. Le nom est global au sein du jeu, vous pouvez ainsi accéder à la même carte de hachage sur n'importe quel script en utilisant ce nom.

Obtenir une carte de hachage
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Après avoir obtenu une carte de hachage, appelez l'une des fonctions suivantes pour lire ou écrire des données :

Fonction	Action
MemoryStoreHashMap:SetAsync()	Ajouter une nouvelle clé ou remplacer la valeur si la clé existe déjà.
MemoryStoreHashMap:GetAsync()	Lire une clé particulière.
MemoryStoreHashMap:ListItemsAsync()	Lister les éléments d'une carte de hachage.
MemoryStoreHashMap:UpdateAsync()	Mettre à jour la valeur d'une clé après l'avoir récupérée d'une carte de hachage.
MemoryStoreHashMap:RemoveAsync()	Supprimer une clé de la carte de hachage.

Pour une documentation détaillée sur chaque fonction, voir MemoryStoreHashMap.

Toutes les fonctions accédant aux structures de données dans les magasins de mémoire sont des appels réseau asynchrones qui peuvent parfois échouer. Vous devez envelopper ces appels dans pcall() pour capturer et gérer les erreurs, comme montré dans les exemples de code.

Ajouter ou remplacer des données

Pour ajouter une nouvelle clé ou remplacer la valeur d'une clé dans la carte de hachage, appelez MemoryStoreHashMap:SetAsync() avec le nom de la clé, sa valeur, et un temps d'expiration en secondes. La mémoire nettoie automatiquement les données une fois la clé expirée. Le temps d'expiration maximum est de 3 888 000 secondes (45 jours).

Selon le Règlement Général sur la Protection des Données (RGPD) de l'UE, si vos magasins de mémoire contiennent des données utilisateur soumises au droit à l'oubli, vous devez supprimer les données dans un délai de 30 jours, même si vous définissez l'expiration de la clé de votre magasin de mémoire jusqu'à 45 jours.

Ajouter des données à une carte de hachage
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("L'ajout a réussi.")
end

Obtenir des données

Vous pouvez soit obtenir une valeur associée à une clé spécifique, soit obtenir plusieurs paires clé-valeur dans la carte de hachage.

Obtenir des données avec une clé

Pour obtenir une valeur associée à une seule clé de la carte de hachage, appelez MemoryStoreHashMap:GetAsync() avec le nom de la clé.

Obtenir une clé particulière d'une carte de hachage
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("L'ajout a réussi.")
end

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

Obtenir des données avec plusieurs paires clé-valeur

Pour obtenir toutes les paires clé-valeur de la carte de hachage en une seule opération, appelez MemoryStoreHashMap:ListItemsAsync() avec la taille de page souhaitée. Cette fonction liste toutes les clés existantes de manière paginée. Par exemple, l'exemple de code suivant récupère jusqu'à 32 éléments de la carte de hachage.

Lister les éléments d'une carte de hachage
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenir la liste des éléments, 32 éléments à la fois
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtenir la page actuelle
		local entries = pages:GetCurrentPage()
		-- Itérer à travers toutes les paires clé-valeur de la page
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Vérifier si la dernière page a été atteinte
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Passer à la page suivante
			pages:AdvanceToNextPageAsync()
		end
	end
end

Mettre à jour des données

Pour récupérer la valeur d'une clé d'une carte de hachage et la mettre à jour, appelez MemoryStoreHashMap:UpdateAsync() avec le nom de la clé, une fonction de rappel pour mettre à jour la clé, et un temps d'expiration en secondes.

Pour la plupart des jeux, plusieurs serveurs peuvent mettre à jour la même clé en même temps et changer la valeur. Comme UpdateAsync() modifie toujours la dernière valeur avant de mettre à jour, vous devez l'utiliser pour lire la dernière valeur comme entrée pour votre fonction de rappel.

Par exemple, l'exemple de code suivant met à jour le nombre de ressources d'une ressource dans un inventaire partagé. UpdateAsync() s'assure que toutes les contributions des joueurs seront intégrées dans cet inventaire partagé, même si ces contributions sont faites simultanément. Dans cette fonction, il impose également un nombre maximum de ressources de 500.

Mettre à jour le nombre de ressources pour une ressource dans un inventaire partagé
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

			-- s'assurer que nous ne dépassons pas le nombre maximum de ressources
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

La latence de UpdateAsync() est similaire à celle de GetAsync() et SetAsync() à moins qu'il n'y ait une concurrence.

Lorsque la concurrence se produit, le système réessaie automatiquement l'opération jusqu'à ce que l'un de ces trois événements se produise : l'opération réussit, la fonction de rappel renvoie nil, ou le nombre maximum de réessais est atteint. Si le système atteint le nombre maximum de réessais, il renvoie un conflit.

Supprimer des données

Vous pouvez utiliser MemoryStoreHashMap:RemoveAsync() pour à la fois supprimer une clé de la carte de hachage et supprimer toutes les données dans une carte de hachage de magasin de mémoire.

Supprimer une clé

Pour supprimer une clé de la carte de hachage, appelez MemoryStoreHashMap:RemoveAsync() avec le nom de la clé.

Supprimer une clé d'une carte de hachage
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("L'ajout a réussi.")
end

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

Supprimer toutes les données

Pour supprimer toutes les données dans une carte de hachage, listez tous vos éléments avec MemoryStoreHashMap:ListItemsAsync(), puis supprimez-les avec MemoryStoreHashMap:RemoveAsync().

Supprimer toutes les données dans une carte de hachage
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenir la liste des éléments, 32 éléments à la fois
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtenir la page actuelle
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Itérer à travers toutes les paires clé-valeur de la page
		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
		-- Vérifier si la dernière page a été atteinte
		if pages.IsFinished then
			print("Suppression de toutes les données terminée.")
			break
		else
			print("----------")
			-- Avancer à la page suivante
			pages:AdvanceToNextPageAsync()
		end
	end
end