Versi penyimpanan data, daftar, dan caching

Kelola data Anda menggunakan versi, daftar, dan caching.

Versi

Versi terjadi ketika Anda mengatur, memperbarui, dan meningkatkan data. Fungsi SetAsync(), UpdateAsync(), dan IncrementAsync() membuat salinan versi dari data Anda dengan menggunakan tulisan pertama untuk setiap kunci dalam setiap jam UTC. Tulisan berturut-turut ke sebuah kunci dalam jam UTC yang sama secara permanen akan menimpa data sebelumnya.

Salinan versi akan kedaluwarsa 30 hari setelah tulisan baru menimpanya. Versi terbaru tidak akan pernah kedaluwarsa.

Fungsi berikut melakukan operasi versi:

Anda dapat menggunakan versi untuk menangani permintaan pengguna. Jika seorang pengguna melaporkan bahwa masalah terjadi pada 2020-10-09T01:42, Anda dapat mengembalikan data ke versi sebelumnya menggunakan contoh berikut:

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)

-- Mendapatkan versi terdekat dengan waktu yang diberikan
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
        -- Membaca versi terdekat
        local closestEntry = items[1]
        local success, value, info = pcall(function()
            return gameStore:GetVersionAsync(DATA_STORE_KEY, closestEntry.Version)
        end)
        -- Mengembalikan nilai saat ini dengan menimpa versi terdekat
        if success then
            local setOptions = Instance.new("DataStoreSetOptions")
            setOptions:SetMetadata(info:GetMetadata())
            gameStore:SetAsync(DATA_STORE_KEY, value, nil, setOptions)
        end
    else
        -- Tidak ada entri ditemukan
    end
end

Snapshot

Snapshot Data Stores Open Cloud API memungkinkan Anda untuk mengambil snapshot dari semua penyimpanan data dalam sebuah permainan sekali sehari. Sebelum Anda menerbitkan pembaruan permainan yang mengubah logika penyimpanan data Anda, pastikan untuk mengambil snapshot. Mengambil snapshot menjamin bahwa Anda memiliki data terbaru yang tersedia dari versi terakhir permainan.

Misalnya, tanpa snapshot, jika Anda menerbitkan pembaruan pada pukul 3:30 UTC yang menyebabkan korupsi data, data yang rusak akan menimpa data apa pun yang ditulis antara 3:00-3:30 UTC. Namun, jika Anda mengambil snapshot pada pukul 3:29 UTC, data yang rusak tidak akan menimpa apa pun yang ditulis sebelum 3:29 UTC, dan data terbaru untuk semua kunci yang ditulis antara 3:00-3:29 UTC akan terpelihara.

Daftar dan awalan

Penyimpanan data memungkinkan Anda untuk mendaftar berdasarkan awalan. Misalnya, mendaftar berdasarkan n karakter pertama dari sebuah nama, seperti "d", "do", atau "dog" untuk kunci atau penyimpanan data mana pun dengan awalan "dog".

Anda dapat menentukan awalan saat mendaftar semua penyimpanan data atau kunci, dan hanya mendapatkan objek yang cocok dengan awalan tersebut. Baik ListDataStoresAsync() dan ListKeysAsync() mengembalikan objek DataStoreListingPages yang dapat Anda gunakan untuk mengenumerasi daftar.

Lingkup

Anda dapat mengatur kunci dalam penyimpanan data lebih lanjut dengan menetapkan string unik sebagai lingkup untuk parameter kedua dari GetDataStore(). Lingkup default (jika tidak ada lingkup yang ditentukan) adalah global. Lingkup secara otomatis ditambahkan di awal semua kunci dalam semua operasi yang dilakukan pada penyimpanan data.

Kombinasi nama penyimpanan data, lingkup, dan kunci secara unik mengidentifikasi sebuah kunci. Ketiga nilai ini diperlukan untuk mengidentifikasi sebuah kunci dengan lingkup. Misalnya, Anda dapat membaca kunci yang berskala global bernama User_1234 sebagai:

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

Namun, jika kunci User_1234 memiliki lingkup gold, Anda hanya dapat membacanya sebagai:

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

Properti AllScopes

DataStoreOptions berisi properti AllScopes yang memungkinkan Anda mengembalikan kunci dari semua lingkup dalam sebuah daftar. Anda kemudian dapat menggunakan properti KeyName dari item dalam daftar untuk operasi penyimpanan data umum seperti membaca data dengan GetAsync() dan menghapus data dengan RemoveAsync().

Ketika Anda menggunakan properti AllScopes, parameter kedua dari GetDataStore() harus berupa string kosong ("").

local DataStoreService = game:GetService("DataStoreService")

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

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

Jika Anda mengaktifkan properti AllScopes dan membuat kunci baru dalam penyimpanan data, Anda harus selalu menentukan lingkup untuk kunci tersebut dalam format lingkup/nama_kunci. Jika tidak, API akan menampilkan kesalahan. Misalnya, gold/player_34545 dapat diterima dengan gold sebagai lingkup, tetapi player_34545 menyebabkan kesalahan.

Caching

Gunakan caching untuk menyimpan sementara data dari penyimpanan data untuk meningkatkan kinerja dan mengurangi jumlah permintaan yang dibuat kepada server. Misalnya, sebuah permainan dapat menyimpan salinan datanya sehingga dapat mengakses data tersebut dengan cepat tanpa harus melakukan panggilan lain ke penyimpanan data.

Caching diterapkan pada modifikasi yang Anda lakukan terhadap kunci penyimpanan data dengan menggunakan:

• GetAsync() untuk membaca data.
• SetAsync() untuk membuat data.
• UpdateAsync() untuk memperbarui data.
• IncrementAsync() untuk meningkatkan data.
• RemoveAsync() untuk menghapus data.

GetVersionAsync(), ListVersionsAsync(), ListKeysAsync(), dan ListDataStoresAsync() tidak menerapkan caching dan selalu mengambil data terbaru dari latar belakang layanan.

Secara default, mesin menggunakan GetAsync() untuk menyimpan nilai yang Anda ambil dari latar belakang dalam cache lokal selama empat detik. Juga secara default, permintaan GetAsync() untuk kunci yang di-cache mengembalikan nilai yang di-cache alih-alih melanjutkan ke latar belakang. Permintaan GetAsync() Anda yang mengembalikan nilai caching tidak dihitung terhadap batasan server dan batasan throughput Anda.

Semua panggilan GetAsync() yang mengambil nilai yang tidak di-cache dari latar belakang segera memperbarui cache dan memulai ulang timer empat detik.

Menonaktifkan caching

Untuk menonaktifkan caching dan memilih untuk tidak menggunakan cache untuk mengambil nilai terbaru dari server, tambahkan parameter DataStoreGetOptions ke panggilan GetAsync() Anda dan atur properti UseCache ke false untuk membuat permintaan Anda mengabaikan kunci apa pun dalam cache.

Menonaktifkan caching berguna jika Anda memiliki beberapa server yang menulis ke kunci dengan frekuensi tinggi dan perlu mendapatkan nilai terbaru dari server. Namun, hal ini dapat menyebabkan Anda mengonsumsi lebih banyak batasan dan kuota penyimpanan data, karena permintaan GetAsync() yang melewati caching selalu dihitung terhadap batas throughput dan server Anda.

Untuk pembacaan verifikasi instan setelah menulis, gunakan GetAsync() dengan DataStoreGetOptions.UseCache = false. Secara default, GetAsync() menggunakan cache lokal selama empat detik, jadi pembacaan verifikasi normal dapat mengembalikan data yang sudah ketinggalan zaman.

Ini sangat penting setelah operasi penulisan seperti UpdateAsync(), SetAsync(), IncrementAsync(), atau RemoveAsync() mengembalikan kesalahan. Dalam kasus ini, kode Anda perlu menentukan apakah akan mencoba lagi, mengembalikan uang, atau mengambil tindakan korektif lainnya.

Contoh berikut menunjukkan cara melewati cache saat memverifikasi hasil penulisan:

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
        -- keputusan berdasarkan status latar belakang, bukan status cache
    end
end

Serialisasi

DataStoreService menyimpan data dalam format JSON. Ketika Anda menyimpan data Luau di Studio, Roblox menggunakan proses yang disebut serialisasi untuk mengubah data tersebut menjadi JSON untuk disimpan dalam penyimpanan data. Roblox kemudian mengubah data Anda kembali ke Luau dan mengembalikannya kepada Anda dalam proses lain yang disebut deserialisasi.

Serialisasi dan deserialisasi mendukung tipe data Luau berikut:

• Nil
• Boolean
• Angka

  • Anda tidak boleh menyimpan nilai numerik khusus inf, -inf, dan nan, karena nilai ini tidak sesuai dengan standar JSON. Anda tidak dapat mengakses kunci yang berisi nilai-nilai ini dengan Open Cloud.
• String
• Tabel

  • Tabel hanya boleh berisi tipe data lain yang didukung
  • Kunci numerik diterjemahkan menjadi string jika panjang tabel adalah 0
• Buffer

Jika Anda mencoba menyimpan tipe data yang tidak didukung oleh serialisasi, Anda akan:

• Gagal dalam menyimpan tipe data tersebut dan mendapatkan pesan kesalahan.
• Sukses dalam menyimpan tipe data tersebut sebagai nil.

Untuk memecahkan masalah mengapa tipe data Anda disimpan sebagai nil, Anda dapat menggunakan fungsi JSONEncode. Ketika Anda mengirimkan tipe data Luau Anda ke fungsi ini, Anda akan menerimanya kembali dalam format yang akan disimpan oleh Roblox dalam penyimpanan data, sehingga memungkinkan Anda untuk melihat dan menyelidiki data yang dikembalikan.