Sklepy z danymi

DataStoreService pozwala na przechowywanie danych, które muszą utrzymywać się między sesjami, takich jak przedmioty w ekwipunku gracza lub punkty umiejętności. Sklepy z danymi są spójne w ramach doświadczenia, więc każde miejsce w doświadczeniu może uzyskać dostęp i zmieniać te same dane, w tym miejsca na różnych serwerach.

Jeśli chcesz dodać dokładną kontrolę uprawnień do swoich sklepów z danymi 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 z danymi w doświadczeniu za pośrednictwem Hub Twórcy, użyj Menadżera Sklepów z Danymi.

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

Włącz dostęp do Studio

Domyślnie doświadczenia testowane w Studio nie mogą uzyskiwać dostępu do sklepów z danymi, więc musisz je najpierw włączyć. Uzyskiwanie dostępu do sklepów z danymi w Studio może być niebezpieczne dla działających doświadczeń, ponieważ Studio uzyskuje dostęp do tych samych sklepów z danymi co aplikacja klienta. Aby uniknąć nadpisania danych produkcyjnych, nie włączaj tej opcji dla działających doświadczeń. Zamiast tego włącz ją dla osobnej wersji testowej doświadczenia.

Aby włączyć dostęp do Studio w publikowanym doświadczeniu:

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

Uzyskiwanie dostępu do sklepów z danymi

Aby uzyskać dostęp do sklepu z danymi wewnątrz doświadczenia:

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

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Tworzenie danych

Sklep z danymi to w zasadzie słownik, podobny do tabeli Luau. Unikalny klucz indeksuje każdą wartość w sklepie z danymi, na przykład unikalny Player.UserId użytkownika lub nazwany ciąg dla promocji doświadczenia.

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

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

Aktualizacja danych

Aby zmienić dowolną przechowywaną wartość w sklepie z danymi, wywołaj UpdateAsync() z nazwą klucza wpisu i funkcją zwrotną, która definiuje, jak chcesz zaktualizować ten wpis. Ta funkcja zwrotna przyjmuje bieżącą wartość i zwraca nową wartość w oparciu o zdefiniowaną przez ciebie logikę. 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("Nazwa wielkimi literami:", updatedName)
end

Ustawienie a aktualizacja

Użyj set, aby szybko zaktualizować określony 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 przeciwko limitowi zapisu

Użyj update, aby obsłużyć próby wieloserwerowe. Funkcja UpdateAsync():

• Odczytuje bieżącą wartość klucza z serwera, który ostatnio go zaktualizował przed wprowadzeniem jakichkolwiek zmian
• Jest wolniejsza, ponieważ najpierw odczytuje, a potem zapisuje
• Liczy się zarówno przeciwko limitowi odczytu, jak i zapisu

Odczyt danych

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

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

Inkrementacja danych

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

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

Usunięcie 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 rodzaje 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 etykietowania i kategoryzacji. Zdefiniowane za pomocą obiektu DataStoreSetOptions oraz funkcji SetMetadata().

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

• SetAsync() akceptuje opcjonalne trzeci i czwarty argument:

  • 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 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(), oraz RemoveAsync() zwracają drugą wartość w obiekcie DataStoreKeyInfo. Ta druga wartość zawiera zarówno zdefiniowane przez usługę właściwości, 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 pomocą 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 ostatni czas aktualizacji klucza, sformatowany jako liczba milisekund od epoki.

  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

• Funkcja zwrotna UpdateAsync() przyjmuje dodatkowy parametr w obiekcie DataStoreKeyInfo, który opisuje aktualny 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

Dla limitów podczas definiowania metadanych zapoznaj się z limitami metadanych.

Zamówione sklepy z danymi

Domyślnie sklepy z danymi nie sortują swojej zawartości. Jeśli musisz uzyskać dane w uporządkowany sposób, jak w trwałych statystykach tablicy liderów, wywołaj GetOrderedDataStore() zamiast GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Zamówione sklepy z danymi obsługują te same podstawowe funkcje, co domyślne sklepy z danymi, plus unikalną funkcję GetSortedAsync(). Funkcja ta zwraca wiele posortowanych kluczy w oparciu o określoną kolejność sortowania, rozmiar strony i wartości minimalne/maksymalne.

Poniższy przykład sortuje dane postaci w strony z trzema wpisami, każdy w kolejności malejącej, a następnie przechodzi przez strony i wypisuje imię i wiek każdej postaci.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Wypełnia zamówiony sklep z danymi
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 kolejności malejącej na strony z trzema wpisami każda
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Odczytuje 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