Stockage de données

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

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

Pour afficher et surveiller tous les magasins de données dans une expérience à travers le Hub Création, utilisez le gestionnaire des magasins de données.

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

Activer l'accès au studio

Par défaut, les expériences testées dans Studio ne peuvent pas accéder aux magasins de données, vous devez donc les activer d'abord.L'accès aux magasins de données dans Studio peut être dangereux pour les expériences 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, n'activez pas ce paramètre pour les expériences en direct.Au lieu de cela, activez-le pour une version de test séparée de l'expérience.

Pour activer l'accès au studio dans une expérience publiée :

1. Ouvrez les paramètres du jeu.
2. Accédez à Sécurité .
3. Activez l'option Activer l'accès au studio aux services API .
4. Cliquez sur Enregistrer .

Stockage des données d'accès

Pour accéder à un magasin de données dans une expérience :

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

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Créer des données

Un magasin de données est essentiellement un dictionnaire, similaire à une table Luau.Un index unique clé indexe chaque valeur dans le boutiquede données, comme une clé unique d'un utilisateur Player.UserId

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

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

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

Mettre à jour les données

Pour modifier n'importe quelle valeur stockée dans un boutiquede 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 en fonction de 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("Uppercase Name:", updatedName)
end

Définir vs mettre à mise à jour

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

• Peut provoquer 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 la mise à jour pour gérer les tentatives multisерверов. La fonction UpdateAsync():

• Lit la valeur de clé actuelle du serveur qui l'a dernièrement mise à jour avant de faire des modifications
• Est plus lent car il lit avant d'écrire
• Compte à la fois 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 clé de l'entrée.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

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

Données d'augmentation

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

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

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

Supprimer des données

Pour supprimer une entrée et retourner 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 de lecture seule par défaut, comme le temps de mise à jour le plus récent et le temps de création. Chaque objet a des métadonnées de service définies.
• Défini par l'utilisateur : Métadonnées personnalisées pour la mise en évidence et la catégorisation. Défini à 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 arguments facultatifs troisième et quatrième:

  • Une table de UserIds . Cela peut aider avec le droit d'auteur et la traçabilité et l'élimination des droits de propriété intellectuelle.

  • Un objet DataStoreSetOptions, où vous pouvez définir des métadonnées personnalisées en utilisant la fonction SetMetadata().

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

• GetAsync() , IncrementAsync() , et RemoveAsync() retournent une deuxième valeur dans l'objet DataStoreKeyInfo.Cette deuxième valeur contient à la fois des propriétés et des fonctions définies par le service pour récupérer les 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 transmises à SetAsync() via SetMetadata().
  • La propriété Version récupère la version de la clé.
  • La propriété CreatedTime récupère le temps auquel la clé a été créée, formaté en tant que 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 en tant que nombre de millisecondes depuis l'époque.

  local DataStoreService = game:GetService("DataStoreService")
  
  local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
  
  local success, currentExperience, keyInfo = pcall(function()
      return experienceStore:GetAsync("User_1234")
  end)
  if success then
      print(currentExperience)
      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 de la clé actuelle.Il 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 limites de métadonnées.

Stockage de données ordonné

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

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Les magasins de données ordonnés supportent 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 de valeurs minimales/maximales.

L'exemple suivant trie les données de caractère en pages avec trois entrées, chacune dans l'ordre décroissant, puis parcourt les pages et affiche le nom et l'âge de chaque personnage.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Popule le boutiquede 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 tous les couples 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("----------")
			-- Avances jusqu'à la page suivante
			pages:AdvanceToNextPageAsync()
		end
	end
end