Gestion des versions, des listes et du cache des magasins de données

Gérez vos données en utilisant la gestion des versions, des listes et du cache.

Gestion des versions

La gestion des versions se produit lorsque vous définissez, mettez à jour et incrémentez des données. Les fonctions SetAsync(), UpdateAsync(), et IncrementAsync() créent des sauvegardes versionnées de vos données en utilisant la première écriture pour chaque clé à chaque heure UTC. Les écritures successives sur une clé dans la même heure UTC remplacent définitivement les données précédentes.

Les sauvegardes versionnées expirent 30 jours après qu'une nouvelle écriture les ait remplacées. La dernière version n'expire jamais.

Les fonctions suivantes effectuent des opérations de gestion des versions :

Vous pouvez utiliser la gestion des versions pour traiter les demandes des utilisateurs. Si un utilisateur signale qu'un problème s'est produit à 2020-10-09T01:42, vous pouvez revenir à une version précédente des données en utilisant l'exemple suivant :

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local DATA_STORE_KEY = "User_1234"

local maxDate = DateTime.fromUniversalTime(2020, 10, 09, 01, 42)

-- Obtient la version la plus proche de l'heure donnée
local listSuccess, pages = pcall(function()
    return gameStore:ListVersionsAsync(DATA_STORE_KEY, Enum.SortDirection.Descending, nil, maxDate.UnixTimestampMillis)
end)
if listSuccess then
    local items = pages:GetCurrentPage()
    if #items > 0 then
        -- Lit la version la plus proche
        local closestEntry = items[1]
        local success, value, info = pcall(function()
            return gameStore:GetVersionAsync(DATA_STORE_KEY, closestEntry.Version)
        end)
        -- Restaure la valeur actuelle en la remplaçant par la version la plus proche
        if success then
            local setOptions = Instance.new("DataStoreSetOptions")
            setOptions:SetMetadata(info:GetMetadata())
            gameStore:SetAsync(DATA_STORE_KEY, value, nil, setOptions)
        end
    else
        -- Aucune entrée trouvée
    end
end

Instantanés

L'API Open Cloud des magasins de données Instantanés vous permet de prendre un instantané de tous les magasins de données d'un jeu une fois par jour. Avant de publier une mise à jour de jeu qui modifie votre logique de stockage de données, assurez-vous de prendre un instantané. Prendre un instantané garantit que vous disposez des données les plus récentes disponibles de la version précédente du jeu.

Par exemple, sans un instantané, si vous publiez une mise à jour à 3:30 UTC qui cause une corruption des données, les données corrompues remplacent toutes les données écrites entre 3:00 et 3:30 UTC. Si vous prenez un instantané à 3:29 UTC, cependant, les données corrompues ne remplacent rien écrit avant 3:29 UTC, et les dernières données pour toutes les clés écrites entre 3:00 et 3:29 UTC sont préservées.

Listing et préfixes

Les magasins de données vous permettent de lister par préfixe. Par exemple, lister par les premiers n caractères d'un nom, comme "d", "do" ou "dog" pour toute clé ou magasin de données avec un préfixe de "dog".

Vous pouvez spécifier un préfixe lors de la liste de tous les magasins de données ou clés, et obtenir uniquement des objets qui correspondent à ce préfixe. Les fonctions ListDataStoresAsync() et ListKeysAsync() retournent un objet DataStoreListingPages que vous pouvez utiliser pour énumérer la liste.

Portées

Vous pouvez organiser davantage les clés dans un magasin de données en définissant une chaîne unique comme portée pour le deuxième paramètre de GetDataStore(). La portée par défaut (si aucune portée n'est donnée) est global. La portée est automatiquement ajoutée au début de toutes les clés dans toutes les opérations effectuées sur le magasin de données.

La combinaison du nom du magasin de données, de la portée et de la clé identifie de manière unique une clé. Les trois valeurs sont nécessaires pour identifier une clé avec une portée. Par exemple, vous pouvez lire une clé à portée global nommée User_1234 comme suit :

local DataStoreService = game:GetService("DataStoreService")
local inventoryStore = DataStoreService:GetDataStore("PlayerInventory")
local success, currentGold = pcall(function()
  return inventoryStore:GetAsync("User_1234")
end)

Si la clé User_1234 a une portée de gold, cependant, vous ne pouvez la lire que comme suit :

local DataStoreService = game:GetService("DataStoreService")
local inventoryStore = DataStoreService:GetDataStore("PlayerInventory", "gold")
local success, currentGold = pcall(function()
  return inventoryStore:GetAsync("User_1234")
end)

Propriété AllScopes

DataStoreOptions contient une propriété AllScopes qui vous permet de retourner des clés de toutes les portées dans une liste. Vous pouvez ensuite utiliser la propriété KeyName d'un élément de la liste pour des opérations courantes de magasin de données comme lire des données avec GetAsync() et supprimer des données avec RemoveAsync().

Lorsque vous utilisez la propriété AllScopes, le deuxième paramètre de GetDataStore() doit être une chaîne vide ("").

local DataStoreService = game:GetService("DataStoreService")

local options = Instance.new("DataStoreOptions")
options.AllScopes = true

local ds = DataStoreService:GetDataStore("DS1", "", options)

Si vous activez la propriété AllScopes et créez une nouvelle clé dans le magasin de données, vous devez toujours spécifier une portée pour cette clé au format portée/nom_de_clé. Si vous ne le faites pas, les API renvoient une erreur. Par exemple, gold/player_34545 est acceptable avec gold comme portée, mais player_34545 entraîne une erreur.

Mise en cache

Utilisez la mise en cache pour stocker temporairement des données provenant des magasins de données afin d'améliorer les performances et de réduire le nombre de requêtes envoyées au serveur. Par exemple, un jeu peut mettre en cache une copie de ses données afin d'accéder rapidement à ces données sans avoir à faire un autre appel au magasin de données.

La mise en cache s'applique aux modifications que vous apportez aux clés du magasin de données en utilisant :

• GetAsync() pour lire des données.
• SetAsync() pour créer des données.
• UpdateAsync() pour mettre à jour des données.
• IncrementAsync() pour incrémenter des données.
• RemoveAsync() pour supprimer des données.

GetVersionAsync(), ListVersionsAsync(), ListKeysAsync(), et ListDataStoresAsync() n'implémentent pas la mise en cache et récupèrent toujours les dernières données du backend du service.

Par défaut, le moteur utilise GetAsync() pour stocker les valeurs que vous récupérez du backend dans un cache local pendant quatre secondes. De plus, par défaut, les requêtes GetAsync() pour les clés mises en cache retournent la valeur mise en cache au lieu de continuer vers le backend. Vos requêtes GetAsync() qui retournent une valeur mise en cache ne comptent pas dans vos limites de serveur et limites de débit.

Tous les appels GetAsync() qui récupèrent une valeur non mise en cache du backend mettent immédiatement à jour le cache et redémarrent le minuteur de quatre secondes.

Désactiver la mise en cache

Pour désactiver la mise en cache et choisir de ne pas utiliser le cache pour récupérer la valeur la plus à jour des serveurs, ajoutez le paramètre DataStoreGetOptions à votre appel GetAsync() et définissez la propriété UseCache sur false pour faire en sorte que votre requête ignore toutes les clés dans le cache.

Désactiver la mise en cache est utile si vous avez plusieurs serveurs écrivant sur une clé avec une fréquence élevée et que vous devez obtenir la dernière valeur des serveurs. Cependant, cela peut vous amener à consommer davantage de vos limites et quotas de magasins de données, car les requêtes GetAsync() contournant la mise en cache comptent toujours pour vos limites de débit et de serveur.

Pour des lectures de vérification immédiates après une écriture, utilisez GetAsync() avec DataStoreGetOptions.UseCache = false. Par défaut, GetAsync() utilise un cache local de quatre secondes, donc une lecture de vérification normale peut retourner des données obsolètes.

Ceci est particulièrement important après des opérations d'écriture comme UpdateAsync(), SetAsync(), IncrementAsync(), ou RemoveAsync() qui retournent une erreur. Dans ces cas, votre code doit déterminer s'il faut réessayer, rembourser ou prendre d'autres mesures correctives.

L'exemple suivant montre comment contourner le cache lors de la vérification du résultat d'une écriture :

local ok = pcall(function()
    store:UpdateAsync(key, transform)
end)

if not ok then
    local options = Instance.new("DataStoreGetOptions")
    options.UseCache = false

    local success, value = pcall(function()
        return store:GetAsync(key, options)
    end)

    if success then
        -- décider en fonction de l'état du backend, pas de l'état mis en cache
    end
end

Sérialisation

Le DataStoreService stocke les données au format JSON. Lorsque vous enregistrez des données Luau dans Studio, Roblox utilise un processus appelé sérialisation pour convertir ces données en JSON afin de les enregistrer dans les magasins de données. Roblox convertit ensuite vos données en Luau et vous les renvoie dans un autre processus appelé désérialisation.

La sérialisation et la désérialisation prennent en charge les types de données Luau suivants :

• Nil
• Booléens
• Nombres

  • Vous ne devez pas stocker les valeurs numériques spéciales inf, -inf, et nan, car ces valeurs ne respectent pas les normes JSON. Lorsque vous récupérez une entrée contenant ces valeurs via Open Cloud, la réponse les représente comme des objets JSON tagués. Pour plus de détails, voir Nombres non finis.
• Chaînes
• Tables

  • Les tables ne doivent contenir que d'autres types de données pris en charge
  • Les clés numériques sont traduites en chaînes si la longueur de la table est 0
• Buffers

Si vous essayez de stocker un type de données que la sérialisation ne prend pas en charge, vous :

• Échouez à stocker ce type de données et obtenez un message d'erreur.
• Réussissez à stocker ce type de données en tant que nil.

Pour déboguer pourquoi votre type de données est stocké en tant que nil, vous pouvez utiliser la fonction JSONEncode. Lorsque vous passez votre type de données Luau dans cette fonction, vous le recevez dans le format que Roblox aurait stocké avec les magasins de données, ce qui vous permet de prévisualiser et d'examiner les données retournées.