데이터 저장소

The DataStoreService 는 플레이어의 인벤토리나 스킬 포인트와 같이 세션 간에 유지되어야 하는 데이터를 저장할 수 있습니다.데이터 저장소는 경험당 일관되므로 경험의 어느 곳이든 서로 다른 서버의 장소를 포함하여 동일한 데이터에 액세스하고 변경할 수 있습니다.

데이터 저장소에 세분화된 권한 제어를 추가하고 Studio 또는 Roblox 서버 외부에서 액세스하려는 경우 Open Cloud APIs for data stores를 사용할 수 있습니다.

크리에이터 허브를 통해 경험의 모든 데이터 저장소를 보고 모니터링하려면 데이터 저장소 관리자를 사용하십시오.

자주 업데이트하거나 액세스해야 하는 임시 데이터는 메모리 저장소를 사용하십시오.

Studio 액세스 활성화

기본적으로 Studio에서 테스트한 경험은 데이터 저장소에 액세스할 수 없으므로 먼저 활성화해야 합니다.Studio에서 데이터 저장소에 액세스하는 것은 라이브 경험에 위험할 수 있으며 이는 Studio가 클라이언트 응용 프로그램과 동일한 데이터 저장소에 액세스하기 때문입니다.프로덕션 데이터를 덮어쓰지 않으려면 라이브 경험에 이 설정을 활성화하지 마십시오.대신 경험의 별도 테스트 버전에 활성화하십시오.

게시된 경험에서 Studio 액세스를 활성화하려면: To enable Studio access in a published experience:

1. 게임 설정을 엽니다.
2. 보안 으로 이동합니다.
3. API 서비스에 대한 Studio 액세스 활성화 토글을 활성화하십시오.
4. 클릭 저장 .

액세스 데이터 저장소

경험 내의 데이터 저장소에 액세스하려면:

1. 서버 측 DataStoreService에 Script에 를 추가합니다.
2. GetDataStore() 함수를 사용하고 사용하려는 데이터 저장소의 이름을 지정하십시오.데이터 저장소가 존재하지 않으면 경험 데이터를 처음 저장할 때 Studio가 자동으로 생성합니다.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

데이터 생성

데이터 저장소는 본질적으로 Luau 테이블과 유사한 사전입니다.고유한 키 인덱스는 데이터 상점사용자의 고유 Player.UserId나 경험 프로모션용 명명된 문자열처럼 각 값을 인덱싱합니다.

새 항목을 생성하려면 키 이름과 값을 사용하여 SetAsync()를 호출하십시오.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

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

데이터 업데이트

데이터 상점저장된 모든 값을 변경하려면 입력의 키 이름과 업데이트할 항목을 정의하는 콜백 함수를 사용하여 UpdateAsync()를 호출하십시오.이 콜백은 현재 값을 가져와 정의한 논리에 따라 새 값을 반환합니다.콜백이 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 업데이트

집합을 사용하여 특정 키를 신속하게 업데이트합니다. SetAsync() 함수:

• 두 서버가 동시에 동일한 키를 설정하려고 하면 데이터 불일치를 일으킬 수 있습니다
• 쓰기 제한에만 계산됩니다

업데이트를 사용하여 다중 서버 시도를 처리합니다. UpdateAsync() 함수:

• 변경하기 전에 서버에서 마지막으로 업데이트한 현재 키 값을 읽습니다
• 쓰기 전에 읽기 때문에 느려집니다
• 읽기 및 쓰기 제한 모두에 대해 계산

데이터 읽기

데이터 저장소 항목의 값을 읽으려면 입력의 키 이름으로 GetAsync()를 호출하십시오.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

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

데이터 증가량

데이터 상점정수를 증가시키려면 입력의 키 이름과 값을 변경할 수량을 사용하여 IncrementAsync()를 호출하십시오. 는 호출하지 않고 정수를 수동으로 증가시키는 것을 피할 수 있는 편의 기능입니다.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, newExperience = pcall(function()
	return experienceStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newExperience)
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 experienceStore = DataStoreService:GetDataStore("PlayerExperience")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["ExperienceElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        experienceStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync() , IncrementAsync() , 그리고 RemoveAsync() 는 DataStoreKeyInfo 개체에서 두 번째 값을 반환합니다.이 두 번째 값에는 사용자 정의 메타데이터를 검색하기 위한 서비스 정의 속성과 함수가 모두 포함되어 있습니다.

  • GetUserIds() 함수는 전달한 테이블 UserIds 을 가져옵니다.The function fetches the table of that you passed to SetAsync().
  • GetMetadata() 함수는 사용자 정의 메타데이터를 검색하여 SetAsync()를 통해 전달하고 SetMetadata()를 통해 검색합니다.
  • Version 속성은 키의 버전을 가져옵니다.
  • CreatedTime 속성은 키가 생성된 시간을 가져와서, 에포크 이후의 밀리초 수로 형식화합니다.
  • UpdatedTime 속성은 키가 마지막으로 업데이트된 시간, 에포크 이후 밀리초 수로 형식화되어 검색합니다.

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

• 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

-- 각 페이지에 3개의 항목으로 내림차순으로 데이터를 정렬합니다
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