Veri deposu sürümlendirme, listeleme ve önbellekleme

Verilerinizi sürümlendirme, listeleme ve önbellekleme kullanarak yönetin.

Sürümlendirme

Sürümlendirme, verileri oluşturduğunuzda, güncellediğinizde ve artırdığınızda gerçekleşir. SetAsync(), UpdateAsync() ve IncrementAsync() işlevleri, her UTC saatinde her anahtar için ilk yazmayı kullanarak verilerinizin sürümlü yedeklerini oluşturur. Aynı UTC saatinde bir anahtara yapılan ardışık yazmalar önceki veriyi kalıcı olarak geçersiz kılmaktadır.

Sürümlü yedekler, yeni bir yazma ile geçersiz kılınmalarından 30 gün sonra sona erer. En son sürüm hiçbir zaman sona ermez.

Aşağıdaki işlevler sürümlendirme işlemleri gerçekleştirir:

Sürümlendirmeyi kullanıcı taleplerini işlemek için kullanabilirsiniz. Bir kullanıcı 2020-10-09T01:42 tarihinde bir problemin olduğunu bildirirse, verileri önceki bir sürüme döndürmek için aşağıdaki örneği kullanabilirsiniz:

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)

-- Verilen zamana en yakın sürümü alır
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
        -- En yakın sürümü okur
        local closestEntry = items[1]
        local success, value, info = pcall(function()
            return gameStore:GetVersionAsync(DATA_STORE_KEY, closestEntry.Version)
        end)
        -- En yakın sürümle mevcut değeri geçersiz kılar
        if success then
            local setOptions = Instance.new("DataStoreSetOptions")
            setOptions:SetMetadata(info:GetMetadata())
            gameStore:SetAsync(DATA_STORE_KEY, value, nil, setOptions)
        end
    else
        -- Giriş bulunamadı
    end
end

Anlık Görüntüler

Anlık Görüntü Veri Depoları Açık Bulut API'si, bir oyundaki tüm veri depolarının günlük olarak bir anlık görüntüsünü almanızı sağlar. Veri depolama mantığınızı değiştiren herhangi bir oyun güncellemesi yayınlamadan önce mutlaka bir anlık görüntü alın. Anlık görüntü almak, oyunun önceki sürümünden en güncel verilere sahip olmanızı garanti eder.

Örneğin, bir güncelleme yayınlayıp 3:30 UTC'de veri bozulmasına yol açtığınızda, bozulmuş veri 3:00-3:30 UTC arasında yazılan tüm verileri geçersiz kılar. Ancak, 3:29 UTC'de bir anlık görüntü alırsanız, bozulmuş veri 3:29 UTC'den önce yazılanları geçersiz kılamaz ve 3:00-3:29 UTC arasında yazılmış tüm anahtarlar için en son veriler korunur.

Listeleme ve ön ekler

Veri depoları, ön ek ile listeleme yapmanıza olanak tanır. Örneğin, bir anahtar veya "dog" ön eki olan herhangi bir veri deposu için "d", "do" veya "dog" gibi bir ismin ilk n karakterine göre listeleyebilirsiniz.

Tüm veri depolarını veya anahtarları listelemede bir ön ek belirtebilir ve yalnızca bu ön eklere uyan nesneleri alabilirsiniz. Hem ListDataStoresAsync() hem de ListKeysAsync() işlevleri, listeyi sıralamak için kullanabileceğiniz bir DataStoreListingPages nesnesi döndürür.

Kapsamlar

Veri deposundaki anahtarları, GetDataStore()'ın ikinci parametresi olarak benzersiz bir dize ayarlayarak daha fazla organize edebilirsiniz. Varsayılan kapsam (herhangi bir kapsam verilmezse) globaldır. Kapsam, veri deposu üzerindeki tüm işlemlerde tüm anahtarların başına otomatik olarak eklenir.

Veri deposu adı, kapsam ve anahtar kombinasyonu, bir anahtarı benzersiz olarak tanımlar. Bir kapsam ile bir anahtarı tanımlamak için bu üç değerin de gerekli olduğunu unutmayın. Örneğin, global kapsamındaki User_1234 adlı bir anahtarı şu şekilde okuyabilirsiniz:

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

Ancak, User_1234 anahtarı gold kapsamına sahipse, yalnızca şu şekilde okuyabilirsiniz:

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

AllScopes özelliği

DataStoreOptions, bir liste içindeki tüm kapsamlar için anahtarları döndürmenizi sağlayan bir AllScopes özelliği içerir. Daha sonra KeyName liste öğesinin özelliğini kullanarak veri okuma ve veri kaldırma işlemleri gibi ortak veri deposu işlemleri gerçekleştirebilirsiniz.

AllScopes özelliğini kullandığınızda, GetDataStore() işlevinin ikinci parametresi boş bir dize ("") olmalıdır.

local DataStoreService = game:GetService("DataStoreService")

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

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

AllScopes özelliğini etkinleştirirseniz ve veri deposunda yeni bir anahtar oluşturursanız, o anahtar için her zaman kapsamı belirtmelisiniz, biçimi kapsam/anahtar adı şeklindedir. Aksi takdirde, API'ler bir hata verir. Örneğin, gold/player_34545 kabul edilebilirken, player_34545 bir hata ile sonuçlanır.

Önbellekleme

Önbellekleme, performansı artırmak ve sunucuya yapılan istek sayısını azaltmak için veri depolarından verileri geçici olarak saklamak için kullanılır. Örneğin, bir oyun verilerinin bir kopyasını önbelleğe alarak bu verilere hızlıca erişebilir ve veri deposuna tekrar çağrı yapmadan ulaşabilir.

Önbellekleme, anahtarları kullanarak veri depolarında yaptığınız değişiklikleri kapsar:

• GetAsync() ile veri okuma.
• SetAsync() ile veri oluşturma.
• UpdateAsync() ile veri güncelleme.
• IncrementAsync() ile veri artırma.
• RemoveAsync() ile veri kaldırma.

GetVersionAsync(), ListVersionsAsync(), ListKeysAsync() ve ListDataStoresAsync() önbellekleme uygulamaz ve her zaman en son verileri hizmet arka ucundan alır.

Varsayılan olarak, motor, arka uçtan elde ettiğiniz değerleri dört saniye boyunca yerel bir önbellekte saklamak için GetAsync() kullanır. Ayrıca varsayılan olarak, GetAsync() önbellek anahtarları için yapılan istekler, arka uca devam etmeden önbellek değerini döndürür. GetAsync() isteklerinizden önbellek değerlerini döndürenler, sunucu limitlerinize ve performans limitlerinize dahil edilmez.

Arka uçtan önbelleğe alınmayan bir değeri almak için yapılan tüm GetAsync() çağrıları, önbelleği derhal günceller ve dört saniyelik zamanlayıcıyı yeniler.

Önbelleği devre dışı bırakma

Önbelleği devre dışı bırakmak ve sunuculardan en güncel değeri almak için önbelleği kullanmamayı seçmek istiyorsanız, GetAsync() çağrınıza DataStoreGetOptions parametresini ekleyin ve UseCache özelliğini false olarak ayarlayın, böylece isteğiniz önbellekteki anahtarları yok sayar.

Önbelleği devre dışı bırakmak, birden fazla sunucunun sık bir şekilde bir anahtara yazma işlemi yaptığı durumlarda, sunuculardan en son değeri almak için yararlıdır. Ancak, bu durum, GetAsync() taleplerinin önbelleği dikkate almadan her zaman kendi performans ve sunucu limitlerinizi tüketebileceğinden, veri deposu limitleriniz ve kotanız üzerinde daha fazla tüketim yapmanıza sebep olabilir.

Yazmadan sonraki hızlı doğrulama okumaları için, DataStoreGetOptions.UseCache = false ile GetAsync() kullanın. Varsayılan olarak, GetAsync() yerel bir dört saniyelik önbellek kullanır, bu nedenle normal bir doğrulama okuması eski veriler döndürebilir.

Bu, özellikle UpdateAsync(), SetAsync(), IncrementAsync() veya RemoveAsync() gibi yazma işlemleri bir hata döndürdüğünde önemlidir. Bu durumda, kodunuzun tekrar denemesi, geri ödeme yapması veya diğer düzeltici eylemleri alması gerektiğini belirlemelidir.

Aşağıdaki örnek, bir yazmanın sonucunu doğrularken önbelleği bypass etmenin nasıl yapılacağını göstermektedir:

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
        -- arka uç durumuna göre karar verin, önbelleğe alınmış duruma değil
    end
end

Seri Hale Getirme

DataStoreService, veriyi JSON formatında saklar. Studio'da Luau verilerini kaydettiğinizde, Roblox bu verileri JSON formatına dönüştürmek için seri hale getirme adı verilen bir süreç kullanır. Roblox daha sonra verilerinizi Luau'ya geri dönüştürerek size başka bir süreç içinde geri döndürür ve bu işleme ters seri hale getirme denir.

Seri hale getirme ve ters seri hale getirme, aşağıdaki Luau veri türlerini destekler:

• Nil
• Boolean'lar
• Sayılar

  • inf, -inf ve nan gibi özel sayısal değerleri saklamamalısınız, çünkü bu değerler JSON standartlarına uymaz. Bu değerleri içeren anahtarlara Açık Bulut ile erişemezsiniz.
• String'ler
• Tablolar

  • Tablolar yalnızca diğer desteklenen veri türlerini içermelidir
  • Sayısal anahtarlar, tablonun uzunluğu 0 ise string'lere dönüştürülür
• Tamponlar

Desteklenmeyen bir veri türünü saklamaya çalıştığınızda, ya:

• O veri türünü saklamada başarısız olur ve bir hata mesajı alırsınız.
• O veri türünü nil olarak saklayarak başarırsınız.

Veri türünüzün neden nil olarak saklandığını çözmek için, JSONEncode işlevini kullanabilirsiniz. Luau veri türünüzü bu işlevin içine aktardığınızda, onu veri depolarıyla saklayacak formatta geri alırsınız, bu da size döndürülen veriyi önizleme ve inceleme olanağı tanır.