Versionamento, Elenco e Cache dei Data Store

Gestisci i tuoi dati utilizzando il versionamento, l'elenco e la cache.

Versionamento

Il versionamento avviene quando imposti, aggiorni e incrementi i dati. Le funzioni SetAsync(), UpdateAsync() e IncrementAsync() creano backup versionati dei tuoi dati utilizzando la prima scrittura per ciascuna chiave in ogni ora UTC. Scritture successive a una chiave nella stessa ora UTC sovrascrivono permanentemente i dati precedenti.

I backup versionati scadono 30 giorni dopo che una nuova scrittura li sovrascrive. L'ultima versione non scade mai.

Le seguenti funzioni eseguono operazioni di versionamento:

Puoi utilizzare il versionamento per gestire le richieste degli utenti. Se un utente segnala che si è verificato un problema il 2020-10-09T01:42, puoi ripristinare i dati a una versione precedente utilizzando il seguente esempio:

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)

-- Ottiene la versione più vicina al tempo dato
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
        -- Legge la versione più vicina
        local closestEntry = items[1]
        local success, value, info = pcall(function()
            return gameStore:GetVersionAsync(DATA_STORE_KEY, closestEntry.Version)
        end)
        -- Ripristina il valore attuale sovrascrivendolo con la versione più vicina
        if success then
            local setOptions = Instance.new("DataStoreSetOptions")
            setOptions:SetMetadata(info:GetMetadata())
            gameStore:SetAsync(DATA_STORE_KEY, value, nil, setOptions)
        end
    else
        -- Nessuna voce trovata
    end
end

Istantanee

L'API Snapshot Data Stores Open Cloud ti consente di fare un'istantanea di tutti i data store in un gioco una volta al giorno. Prima di pubblicare qualsiasi aggiornamento del gioco che modifica la tua logica di archiviazione dei dati, assicurati di fare un'istantanea. Prendere un'istantanea garantisce che tu abbia i dati più recenti disponibili dalla versione precedente del gioco.

Ad esempio, senza un'istantanea, se pubblichi un aggiornamento alle 3:30 UTC che causa corruzione dei dati, i dati corrotti sovrascriveranno qualsiasi dato scritto tra le 3:00 e le 3:30 UTC. Se però fai un'istantanea alle 3:29 UTC, i dati corrotti non sovrascriveranno nulla scritto prima delle 3:29 UTC e i dati più recenti per tutte le chiavi scritte tra le 3:00 e le 3:29 UTC sono preservati.

Elencare e prefissi

I data store ti consentono di elencare per prefisso. Ad esempio, elencando i primi n caratteri di un nome, come "d", "do" o "dog" per qualsiasi chiave o data store con un prefisso di "dog".

Puoi specificare un prefisso quando elenchi tutti i data store o le chiavi e ricevere solo oggetti che corrispondono a quel prefisso. Sia le funzioni ListDataStoresAsync() che ListKeysAsync() restituiscono un oggetto DataStoreListingPages che puoi utilizzare per enumerare l'elenco.

Scope

Puoi organizzare ulteriormente le chiavi in un data store impostando una stringa unica come scope per il secondo parametro di GetDataStore(). Lo scope predefinito (se non viene fornito uno scope) è global. Lo scope viene automaticamente anteposto all'inizio di tutte le chiavi in tutte le operazioni eseguite sul data store.

La combinazione di nome del data store, scope e chiave identifica univocamente una chiave. Tutti e tre i valori sono necessari per identificare una chiave con uno scope. Ad esempio, puoi leggere una chiave con scope global chiamata User_1234 come:

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

Se la chiave User_1234 ha uno scope di gold, però, puoi leggerla solo come:

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

Proprietà AllScopes

DataStoreOptions contiene una proprietà AllScopes che ti consente di restituire chiavi da tutti gli scope in un elenco. Puoi quindi utilizzare la proprietà KeyName di un elemento dell'elenco per operazioni comuni sui data store come leggere dati con GetAsync() e rimuovere dati con RemoveAsync().

Quando utilizzi la proprietà AllScopes, il secondo parametro di GetDataStore() deve essere una stringa vuota ("").

local DataStoreService = game:GetService("DataStoreService")

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

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

Se abiliti la proprietà AllScopes e crei una nuova chiave nel data store, devi sempre specificare uno scope per quella chiave nel formato scope/nomechiave. Se non lo fai, le API generano un errore. Ad esempio, gold/player_34545 è accettabile con gold come scope, ma player_34545 porta a un errore.

Cache

Utilizza la cache per memorizzare temporaneamente i dati dai data store per migliorare le prestazioni e ridurre il numero di richieste effettuate al server. Ad esempio, un gioco può memorizzare una copia dei propri dati in modo da poter accedere rapidamente a quei dati senza dover effettuare un'altra chiamata al data store.

La cache si applica alle modifiche che apporti alle chiavi del data store utilizzando:

• GetAsync() per leggere dati.
• SetAsync() per creare dati.
• UpdateAsync() per aggiornare dati.
• IncrementAsync() per incrementare dati.
• RemoveAsync() per rimuovere dati.

GetVersionAsync(), ListVersionsAsync(), ListKeysAsync(), e ListDataStoresAsync() non implementano la cache e recuperano sempre i dati più recenti dal backend del servizio.

Per impostazione predefinita, il motore utilizza GetAsync() per memorizzare i valori che recuperi dal backend in una cache locale per quattro secondi. Inoltre, per impostazione predefinita, le richieste GetAsync() per chiavi memorizzate restituiscono il valore memorizzato anziché continuare verso il backend. Le tue richieste GetAsync() che restituiscono un valore memorizzato non contano verso i tuoi limiti del server e limiti di throughput.

Tutte le chiamate GetAsync() che recuperano un valore non memorizzato dal backend aggiornano immediatamente la cache e riavviano il timer di quattro secondi.

Disattivare la cache

Per disattivare la cache e optare per non utilizzare la cache per recuperare il valore più aggiornato dai server, aggiungi il parametro DataStoreGetOptions alla tua chiamata GetAsync() e imposta la proprietà UseCache su false per far sì che la tua richiesta ignori qualsiasi chiave nella cache.

Disattivare la cache è utile se hai più server che scrivono a una chiave con alta frequenza e hai bisogno di ottenere il valore più recente dai server. Tuttavia, può farti consumare di più i tuoi limiti e quote dei data store, poiché le richieste GetAsync() che bypassano la cache contano sempre verso i tuoi limiti di throughput e server.

Per letture di verifica immediate dopo una scrittura, utilizza GetAsync() con DataStoreGetOptions.UseCache = false. Per impostazione predefinita, GetAsync() utilizza una cache locale di quattro secondi, quindi una lettura di verifica normale può restituire dati non aggiornati.

Questo è particolarmente importante dopo operazioni di scrittura come UpdateAsync(), SetAsync(), IncrementAsync(), o RemoveAsync() che restituiscono un errore. In questi casi, il tuo codice deve determinare se riprovare, rimborsare o prendere altre misure correttive.

Il seguente esempio mostra come bypassare la cache durante la verifica del risultato di una scrittura:

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
        -- decidi in base allo stato del backend, non allo stato memorizzato
    end
end

Serializzazione

Il DataStoreService memorizza i dati in formato JSON. Quando salvi i dati Luau in Studio, Roblox utilizza un processo chiamato serializzazione per convertire quei dati in JSON per salvarli nei data store. Roblox poi converte i tuoi dati di nuovo in Luau e te li restituisce in un altro processo chiamato deserializzazione.

La serializzazione e la deserializzazione supportano i seguenti tipi di dati Luau:

• Nil
• Booleani
• Numeri

  • Non dovresti memorizzare i valori numerici speciali inf, -inf, e nan, poiché questi valori non conformano agli standard JSON. Non puoi accedere a chiavi che contengono questi valori con Open Cloud.
• Stringhe
• Tabelle

  • Le tabelle devono contenere solo altri tipi di dati supportati
  • Le chiavi numeriche vengono tradotte in stringhe se la lunghezza della tabella è 0
• Buffer

Se provi a memorizzare un tipo di dati che la serializzazione non supporta, ottieni uno dei seguenti risultati:

• Fallisci nel memorizzare quel tipo di dati e ricevi un messaggio di errore.
• Riesci a memorizzare quel tipo di dati come nil.

Per debugare il motivo per cui il tuo tipo di dati viene memorizzato come nil, puoi utilizzare la funzione JSONEncode. Quando passi il tuo tipo di dati Luau a questa funzione, lo ricevi di nuovo nel formato in cui Roblox lo avrebbe memorizzato con i data store, il che ti consente di visualizzare e investigare i dati restituiti.