Sklepy danych

DataStoreService pozwala na przechowywanie danych, które muszą być trwałe między sesjami, takich jak przedmioty w ekwipunku gracza lub punkty umiejętności. Sklepy danych są spójne w ramach gry, więc każde miejsce w grze może uzyskać dostęp do tych samych danych i je zmieniać, w tym miejsca na różnych serwerach.

Jeśli chcesz dodać szczegółową kontrolę uprawnień do swoich sklepów danych i uzyskać do nich dostęp poza Studio lub serwerami Roblox, możesz użyć Open Cloud APIs for data stores.

Aby wyświetlić i monitorować wszystkie sklepy danych w grze przez Hub twórcy, użyj Menadżera Sklepów Danych.

Do tymczasowych danych, które musisz często aktualizować lub uzyskiwać do nich dostęp, użyj pamięci podręcznych.

Włącz dostęp do Studio

Domyślnie gry testowane w Studio nie mogą uzyskiwać dostępu do sklepów danych, więc musisz najpierw je włączyć. Uzyskiwanie dostępu do sklepów danych w Studio może być niebezpieczne dla gier na żywo, ponieważ Studio uzyskuje dostęp do tych samych sklepów danych co aplikacja kliencka. Aby uniknąć nadpisania danych produkcyjnych, nie włączaj tej opcji dla gier na żywo. Zamiast tego włącz ją dla oddzielnej wersji testowej gry.

Aby włączyć dostęp do Studio w grze opublikowanej:

1. Otwórz okno Plik ⟩ Ustawienia doświadczenia w Studio.
2. Przejdź do Bezpieczeństwo.
3. Włącz przełącznik Włącz dostęp Studio do usług API.
4. Kliknij Zapisz.

Uzyskaj dostęp do sklepów danych

Aby uzyskać dostęp do sklepu danych w grze:

1. Dodaj DataStoreService do skryptu po stronie serwera Script.
2. Użyj funkcji GetDataStore() i określ nazwę sklepu danych, którego chcesz użyć. Jeśli sklep danych nie istnieje, Studio tworzy go, gdy po raz pierwszy zapiszesz dane gry.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Tworzenie danych

Sklep danych jest zasadniczo słownikiem, podobnym do tabeli Luau. Unikalny klucz indeksuje każdą wartość w sklepie danych, na przykład unikalny Player.UserId użytkownika lub nazwany ciąg dla promocji gry.

Aby utworzyć nowy wpis, wywołaj SetAsync() z nazwą klucza i wartością.

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

Aktualizacja danych

Aby zmienić dowolną przechowywaną wartość w sklepie danych, wywołaj UpdateAsync() z nazwą klucza wpisu i funkcją zwrotną, która definiuje, jak chcesz zaktualizować wpis. Ta funkcja zwrotna przyjmuje bieżącą wartość i zwraca nową wartość na podstawie zdefiniowanej logiki. Jeśli funkcja zwrotna zwraca nil, operacja zapisu jest anulowana, a wartość nie jest aktualizowana.

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

Ustawianie vs aktualizacja

Użyj ustawienia, aby szybko zaktualizować konkretny klucz. Funkcja SetAsync():

• Może powodować niespójność danych, jeśli dwa serwery próbują ustawić ten sam klucz w tym samym czasie
• Liczy się tylko w ramach limitu zapisu

Użyj aktualizacji, aby obsłużyć próby z wielu serwerów. Funkcja UpdateAsync():

• Odczytuje bieżącą wartość klucza z serwera, który ostatnio go zaktualizował, przed dokonaniem jakichkolwiek zmian
• Jest wolniejsza, ponieważ odczytuje przed zapisem
• Liczy się zarówno w ramach limitu odczytu, jak i zapisu

Odczyt danych

Aby odczytać wartość wpisu w sklepie danych, wywołaj GetAsync() z nazwą klucza wpisu.

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

Inkrementacja danych

Aby zwiększyć liczbę całkowitą w sklepie danych, wywołaj IncrementAsync() z nazwą klucza wpisu i liczbą, o którą chcesz zmienić wartość. IncrementAsync() to funkcja pomocnicza, która pozwala uniknąć wywoływania UpdateAsync() i ręcznego zwiększania liczby.

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

Usuwanie danych

Aby usunąć wpis i zwrócić wartość związaną z kluczem, wywołaj 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

Metadane

Istnieją dwa typy metadanych związanych z kluczami:

• Zdefiniowane przez usługę: Domyślne metadane tylko do odczytu, takie jak czas ostatniej aktualizacji i czas utworzenia. Każdy obiekt ma metadane zdefiniowane przez usługę.
• Zdefiniowane przez użytkownika: Niestandardowe metadane do tagowania i kategoryzacji. Zdefiniowane za pomocą obiektu DataStoreSetOptions i funkcji SetMetadata().

Aby zarządzać metadanymi, rozszerz funkcje SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync(), i RemoveAsync().

• SetAsync() akceptuje opcjonalne trzecie i czwarte argumenty:

  • Tabelę UserIds. Może to pomóc w śledzeniu i usuwaniu praw autorskich do treści i własności intelektualnej.

  • Obiekt DataStoreSetOptions, w którym możesz zdefiniować niestandardowe metadane za pomocą funkcji 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(), i RemoveAsync() zwracają drugą wartość w obiekcie DataStoreKeyInfo. Ta druga wartość zawiera zarówno właściwości zdefiniowane przez usługę, jak i funkcje do pobierania metadanych zdefiniowanych przez użytkownika.

  • Funkcja GetUserIds() pobiera tabelę UserIds, którą przekazałeś do SetAsync().
  • Funkcja GetMetadata() pobiera metadane zdefiniowane przez użytkownika, które przekazałeś do SetAsync() za pośrednictwem SetMetadata().
  • Właściwość Version pobiera wersję klucza.
  • Właściwość CreatedTime pobiera czas utworzenia klucza, sformatowany jako liczba milisekund od epoki.
  • Właściwość UpdatedTime pobiera czas ostatniej aktualizacji klucza, sformatowany jako liczba milisekund od epoki.

  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

• Funkcja zwrotna UpdateAsync() przyjmuje dodatkowy parametr w obiekcie DataStoreKeyInfo, który opisuje bieżący stan klucza. Zwraca zmodyfikowaną wartość, klucze związane z UserIds oraz metadane klucza.

  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

Aby uzyskać limity przy definiowaniu metadanych, zobacz limity metadanych.

Zamówione sklepy danych

Domyślnie sklepy danych nie sortują swojej zawartości. Jeśli potrzebujesz uzyskać dane w uporządkowany sposób, na przykład w trwałych statystykach liderów, wywołaj GetOrderedDataStore() zamiast GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Zamówione sklepy danych obsługują te same podstawowe funkcje co domyślne sklepy danych, plus unikalną funkcję GetSortedAsync(). Ta funkcja pobiera wiele posortowanych kluczy na podstawie określonego porządku sortowania, rozmiaru strony oraz wartości minimalnych/maksymalnych.

Poniższy przykład sortuje dane postaci na strony z trzema wpisami, każdy w porządku malejącym, a następnie przechodzi przez strony i wyświetla imię i wiek każdej postaci.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Wypełnia zamówiony sklep danych
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

-- Sortuje dane w porządku malejącym na strony z trzema wpisami każda
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Pobiera bieżącą (pierwszą) stronę
		local entries = pages:GetCurrentPage()
		-- Iteruje przez wszystkie pary klucz-wartość na stronie
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Sprawdza, czy osiągnięto ostatnią stronę
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Przechodzi do następnej strony
			pages:AdvanceToNextPageAsync()
		end
	end
end

Odczyt wielu wpisów

Aby odczytać wiele wpisów zamówionego sklepu danych w jednym żądaniu, wywołaj BatchGetAsync() z tablicą kluczy. To jest odpowiednik wsadowy odczytywania wpisów jeden po drugim za pomocą GetAsync().

BatchGetAsync() zwraca słownik, który mapuje każdy żądany klucz do tabeli z polem value. Klucze, które nie istnieją, są pomijane w słowniku, więc upewnij się, że klucz jest obecny przed odczytaniem jego wartości.

Każdy klucz, o który prosisz, liczy się jako jedno żądanie odczytu, więc pojedyncze wywołanie dla N kluczy liczy się jako N żądań w ramach limitu odczytu zamówionego sklepu danych limit odczytu.

Poniższy przykład odczytuje trzy wyniki graczy w jednym żądaniu, a następnie przechodzi przez klucze i wyświetla każdy wynik, który istnieje.

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 .. " nie ma zapisanego wpisu")
		end
	end
end