Datenbankversionierung, Auflistung und Caching

Verwalten Sie Ihre Daten mithilfe von Versionierung, Auflistung und Caching.

Versionierung

Die Versionierung erfolgt, wenn Sie setzen, aktualisieren und in­kre­mieren Daten. Die Funktionen SetAsync(), UpdateAsync() und IncrementAsync() erstellen versionierte Sicherungskopien Ihrer Daten mit dem ersten Schreibvorgang für jeden Schlüssel in jeder UTC-Stunde. Nachfolgende Schreibvorgänge an einem Schlüssel in derselben UTC-Stunde überschreiben die vorherigen Daten dauerhaft.

Versionierte Sicherungskopien laufen 30 Tage nach einem neuen Schreibvorgang ab, der sie überschreibt. Die neueste Version läuft niemals ab.

Die folgenden Funktionen führen Versionierungsoperationen durch:

Sie können die Versionierung verwenden, um Benutzeranfragen zu bearbeiten. Wenn ein Benutzer meldet, dass ein Problem am 2020-10-09T01:42 aufgetreten ist, können Sie die Daten auf eine vorherige Version zurücksetzen, indem Sie das folgende Beispiel verwenden:

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)

-- Holt die Version, die der angegebenen Zeit am nächsten liegt
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
        -- Liest die nächstgelegene Version
        local closestEntry = items[1]
        local success, value, info = pcall(function()
            return gameStore:GetVersionAsync(DATA_STORE_KEY, closestEntry.Version)
        end)
        -- Stellt den aktuellen Wert wieder her, indem er mit der nächstgelegenen Version überschrieben wird
        if success then
            local setOptions = Instance.new("DataStoreSetOptions")
            setOptions:SetMetadata(info:GetMetadata())
            gameStore:SetAsync(DATA_STORE_KEY, value, nil, setOptions)
        end
    else
        -- Keine Einträge gefunden
    end
end

Schnappschüsse

Die Snapshot Data Stores Open Cloud API ermöglicht es Ihnen, einmal täglich einen Schnappschuss aller Datenspeicher in einem Spiel zu erstellen. Bevor Sie ein Spiel-Update veröffentlichen, das Ihre Datenspeicher-Logik ändert, stellen Sie sicher, dass Sie einen Schnappschuss erstellen. Das Erstellen eines Schnappschusses garantiert, dass Sie die aktuellsten Daten aus der vorherigen Version des Spiels haben.

Wenn Sie beispielsweise ohne einen Schnappschuss ein Update um 3:30 UTC veröffentlichen, das zu Datenkorruption führt, überschreibt die beschädigte Daten jeden zwischen 3:00-3:30 UTC geschriebenen Wert. Wenn Sie jedoch um 3:29 UTC einen Schnappschuss erstellen, überschreibt die beschädigte Daten nichts, was vor 3:29 UTC geschrieben wurde, und die neuesten Daten für alle in der Zeit zwischen 3:00-3:29 UTC geschriebenen Schlüssel werden gespeichert.

Auflistung und Präfixe

Datenspeicher ermöglichen es Ihnen, nach Präfixen aufzulisten. Zum Beispiel, indem Sie nach den ersten n Zeichen eines Namens auflisten, wie "d", "do" oder "dog" für jeden Schlüssel oder Datenspeicher mit einem Präfix von "dog".

Sie können ein Präfix angeben, wenn Sie alle Datenspeicher oder Schlüssel auflisten, und nur Objekte zurückerhalten, die mit diesem Präfix übereinstimmen. Sowohl die Funktionen ListDataStoresAsync() als auch ListKeysAsync() geben ein DataStoreListingPages-Objekt zurück, das Sie verwenden können, um die Liste aufzulisten.

Geltungsbereiche

Sie können Schlüssel in einem Datenspeicher weiter organisieren, indem Sie eine eindeutige Zeichenfolge als Geltungsbereich für den zweiten Parameter von GetDataStore() festlegen. Der Standard-Geltungsbereich (wenn kein Geltungsbereich angegeben ist) ist global. Der Geltungsbereich wird automatisch an den Anfang aller Schlüssel in allen Operationen, die im Datenspeicher durchgeführt werden, vorangestellt.

Die Kombination aus Datenspeichernamen, Geltungsbereich und Schlüssel identifiziert einen Schlüssel eindeutig. Alle drei Werte sind erforderlich, um einen Schlüssel mit einem Geltungsbereich zu identifizieren. Wenn Sie beispielsweise einen global-Geltungsbereichsschlüssel mit dem Namen User_1234 lesen möchten, geschieht dies so:

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

Hat der Schlüssel User_1234 jedoch einen Geltungsbereich von gold, können Sie ihn nur so lesen:

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

AllScopes-Property

DataStoreOptions enthält eine AllScopes-Property, die es Ihnen ermöglicht, Schlüssel aus allen Geltungsbereichen in einer Liste zurückzugeben. Sie können dann die KeyName-Property eines Listenelements für gängige Datenspeicheroperationen wie Daten lesen mit GetAsync() und Daten entfernen mit RemoveAsync() verwenden.

Wenn Sie die AllScopes-Property verwenden, muss der zweite Parameter von GetDataStore() eine leere Zeichenfolge ("") sein.

local DataStoreService = game:GetService("DataStoreService")

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

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

Wenn Sie die AllScopes-Property aktivieren und einen neuen Schlüssel im Datenspeicher erstellen, müssen Sie immer einen Geltungsbereich für diesen Schlüssel im Format geltungsbereich/schlüsselname angeben. Wenn Sie dies nicht tun, geben die APIs einen Fehler zurück. Beispielsweise ist gold/player_34545 mit gold als Geltungsbereich akzeptabel, aber player_34545 führt zu einem Fehler.

Caching

Verwenden Sie Caching, um Daten aus Datenspeichern vorübergehend zu speichern, um die Leistung zu verbessern und die Anzahl der an den Server gesendeten Anfragen zu reduzieren. Beispielsweise kann ein Spiel eine Kopie seiner Daten zwischenspeichern, damit es schnell auf diese Daten zugreifen kann, ohne einen weiteren Aufruf an den Datenspeicher machen zu müssen.

Caching wird auf Änderungen angewendet, die Sie an Datenspeicherschlüsseln vornehmen, indem Sie:

• GetAsync() verwenden, um Daten zu lesen.
• SetAsync() verwenden, um Daten zu erstellen.
• UpdateAsync() verwenden, um Daten zu aktualisieren.
• IncrementAsync() verwenden, um Daten zu inkrementieren.
• RemoveAsync() verwenden, um Daten zu entfernen.

GetVersionAsync(), ListVersionsAsync(), ListKeysAsync() und ListDataStoresAsync() implementieren kein Caching und rufen immer die neuesten Daten vom Backend-Service ab.

Standardmäßig verwendet die Engine GetAsync(), um Werte, die Sie vom Backend abrufen, für vier Sekunden in einem lokalen Cache zu speichern. Außerdem geben GetAsync()-Anfragen für zwischengespeicherte Schlüsseln den zwischengespeicherten Wert zurück, anstatt fortzufahren, um das Backend zu erreichen. Ihre GetAsync()-Anfragen, die einen zwischengespeicherten Wert zurückgeben, zählen nicht zu Ihren Serverlimits und Durchsatzlimits.

Alle GetAsync()-Aufrufe, die einen Wert abrufen, der nicht im Backend zwischengespeichert ist, aktualisieren den Cache sofort und starten den viersekündigen Timer neu.

Caching deaktivieren

Um Caching zu deaktivieren und auf die Verwendung des Caches zu verzichten, um den aktuellsten Wert von den Servern abzurufen, fügen Sie den Parameter DataStoreGetOptions zu Ihrem Aufruf von GetAsync() hinzu und setzen Sie die UseCache-Property auf false, um Ihre Anfrage zu veranlassen, alle Schlüssel im Cache zu ignorieren.

Die Deaktivierung des Cachings ist nützlich, wenn Sie mehrere Server haben, die häufig auf einen Schlüssel schreiben und den neuesten Wert von den Servern abrufen müssen. Es kann jedoch dazu führen, dass Sie mehr von Ihren Datenspeicherlimits und -quoten verbrauchen, da GetAsync()-Anfragen, die das Caching umgehen, immer auf Ihren Durchsatz und Serverlimits angerechnet werden.

Für sofortige Überprüfungslesungen nach einem Schreibvorgang verwenden Sie GetAsync() mit DataStoreGetOptions.UseCache = false. Standardmäßig verwendet GetAsync() einen lokalen viersekündigen Cache, sodass eine normale Überprüfungslesung veraltete Daten zurückgeben kann.

Dies ist besonders wichtig, nachdem Schreibvorgänge wie UpdateAsync(), SetAsync(), IncrementAsync() oder RemoveAsync() einen Fehler zurückgeben. In diesen Fällen muss Ihr Code entscheiden, ob er erneut versuchen, zurückerstatten oder andere Korrekturmaßnahmen ergreifen soll.

Das folgende Beispiel zeigt, wie Sie den Cache umgehen können, wenn Sie das Ergebnis eines Schreibvorgangs überprüfen:

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
        -- Entscheidungen basierend auf dem Backend-Zustand treffen, nicht auf dem zwischengespeicherten Zustand
    end
end

Serialisierung

Der DataStoreService speichert Daten im JSON-Format. Wenn Sie Luau-Daten im Studio speichern, verwendet Roblox einen Prozess namens Serialisierung, um diese Daten in JSON zu konvertieren, um sie in Datenspeichern zu speichern. Roblox konvertiert dann Ihre Daten zurück in Luau und gibt sie Ihnen in einem anderen Prozess zurück, der als Deserialisierung bezeichnet wird.

Serialisierung und Deserialisierung unterstützen die folgenden Luau-Datentypen:

• Nil
• Booleans
• Zahlen

  • Sie sollten die speziellen numerischen Werte inf, -inf und nan nicht speichern, da diese Werte nicht den JSON-Standards entsprechen. Schlüssel, die diese Werte enthalten, können nicht über Open Cloud zugegriffen werden.
• Strings
• Tabellen

  • Tabellen dürfen nur andere unterstützte Datentypen enthalten
  • Numerische Schlüssel werden in Strings übersetzt, wenn die Länge der Tabelle 0 beträgt
• Puffer

Wenn Sie versuchen, einen Datentyp zu speichern, den die Serialisierung nicht unterstützt, werden Sie entweder:

• In der Speicherung dieses Datentyps fehlschlagen und eine Fehlermeldung erhalten.
• Erfolgreich diesen Datentyp als nil speichern.

Um zu debuggen, warum Ihr Datentyp als nil gespeichert wird, können Sie die Funktion JSONEncode verwenden. Wenn Sie Ihren Luau-Datentyp in diese Funktion übergeben, erhalten Sie ihn in dem Format zurück, in dem Roblox ihn in Datenspeichern gespeichert hätte, was Ihnen ermöglicht, die zurückgegebene Daten anzusehen und zu untersuchen.