Stockages 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, afin que n'importe quel endroit dans une expérience puisse accéder et modifier les mêmes données, y compris les lieux sur différents serveurs.

Si vous souhaitez ajouter un contrôle de permission granulaire à vos magasins de données et les accéder en dehors des serveurs Studio ou Roblox, vous pouvez utiliser Ouvrir des API du cloud pour les magasins de données .

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

Activer l'accès Studio

Par défaut, les expériences testées dans Studio ne peuvent pas accéder aux magasins de données, vous devez donc d'abord les activer. 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 client. Pour éviter d'écraser les données de production, n'activez pas ce paramètre pour les expériences en direct.

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

1. Allez à Accueil > Paramètres du jeu > Sécurité .
2. Activer le activer/désactiver Activer l'accès Studio aux services d'API .
3. Cliquez sur Enregistrer .

Accéder aux magasins de données

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

1. Ajouter DataStoreService à un serveur côté Script.
2. Utilisez la fonction GetDataStore() et spécifiez le nom du data store que vous souhaitez utiliser. Si le data store n'existe pas, Studio 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 en fait un dictionnaire, similaire à une table Lua. Un clé unique indexe chaque valeur dans le boutiquede données, comme un Player.UserId unique ou une chaîne nommée pour une expérience promo.

Pour créer une nouvelle entrée, appelez Class.GlobalDataStore:SetAsync()|SetAsync() avec le nom de la 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

Mise à jour des données

Pour modifier n'importe quelle valeur stockée dans un boutiquede données, appelez Class.GlobalDataStore:UpdateAsync()|UpdateAsync() avec le nom de l'entrée et une fonction d'appel qui définit comment vous souhaitez mettre à jour l'entrée. Cette fonction d'appel prend la valeur actuelle et renvoie une nouvelle valeur en fonction de la logique que vous définissez. Si la fonction d'appel renvoie nil , l'

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

Mettre à jour vs

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

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

Utilisez la fonction mise à jour pour gérer les tentatives multisерveur. La fonction Class.GlobalDataStore:UpdateAsync()|UpdateAsync() :

• Lit la valeur de clé actuelle du serveur qui l'a dernièrement mise à jour avant d'apporter toute modification
• Est plus lent car il lit avant d'écrire
• Compte à la fois contre les limites de lecture et d'écriture

Lire les données

Pour lire la valeur d'une entrée dans un stockage de données, appelez GetAsync() avec le nom de la 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

Augmenter les données

Pour augmenter un nombre dans un boutiquede données, appelez Class.GlobalDataStore:IncrementAsync()|IncrementAsync() avec le nom de l'entrée et un nombre pour le montant de la valeur à modifier. Class.GlobalDataStore:IncrementAsync()|IncrementAsync() est une fonction de commodité qui vous permet d'éviter d'appeler Class.GlobalDataStore:UpdateAsync()|UpdateAsync() et

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

Suppression 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 y a deux types de métadonnées associés aux clés :

• Défini par le service : Métadonnées de lecture par défaut, comme la plus récente heure de mise à jour et le temps de création. Tous les objets ont une métadonnée de service définie.
• Utilisateur défini : Métadonnées personnalisées pour la marquage et la catégorisation. Défini en utilisant l'objet DataStoreSetOptions et la fonction Class.DataStoreSetOptions:SetMetric()|SetMetric() ».

Pour gérer les métadonnées, expandez le SetAsync(), UpdateAsync(), GetAsync(), 1> Class.GlobalDataStore:IncrementAsync()|IncrementAsync()1> et 4> Class

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

  • Une table de UserIds . Cela peut aider avec le suivi du droit d'auteur et de la propriété intellectuelle et la suppression.

  • 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 0> Class.DataStoreKeyInfo0>. Cette deuxième valeur contient à la fois des propriétés et des fonctions définies par le service pour récupérer des

  • 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 utilisateur que vous avez fournies à 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, formulé 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, formée comme le 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 avec 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 limites des métadonnées.

Stockages de données commandés

Par défaut, les magasins de données ne trient pas leur contenu. Si vous avez besoin d'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 commandés supportent les mêmes fonctions de base que les magasins de données par défaut, plus la fonction unique GetSortedAsync() .Ceci 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 minimum/maximum.

L'exemple suivant trie les données du personnage en pages avec trois entrées, chacune dans un ordre décroissant, puis traite les pages et les sorties de chaque personnage.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Popule la base de données boutique
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 dans des 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 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 prochaine page
			pages:AdvanceToNextPageAsync()
		end
	end
end