Magazyny danych

The DataStoreService pozwala przechowywać dane, które muszą istnieć między sesjami, takie jak przedmioty w ekwipunku gracza lub punkty umiejętności.Magazyny danych są spójne w każdym doświadczeniu, więc każde miejsce w doświadczeniu może uzyskać dostęp i zmienić te same dane, w tym miejsca na różnych serwerach.

Jeśli chcesz dodać granularną kontrolę dostępu do swoich magazynów danych i uzyskać do nich dostęp poza serwerami Studio lub Roblox, możesz użyć Otwórz chmurowe API dla magazynów danych.

Aby zobaczyć i monitorować wszystkie magazyny danych w doświadczeniu za pośrednictwem Centrum twórców, użyj Menadżera magazynów danych.

W przypadku tymczasowych danych, które musisz często aktualizować lub uzyskiwać, użyj przechowywania pamięci.

Włącz dostęp do Studio

Domyślnie doświadczenia przetestowane w Studio nie mają dostępu do magazynów danych, więc musisz najpierw je włączyć.Dostęp do magazynów danych w Studio może być niebezpieczny dla doświadczeń na żywo, ponieważ Studio uzyskuje dostęp do tych samych magazynów danych, co aplikacja klienta.Aby uniknąć nadpisania danych produkcyjnych, nie włączaj tej opcji dla doświadczeń na żywo.Zamiast tego włącz ją dla odrębnej wersji testowej doświadczenia.

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

1. Otwórz Ustawienia gry.
2. Nawiguj do Bezpieczeństwa .
3. Włącz przełącznik Włącz dostęp do Studio do usług API .
4. Kliknij Zapisz .

Magazyny danych dostępu

Aby uzyskać dostęp do magazynu danych w środku doświadczenia:

1. Dodaj DataStoreService do strony serwera Script.
2. Użyj funkcji GetDataStore() i określ nazwę magazynu danych, którego chcesz użyć.Jeśli przechowywanie danych nie istnieje, Studio tworzy go po raz pierwszy, gdy zapisujesz dane doświadczenia.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Twórz dane

Magazyn danych jest zasadniczo słownikiem, podobnym do tabeli Luau.Unikalny indeks klucza oznacza każdą wartość w sklepdanych, tak jak unikalny Player.UserId użytkownika lub nazwana struna dla promocji doświadczenia.

Aby utworzyć nową pozycję, wezwij 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

Aktualizuj dane

Aby zmienić dowolną zapisany wartość w sklepdanych, wezwij UpdateAsync() z nazwą klucza wejścia i funkcją powrotną, która określa, jak chcesz zaktualizować wpis.Ta metoda zwrotna bierze obecną wartość i zwraca nową wartość w oparciu o logikę, którą określasz.Jeśli powrót wezwania zwraca nil, operacja pisania 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

Ustaw vs aktualizacja

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

• Może powodować niezgodność danych, jeśli dwa serwery próbują ustawić ten sam klucz jednocześnie
• Liczy się tylko przeciwko limitowi pisania

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

• Czyta obecną wartość klucza z serwera, który po raz ostatni ją zaktualizował, zanim dokonał jakichkolwiek zmian
• Jest wolniejszy, ponieważ czyta przed zapisaniem
• Liczy przeciwko zarówno ograniczeniom odczytu, jak i pisania

Przeczytaj dane

Aby odczytać wartość wpisu w magazynie danych, wezwij 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

Dane o wzroście

Aby zwiększyć liczbę całkowitą w sklepdanych, wezwij IncrementAsync() z nazwą klucza wejścia i liczbą, jak dużo zmienić wartość.IncrementAsync() to funkcja udogodnienia, która pozwala uniknąć wezwania 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

Usuń dane

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

Opis metadanych

Istnieją dwa rodzaje metadanych związanych z kluczami:

• Definiowane przez usługę : Domyślne metadane do odczytu, takie jak najnowszy czas aktualizacji i czas tworzenia. Każdy obiekt ma metadane definiowane przez usługę.
• Definiowane przez użytkownika : Metadane niestandardowe do oznaczania i kategoryzacji. Określone 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:

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

  • Przedmiot DataStoreSetOptions, w którym możesz określić 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() , i RemoveAsync() zwracają drugą wartość w obiekcie DataStoreKeyInfo.Druga wartość zawiera zarówno właściwości i funkcje 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 użytkownika, które przekazałeś do SetAsync() poprzez SetMetadata().
  • Właściwość Version pobiera wersję klucza.
  • Właściwość CreatedTime pobiera czas, w którym klucz został utworzony, formatowany jako liczba milisekund od czasu epoki.
  • Właściwość UpdatedTime pobiera ostatni raz, kiedy klucz został zaktualizowany, formatowany 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 powrotna UpdateAsync() przyjmuje dodatkowy parametr w obiekcie DataStoreKeyInfo, który opisuje obecny stan klucza.Zwraca zmienioną wartość, klucze związane z UserIds , a także 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 określić limity przy definiowaniu metadanych, zobacz ograniczenia metadanych.

Zamówione magazyny danych

Domyślnie magazyny danych nie sortują swoich treści.Jeśli musisz uzyskać dane w uporządkowany sposób, tak jak w przypadku trwałych statystyk w tabeli liderów, wezwij GetOrderedDataStore() zamiast GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Zamówione magazyny danych wspierają te same podstawowe funkcje, co domyślne magazyny danych, plus unikalną funkcję GetSortedAsync().To odzyskuje kilka sortowanych kluczy w oparciu o określone kolejność sortowania, rozmiar strony i minimalne/maksymalne wartości.

Poniższy przykład sortuje dane postaci na strony z trzema wpisami, każdy w kolejności malejącej, a następnie przesłania się przez strony i wyświetla nazwę i wiek każdej postaci.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Wypełnia uporządkowany sklepdanych
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 według malejącego porządku na stronach trzech wpisów każdy
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Zdobywa bieżącą (pierwszą) stronę
		local entries = pages:GetCurrentPage()
		-- Iteruje przez wszystkie pary kluczowo-wartościowe na stronie
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Sprawdza, czy ostatnia strona została osiągnięta
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Przejścia do następnej strony
			pages:AdvanceToNextPageAsync()
		end
	end
end