Magasins de données

Le DataStoreService vous permet de stocker des données qui doivent persister entre les sessions, comme les objets dans l'inventaire d'un joueur ou les points de compétence. Les magasins de données sont cohérents par jeu, donc n'importe quel endroit dans un jeu peut accéder et modifier les mêmes données, y compris les endroits sur différents serveurs.

Si vous souhaitez ajouter un contrôle d'autorisation granulaire à vos magasins de données et y accéder en dehors de Studio ou des serveurs Roblox, vous pouvez utiliser les API Open Cloud pour les magasins de données.

Pour visualiser et surveiller tous les magasins de données dans un jeu via le Creator Hub, utilisez le Gestionnaire de magasins de données.

Pour des données temporaires que vous devez mettre à jour ou accéder fréquemment, utilisez les magasins en mémoire.

Activer l'accès Studio

Par défaut, les jeux testés dans Studio ne peuvent pas accéder aux magasins de données, vous devez donc d'abord les activer. Accéder aux magasins de données dans Studio peut être dangereux pour les jeux en direct car Studio accède aux mêmes magasins de données que l'application cliente. Pour éviter d'écraser les données de production, ne pas activer ce paramètre pour les jeux en direct. Au lieu de cela, activez-le pour une version de test séparée du jeu.

Pour activer l'accès Studio dans un jeu publié :

1. Ouvrez la fenêtre Fichier ⟩ Paramètres de l'expérience de Studio.
2. Allez à Sécurité.
3. Activez le bascule Activer l'accès Studio aux services API.
4. Cliquez sur Enregistrer.

Accéder aux magasins de données

Pour accéder à un magasin de données à l'intérieur d'un jeu :

1. Ajoutez DataStoreService à un Script côté serveur.
2. Utilisez la fonction GetDataStore() et spécifiez le nom du magasin de données que vous souhaitez utiliser. Si le magasin de données n'existe pas, Studio en crée un lorsque vous enregistrez vos données de jeu pour la première fois.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Créer des données

Un magasin de données est essentiellement un dictionnaire, similaire à une table Luau. Une clé unique indexe chaque valeur dans le magasin de données, comme l'Player.UserId unique d'un utilisateur ou une chaîne nommée pour une promotion de jeu.

Pour créer une nouvelle entrée, appelez SetAsync() avec le nom de la clé et une valeur.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, errorMessage = pcall(function()
	gameStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

Mettre à jour des données

Pour modifier une valeur stockée dans un magasin de données, appelez UpdateAsync() avec le nom de la clé de l'entrée et une fonction de rappel qui définit comment vous souhaitez mettre à jour l'entrée. Ce rappel prend la valeur actuelle et renvoie une nouvelle valeur basée sur la logique que vous définissez. Si le rappel renvoie nil, l'opération d'écriture est annulée et la valeur n'est pas mise à jour.

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("Nom en majuscules :", updatedName)
end

Définir vs mettre à jour

Utilisez set pour mettre à jour rapidement une clé spécifique. La fonction SetAsync() :

• Peut causer une incohérence des données si deux serveurs essaient de définir la même clé en même temps
• Ne compte que contre la limite d'écriture

Utilisez update pour gérer les tentatives multi-serveurs. La fonction UpdateAsync() :

• Lit la valeur actuelle de la clé à partir du serveur qui l'a mise à jour en dernier avant d'apporter des modifications
• Est plus lente car elle lit avant d'écrire
• Compte contre les limites de lecture et d'écriture

Lire des données

Pour lire la valeur d'une entrée de magasin de données, appelez GetAsync() avec le nom de la clé de l'entrée.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, currentGame = pcall(function()
	return gameStore:GetAsync("User_1234")
end)
if success then
	print(currentGame)
end

Incrémenter des données

Pour incrémenter un entier dans un magasin de données, appelez IncrementAsync() avec le nom de la clé de l'entrée et un nombre pour combien changer la valeur. IncrementAsync() est une fonction de commodité qui vous permet d'éviter d'appeler UpdateAsync() et d'incrémenter manuellement l'entier.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, newGame = pcall(function()
	return gameStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newGame)
end

Supprimer des données

Pour supprimer une entrée et renvoyer la valeur associée à la clé, appelez RemoveAsync().

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

Métadonnées

Il existe deux types de métadonnées associées aux clés :

• Défini par le service : Métadonnées par défaut en lecture seule, comme le temps de mise à jour le plus récent et le temps de création. Chaque objet a des métadonnées définies par le service.
• Défini par l'utilisateur : Métadonnées personnalisées pour le marquage et la catégorisation. Définies à l'aide de l'objet DataStoreSetOptions et de la fonction SetMetadata().

Pour gérer les métadonnées, étendez les fonctions SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync(), et RemoveAsync().

• SetAsync() accepte les troisième et quatrième arguments optionnels :

  • Une table de UserIds. Cela peut aider au suivi et à la suppression des droits d'auteur et de la propriété intellectuelle du contenu.

  • Un objet DataStoreSetOptions, où vous pouvez définir des métadonnées personnalisées à l'aide de la fonction SetMetadata().

    local DataStoreService = game:GetService("DataStoreService")
    
    local gameStore = DataStoreService:GetDataStore("PlayerGame")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["GameElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        gameStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync(), IncrementAsync(), et RemoveAsync() renvoient une deuxième valeur dans l'objet DataStoreKeyInfo. Cette deuxième valeur contient à la fois des propriétés définies par le service et des fonctions pour récupérer des métadonnées définies par l'utilisateur.

  • La fonction GetUserIds() récupère la table de UserIds que vous avez passée à SetAsync().
  • La fonction GetMetadata() récupère les métadonnées définies par l'utilisateur que vous avez passées à SetAsync() via SetMetadata().
  • La propriété Version récupère la version de la clé.
  • La propriété CreatedTime récupère le temps de création de la clé, formaté comme le nombre de millisecondes depuis l'époque.
  • La propriété UpdatedTime récupère la dernière fois que la clé a été mise à jour, formatée comme le nombre de millisecondes depuis l'époque.

  local DataStoreService = game:GetService("DataStoreService")
  
  local gameStore = DataStoreService:GetDataStore("PlayerGame")
  
  local success, currentGame, keyInfo = pcall(function()
      return gameStore:GetAsync("User_1234")
  end)
  if success then
      print(currentGame)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

• La fonction de rappel de UpdateAsync() prend un paramètre supplémentaire dans l'objet DataStoreKeyInfo qui décrit l'état actuel de la clé. Elle renvoie la valeur modifiée, les clés associées à UserIds, et les métadonnées de la clé.

  local DataStoreService = game:GetService("DataStoreService")
  
  local nicknameStore = DataStoreService:GetDataStore("Nicknames")
  
  local function makeNameUpper(currentName, keyInfo)
      local nameUpper = string.upper(currentName)
      local userIDs = keyInfo:GetUserIds()
      local metadata = keyInfo:GetMetadata()
      return nameUpper, userIDs, metadata
  end
  
  local success, updatedName, keyInfo = pcall(function()
      return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
  end)
  if success then
      print(updatedName)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

Pour les limites lors de la définition des métadonnées, voir les limites de métadonnées.

Magasins de données ordonnés

Par défaut, les magasins de données ne trient pas leur contenu. Si vous devez obtenir des données de manière ordonnée, comme dans les statistiques de classement persistantes, appelez GetOrderedDataStore() au lieu de GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Les magasins de données ordonnés prennent en charge les mêmes fonctions de base que les magasins de données par défaut, plus la fonction unique GetSortedAsync(). Cela récupère plusieurs clés triées en fonction d'un ordre de tri spécifique, de la taille de la page et des valeurs minimales/maximales.

L'exemple suivant trie les données des personnages en pages de trois entrées, chacune dans un ordre décroissant, puis boucle à travers les pages et affiche le nom et l'âge de chaque personnage.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Remplit le magasin de données ordonné
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- Trie les données par ordre décroissant en pages de trois entrées chacune
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Obtient la page actuelle (première)
		local entries = pages:GetCurrentPage()
		-- Itère à travers toutes les paires clé-valeur sur la page
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Vérifie si la dernière page a été atteinte
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avance à la page suivante
			pages:AdvanceToNextPageAsync()
		end
	end
end

Lire plusieurs entrées

Pour lire plusieurs entrées de magasin de données ordonné en une seule demande, appelez BatchGetAsync() avec un tableau de clés. C'est le pendant par lot de la lecture des entrées une par une avec GetAsync().

BatchGetAsync() renvoie un dictionnaire qui associe chaque clé demandée à une table avec un champ value. Les clés qui n'existent pas sont omises du dictionnaire, donc confirmez qu'une clé est présente avant de lire sa valeur.

Chaque clé que vous demandez compte comme une demande de lecture, donc un seul appel pour N clés compte comme N demandes contre la limite de lecture du magasin de données ordonné.

L'exemple suivant lit trois scores de joueurs en une seule demande, puis boucle à travers les clés et affiche chaque score qui existe.

local DataStoreService = game:GetService("DataStoreService")

local playerScores = DataStoreService:GetOrderedDataStore("PlayerScores")
local keys = {"Player_123", "Player_456", "Player_789"}

local success, results = pcall(function()
	return playerScores:BatchGetAsync(keys)
end)
if success then
	for _, key in keys do
		local entry = results[key]
		if entry then
			print(key .. " : " .. tostring(entry.value))
		else
			print(key .. " n'a pas d'entrée sauvegardée")
		end
	end
end