การจัดการเวอร์ชัน รายการ และการแคชของข้อมูล

จัดการข้อมูลของคุณโดยใช้การจัดการเวอร์ชัน รายการ และการแคช

การจัดการเวอร์ชัน

การจัดการเวอร์ชันเกิดขึ้นเมื่อคุณ ตั้งค่า, ปรับปรุง, และ เพิ่มจำนวน ข้อมูล ฟังก์ชัน SetAsync(), UpdateAsync(), และ IncrementAsync() จะสร้างสำเนาเวอร์ชันของข้อมูลของคุณโดยใช้การเขียนครั้งแรกไปยังแต่ละคีย์ในแต่ละชั่วโมง UTC การเขียนต่อเนื่องไปยังคีย์ในชั่วโมง UTC เดียวกันจะเขียนทับข้อมูลก่อนหน้านี้อย่างถาวร

สำเนาเวอร์ชันจะหมดอายุ 30 วันหลังการเขียนใหม่ทับพวกเขา เวอร์ชันล่าสุดจะไม่มีวันหมดอายุ

ฟังก์ชันต่อไปนี้ทำการดำเนินการเกี่ยวกับเวอร์ชัน:

คุณสามารถใช้การจัดการเวอร์ชันเพื่อจัดการคำขอของผู้ใช้ หากผู้ใช้รายงานว่ามีปัญหาเกิดขึ้นเมื่อวันที่ 2020-10-09T01:42 คุณสามารถคืนข้อมูลไปยังเวอร์ชันก่อนหน้าโดยใช้ตัวอย่างต่อไปนี้:

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)

-- รับเวอร์ชันที่ใกล้ที่สุดกับเวลาที่กำหนด
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
        -- อ่านเวอร์ชันที่ใกล้ที่สุด
        local closestEntry = items[1]
        local success, value, info = pcall(function()
            return gameStore:GetVersionAsync(DATA_STORE_KEY, closestEntry.Version)
        end)
        -- คืนค่าปัจจุบันโดยการเขียนทับมันด้วยเวอร์ชันที่ใกล้ที่สุด
        if success then
            local setOptions = Instance.new("DataStoreSetOptions")
            setOptions:SetMetadata(info:GetMetadata())
            gameStore:SetAsync(DATA_STORE_KEY, value, nil, setOptions)
        end
    else
        -- ไม่พบรายการ
    end
end

สแน็ปช็อต

Snapshot Data Stores Open Cloud API ช่วยให้คุณสามารถสร้างสแน็ปช็อตของทุกที่เก็บข้อมูลในเกมได้หนึ่งครั้งต่อวัน ก่อนที่คุณจะเผยแพร่อัปเดตเกมใด ๆ ที่เปลี่ยนแปลงตรรกะการจัดเก็บข้อมูลของคุณ ให้แน่ใจว่าได้ทำการสร้างสแน็ปช็อต การสร้างสแน็ปช็อตเป็นการรับประกันว่าคุณมีข้อมูลที่ล่าสุดจากเวอร์ชันก่อนหน้าของเกม

ตัวอย่างเช่น หากไม่มีสแน็ปช็อต หากคุณเผยแพร่อัปเดตในเวลา 3:30 UTC ที่ทำให้ข้อมูลเสียหาย ข้อมูลที่เสียหายจะเขียนทับข้อมูลใด ๆ ที่เขียนระหว่าง 3:00-3:30 UTC อย่างไรก็ตาม หากคุณทำการสร้างสแน็ปช็อตเมื่อเวลา 3:29 UTC ข้อมูลที่เสียหายจะไม่เขียนทับข้อมูลใด ๆ ที่เขียนก่อน 3:29 UTC และข้อมูลล่าสุดสำหรับทุกคีย์ที่เขียนระหว่าง 3:00-3:29 UTC จะถูกเก็บรักษาไว้

การรายการและคำนำหน้า

ที่เก็บข้อมูลช่วยให้คุณสามารถสร้างรายการตามคำนำหน้าได้ ตัวอย่างเช่น การสร้างรายการตามตัวอักษรแรก n ของชื่อ เช่น "d", "do", หรือ "dog" สำหรับคีย์ใด ๆ หรือที่เก็บข้อมูลที่มีคำนำหน้าว่า "dog"

คุณสามารถระบุคำนำหน้าเมื่อสร้างรายการทุกที่เก็บข้อมูลหรือคีย์ และได้รับเฉพาะวัตถุที่ตรงกับคำนำหน้านั้น ฟังก์ชัน ListDataStoresAsync() และ ListKeysAsync() จะส่งคืนวัตถุ DataStoreListingPages ที่คุณสามารถใช้เพื่อแต่ละรายการได้

ขอบเขต

คุณสามารถจัดระเบียบคีย์ในที่เก็บข้อมูลได้เพิ่มเติมโดยการตั้งค่าสตริงที่ไม่ซ้ำกันเป็นขอบเขตสำหรับพารามิเตอร์ที่สองของ GetDataStore() ขอบเขตเริ่มต้น (หากไม่มีขอบเขตระบุ) คือ global ขอบเขตจะถูกนำไปข้างหน้าทุกคีย์ในการดำเนินการทั้งหมดที่ทำในที่เก็บข้อมูล

การรวมกันของชื่อที่เก็บข้อมูล ขอบเขต และคีย์จะระบุตัวคีย์เฉพาะได้ ค่าทั้งสามนี้จำเป็นในการระบุตัวคีย์ที่มีขอบเขต ตัวอย่างเช่น คุณสามารถอ่านคีย์ที่มีขอบเขตเป็น global ชื่อว่า User_1234 ได้ดังนี้:

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

หากคีย์ User_1234 มีขอบเขตเป็น gold อย่างไรก็ตาม คุณจะสามารถอ่านได้เพียงดังนี้:

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

คุณสมบัติ AllScopes

DataStoreOptions มีคุณสมบัติ AllScopes ที่ช่วยให้คุณสามารถคืนค่าคีย์จากทุก ขอบเขต ในรายการ คุณสามารถใช้ KeyName ของรายการสำหรับการดำเนินการที่เก็บข้อมูลทั่วไป เช่น การอ่านข้อมูล ด้วย GetAsync() และ การลบข้อมูล ด้วย RemoveAsync()

เมื่อใช้คุณสมบัติ AllScopes พารามิเตอร์ที่สองของ GetDataStore() จะต้องเป็นสตริงว่าง ("")

local DataStoreService = game:GetService("DataStoreService")

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

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

หากคุณเปิดใช้งานคุณสมบัติ AllScopes และสร้างคีย์ใหม่ในที่เก็บข้อมูล คุณต้องระบุขอบเขตสำหรับคีย์นั้นในรูปแบบของ scope/keyname เสมอ หากคุณไม่ทำเช่นนั้น API จะโยนข้อผิดพลาด ตัวอย่างเช่น gold/player_34545 ถือเป็นที่ยอมรับโดยมี gold เป็นขอบเขต แต่ player_34545 จะนำไปสู่ข้อผิดพลาด

การแคช

ใช้การแคชเพื่อเก็บข้อมูลจากที่เก็บข้อมูลชั่วคราวเพื่อเพิ่มประสิทธิภาพและลดจำนวนคำขอที่ถูกส่งไปยังเซิร์ฟเวอร์ ตัวอย่างเช่น เกมสามารถแคชสำเนาของข้อมูลของมันเพื่อให้สามารถเข้าถึงข้อมูลนั้นได้อย่างรวดเร็วโดยไม่ต้องเรียกอีกครั้งไปยังที่เก็บข้อมูล

การแคชใช้กับการเปลี่ยนแปลงที่คุณทำกับคีย์ที่เก็บข้อมูลโดยใช้:

• GetAsync() เพื่อ อ่านข้อมูล
• SetAsync() เพื่อ สร้างข้อมูล
• UpdateAsync() เพื่อ ปรับปรุงข้อมูล
• IncrementAsync() เพื่อ เพิ่มข้อมูล
• RemoveAsync() เพื่อ ลบข้อมูล

GetVersionAsync(), ListVersionsAsync(), ListKeysAsync(), และ ListDataStoresAsync() ไม่ใช้การแคชและจะเรียกค่าข้อมูลล่าสุดจากบริการด้านหลังเสมอ

โดยค่าเริ่มต้น เอนจินใช้ GetAsync() เพื่อเก็บค่าที่คุณดึงมาจากด้านหลังไว้ในแคชท้องถิ่นเป็นเวลาสี่วินาที นอกจากนี้ โดยค่าเริ่มต้น คำขอ GetAsync() สำหรับคีย์ที่แคชจะส่งคืนค่าที่ถูกแคชแทนที่จะดำเนินต่อไปที่ด้านหลัง คำขอ GetAsync() ของคุณที่ส่งคืนค่าที่ถูกแคชจะไม่ถูกนับเข้าสู่ ขีดจำกัดเซิร์ฟเวอร์ และ ขีดจำกัด throughput

การเรียก GetAsync() ทั้งหมดที่ดึงค่าที่ไม่ถูกแคชจากด้านหลังจะอัปเดตแคชทันทีและรีเซ็ตตัวจับเวลาสี่วินาที

ปิดการใช้งานการแคช

เพื่อปิดการใช้งานการแคชและเลือกไม่ใช้การใช้แคชเพื่อดึงค่าที่ล่าสุดจากเซิร์ฟเวอร์ ให้เพิ่มพารามิเตอร์ DataStoreGetOptions ไปยังการเรียก GetAsync() ของคุณและตั้งค่าคุณสมบัติ UseCache เป็น false เพื่อทำให้คำขอของคุณละเว้นคีย์ใด ๆ ในแคช

การปิดการใช้งานการแคชมีประโยชน์หากคุณมีเซิร์ฟเวอร์หลายตัวที่เขียนไปยังคีย์อย่างถี่ถ้วนและต้องการให้ได้ค่าล่าสุดจากเซิร์ฟเวอร์ อย่างไรก็ตาม อาจทำให้คุณใช้ขีดจำกัดและโควต้าของ ที่เก็บข้อมูล มากขึ้น เนื่องจากคำขอ GetAsync() ที่ไม่ใช้การแคชจะถูกนับเข้าสู่ขีดจำกัด throughput และเซิร์ฟเวอร์เสมอ

เพื่อการตรวจสอบค่าทันทีหลังการเขียน ใช้ GetAsync() พร้อม DataStoreGetOptions.UseCache = false โดยค่าเริ่มต้น, GetAsync() ใช้แคชท้องถิ่นเป็นเวลาสี่วินาที ดังนั้นการตรวจสอบปกติอาจส่งคืนข้อมูลที่ล้าสมัย

นี่เป็นสิ่งที่สำคัญโดยเฉพาะหลังจากการดำเนินการเขียน เช่น UpdateAsync(), SetAsync(), IncrementAsync(), หรือ RemoveAsync() ที่ส่งคืนข้อผิดพลาด ในกรณีเหล่านี้ โค้ดของคุณต้องกำหนดว่าจะลองอีกครั้ง คืนเงิน หรือดำเนินการอื่น ๆ อย่างไร

ตัวอย่างต่อไปนี้แสดงวิธีการข้ามแคชเมื่อทำการตรวจสอบผลลัพธ์ของการเขียน:

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
        -- ตัดสินใจตามสถานะด้านหลัง ไม่ใช่สถานะแคช
    end
end

การจัดรูปแบบข้อมูล

DataStoreService จะจัดเก็บข้อมูลในรูปแบบ JSON เมื่อคุณบันทึกข้อมูล Luau ใน Studio, Roblox จะใช้กระบวนการที่เรียกว่า serialization เพื่อแปลงข้อมูลนั้นเป็น JSON เพื่อบันทึกในที่เก็บข้อมูล จากนั้น Roblox จะช่วยแปลงข้อมูลของคุณกลับไปเป็น Luau และส่งคืนให้คุณในกระบวนการอีกอย่างที่เรียกว่า deserialization

การจัดรูปแบบและการแปลงกลับรองรับประเภทข้อมูล Luau ต่อไปนี้:

• Nil
• Boolean
• ตัวเลข

  • คุณไม่ควรเก็บค่าตัวเลขพิเศษ inf, -inf, และ nan, เพราะค่าพวกนี้ไม่ตรงตามมาตรฐาน JSON คุณไม่สามารถเข้าถึงคีย์ที่มีค่าพวกนี้ด้วย Open Cloud ได้
• สตริง
• ตาราง

  • ตารางต้องประกอบด้วยประเภทข้อมูลที่รองรับอื่น ๆ เท่านั้น
  • คีย์ตัวเลขจะถูกแปลงเป็นสตริงหากความยาวของตารางเป็น 0
• Buffers

หากคุณพยายามที่จะจัดเก็บประเภทข้อมูลที่การจัดรูปแบบไม่รองรับ คุณจะ:

• ล้มเหลวในการจัดเก็บประเภทข้อมูลนั้นและได้รับข้อความแสดงข้อผิดพลาด
• ประสบความสำเร็จในการจัดเก็บประเภทข้อมูลนั้นเป็น nil

เพื่อแก้ไขปัญหาว่าทำไมประเภทข้อมูลของคุณจึงถูกเก็บเป็น nil คุณสามารถใช้ฟังก์ชัน JSONEncode เมื่อคุณส่งประเภทข้อมูล Luau ของคุณไปยังฟังก์ชันนี้ คุณจะได้รับมันกลับมาในรูปแบบที่ Roblox จะจัดเก็บมันด้วยที่เก็บข้อมูล ซึ่งจะช่วยให้คุณดูตัวอย่างและตรวจสอบข้อมูลที่ส่งกลับ