ที่เก็บข้อมูล

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

หากคุณต้องการเพิ่มการควบคุมสิทธิ์ที่ละเอียดให้กับที่เก็บข้อมูลของคุณและเข้าถึงจากภายนอก Studio หรือเซิร์ฟเวอร์ Roblox คุณสามารถใช้ Open Cloud APIs สำหรับที่เก็บข้อมูล.

ในการดูและติดตามที่เก็บข้อมูลทั้งหมดในเกมผ่าน Creator Hub ให้ใช้ Data Stores Manager.

สำหรับข้อมูลชั่วคราวที่คุณต้องการอัปเดตหรือเข้าถึงบ่อย ๆ ให้ใช้ memory stores.

เปิดใช้งานการเข้าถึง Studio

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

ในการเปิดใช้งานการเข้าถึง Studio ในเกมที่ เผยแพร่:

1. เปิดหน้าต่าง File ⟩ Experience Settings ของ Studio
2. ไปที่ Security
3. เปิดใช้งานสวิตช์ Enable Studio Access to API Services
4. คลิก Save

เข้าถึงที่เก็บข้อมูล

ในการเข้าถึงที่เก็บข้อมูลภายในเกม:

1. เพิ่ม DataStoreService ลงใน Script ฝั่งเซิร์ฟเวอร์
2. ใช้ฟังก์ชัน GetDataStore() และระบุชื่อของที่เก็บข้อมูลที่คุณต้องการใช้ หากที่เก็บข้อมูลไม่มีอยู่ Studio จะสร้างขึ้นเมื่อคุณบันทึกข้อมูลเกมของคุณเป็นครั้งแรก

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

สร้างข้อมูล

ที่เก็บข้อมูลเป็นเหมือนพจนานุกรม ซึ่งคล้ายกับตาราง Luau คีย์ key ที่ไม่ซ้ำกันจะทำการจัดทำดัชนีแต่ละค่าในที่เก็บข้อมูล เช่น Player.UserId ที่ไม่ซ้ำกันของผู้ใช้หรือสตริงที่ตั้งชื่อสำหรับโปรโมชั่นเกม

ในการสร้างรายการใหม่ ให้เรียกใช้ SetAsync() พร้อมกับชื่อคีย์และค่า

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, errorMessage = pcall(function()
	gameStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

อัปเดตข้อมูล

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

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("Uppercase Name:", updatedName)
end

ตั้งค่า vs อัปเดต

ใช้ set เพื่ออัปเดตคีย์เฉพาะอย่างรวดเร็ว ฟังก์ชัน SetAsync():

• อาจทำให้ข้อมูลไม่สอดคล้องกันหากเซิร์ฟเวอร์สองตัวพยายามตั้งค่าคีย์เดียวกันในเวลาเดียวกัน
• นับเฉพาะการเขียนเท่านั้น

ใช้ update เพื่อจัดการกับการพยายามจากหลายเซิร์ฟเวอร์ ฟังก์ชัน UpdateAsync():

• อ่านค่าคีย์ปัจจุบันจากเซิร์ฟเวอร์ที่อัปเดตล่าสุดก่อนที่จะทำการเปลี่ยนแปลงใด ๆ
• ช้ากว่าเพราะมันอ่านก่อนที่จะเขียน
• นับทั้งการอ่านและการเขียน

อ่านข้อมูล

ในการอ่านค่าของรายการที่เก็บข้อมูล ให้เรียกใช้ GetAsync() พร้อมกับชื่อคีย์ของรายการ

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, currentGame = pcall(function()
	return gameStore:GetAsync("User_1234")
end)
if success then
	print(currentGame)
end

เพิ่มข้อมูล

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

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, newGame = pcall(function()
	return gameStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newGame)
end

ลบข้อมูล

ในการลบรายการและส่งคืนค่าที่เกี่ยวข้องกับคีย์ ให้เรียกใช้ RemoveAsync()

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

เมตาดาต้า

มีเมตาดาต้าสองประเภทที่เกี่ยวข้องกับคีย์:

• บริการกำหนด: เมตาดาต้าพื้นฐานที่อ่านได้เท่านั้น เช่น เวลาที่อัปเดตล่าสุดและเวลาที่สร้าง ทุกวัตถุมีเมตาดาต้าที่บริการกำหนด
• ผู้ใช้กำหนด: เมตาดาต้าที่กำหนดเองสำหรับการติดแท็กและการจัดหมวดหมู่ กำหนดโดยใช้วัตถุ DataStoreSetOptions และฟังก์ชัน SetMetadata()

ในการจัดการเมตาดาต้า ขยายฟังก์ชัน SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync(), และ RemoveAsync()

• SetAsync() รับพารามิเตอร์ที่สามและสี่ที่ไม่บังคับ:

  • ตารางของ UserIds ซึ่งสามารถช่วยในการติดตามและลบลิขสิทธิ์เนื้อหาและทรัพย์สินทางปัญญา

  • วัตถุ DataStoreSetOptions ซึ่งคุณสามารถกำหนดเมตาดาต้าที่กำหนดเองโดยใช้ฟังก์ชัน SetMetadata()

    local DataStoreService = game:GetService("DataStoreService")
    
    local gameStore = DataStoreService:GetDataStore("PlayerGame")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["GameElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        gameStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync(), IncrementAsync(), และ RemoveAsync() จะส่งคืนค่าที่สองในวัตถุ DataStoreKeyInfo ค่าที่สองนี้ประกอบด้วยคุณสมบัติที่บริการกำหนดและฟังก์ชันในการดึงเมตาดาต้าที่ผู้ใช้กำหนด

  • ฟังก์ชัน GetUserIds() ดึงตารางของ UserIds ที่คุณส่งไปยัง SetAsync()
  • ฟังก์ชัน GetMetadata() ดึงเมตาดาต้าที่ผู้ใช้กำหนดซึ่งคุณส่งไปยัง SetAsync() ผ่าน SetMetadata()
  • คุณสมบัติ Version ดึงเวอร์ชันของคีย์
  • คุณสมบัติ CreatedTime ดึงเวลาที่คีย์ถูกสร้าง โดยจัดรูปแบบเป็นจำนวนมิลลิวินาทีตั้งแต่ยุค
  • คุณสมบัติ UpdatedTime ดึงเวลาที่คีย์ถูกอัปเดตล่าสุด โดยจัดรูปแบบเป็นจำนวนมิลลิวินาทีตั้งแต่ยุค

  local DataStoreService = game:GetService("DataStoreService")
  
  local gameStore = DataStoreService:GetDataStore("PlayerGame")
  
  local success, currentGame, keyInfo = pcall(function()
      return gameStore:GetAsync("User_1234")
  end)
  if success then
      print(currentGame)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

• ฟังก์ชัน callback ของ UpdateAsync() จะรับพารามิเตอร์เพิ่มเติมในวัตถุ DataStoreKeyInfo ที่อธิบายสถานะปัจจุบันของคีย์ มันจะส่งคืนค่าที่แก้ไขแล้ว คีย์ที่เกี่ยวข้องกับ UserIds และเมตาดาต้าของคีย์

  local DataStoreService = game:GetService("DataStoreService")
  
  local nicknameStore = DataStoreService:GetDataStore("Nicknames")
  
  local function makeNameUpper(currentName, keyInfo)
      local nameUpper = string.upper(currentName)
      local userIDs = keyInfo:GetUserIds()
      local metadata = keyInfo:GetMetadata()
      return nameUpper, userIDs, metadata
  end
  
  local success, updatedName, keyInfo = pcall(function()
      return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
  end)
  if success then
      print(updatedName)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

สำหรับขีดจำกัดเมื่อกำหนดเมตาดาต้า โปรดดูที่ ขีดจำกัดเมตาดาต้า.

ที่เก็บข้อมูลที่เรียงลำดับ

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

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

ที่เก็บข้อมูลที่เรียงลำดับสนับสนุนฟังก์ชันพื้นฐานเดียวกันกับที่เก็บข้อมูลเริ่มต้น รวมถึงฟังก์ชันเฉพาะ GetSortedAsync() ซึ่งดึง คีย์ที่เรียงลำดับหลายรายการ ตามลำดับการจัดเรียงเฉพาะ ขนาดหน้า และค่าต่ำสุด/สูงสุด

ตัวอย่างต่อไปนี้จัดเรียงข้อมูลตัวละครเป็นหน้าโดยมีสามรายการในแต่ละหน้า โดยเรียงจากมากไปน้อย จากนั้นวนรอบหน้าต่างและแสดงชื่อและอายุของตัวละครแต่ละตัว

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- ป้อนข้อมูลที่เก็บข้อมูลที่เรียงลำดับ
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- จัดเรียงข้อมูลตามลำดับจากมากไปน้อยเป็นหน้าโดยมีสามรายการในแต่ละหน้า
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- ดึงหน้าปัจจุบัน (หน้าแรก)
		local entries = pages:GetCurrentPage()
		-- วนรอบคู่คีย์-ค่าในหน้า
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- ตรวจสอบว่าถึงหน้าสุดท้ายแล้วหรือไม่
		if pages.IsFinished then
			break
		else
			print("----------")
			-- ไปยังหน้าถัดไป
			pages:AdvanceToNextPageAsync()
		end
	end
end

อ่านหลายรายการ

ในการอ่านหลายรายการจาก ที่เก็บข้อมูลที่เรียงลำดับ ในคำขอเดียว ให้เรียกใช้ BatchGetAsync() พร้อมกับอาร์เรย์ของคีย์ นี่คือฟังก์ชันแบบกลุ่มที่ตรงกันกับการอ่านรายการทีละรายการด้วย GetAsync()

BatchGetAsync() จะส่งคืนพจนานุกรมที่แมพแต่ละคีย์ที่ร้องขอไปยังตารางที่มีฟิลด์ value คีย์ที่ไม่มีอยู่จะถูกละเว้นจากพจนานุกรม ดังนั้นให้ยืนยันว่าคีย์มีอยู่ก่อนที่จะอ่านค่าของมัน

แต่ละคีย์ที่คุณร้องขอนับเป็นหนึ่งคำขออ่าน ดังนั้นการเรียกครั้งเดียวสำหรับคีย์ N จะนับเป็น N คำขอที่เกี่ยวข้องกับ ขีดจำกัดการอ่าน ของที่เก็บข้อมูลที่เรียงลำดับ

ตัวอย่างต่อไปนี้อ่านคะแนนผู้เล่นสามคะแนนในคำขอเดียว จากนั้นวนรอบคีย์และแสดงคะแนนที่มีอยู่แต่ละคะแนน

local DataStoreService = game:GetService("DataStoreService")

local playerScores = DataStoreService:GetOrderedDataStore("PlayerScores")
local keys = {"Player_123", "Player_456", "Player_789"}

local success, results = pcall(function()
	return playerScores:BatchGetAsync(keys)
end)
if success then
	for _, key in keys do
		local entry = results[key]
		if entry then
			print(key .. " : " .. tostring(entry.value))
		else
			print(key .. " ไม่มีรายการที่บันทึกไว้")
		end
	end
end