GlobalDataStore
*Ta zawartość została przetłumaczona przy użyciu narzędzi AI (w wersji beta) i może zawierać błędy. Aby wyświetlić tę stronę w języku angielskim, kliknij tutaj.
A Globalny sklep danych ujawnia funkcje do zapisywania i ładowania danych dla DataStoreService.
Zobacz Magazyny danych dla szczegółowego przewodnika na temat struktury danych, zarządzania, obsługi błędów itp.
Sortowane magazyny danych nie wspierają wersjonowania i metadanych, więc DataStoreKeyInfo zawsze jest nil dla kluczy w OrderedDataStore .Jeśli potrzebujesz wsparcia wersjonowania i metadanych, użyj DataStore.
Podsumowanie
Metody
Zwraca wartość klucza w określonym magazynie danych i instancji DataStoreKeyInfo.
- IncrementAsync(key : string,delta : number,userIds : Array,options : DataStoreIncrementOptions):Variant
Zwiększa wartość klucza o podany wynik (oba muszą być liczbami całkowitymi).
Usuwa określony klucz, zachowując jednocześnie dostępną wersję.
Ustawia wartość magazynu danych dla podanego klucza.
Aktualizuje wartość klucza za pomocą nowej wartości z określonej funkcji powrotnej.
Właściwości
Metody
GetAsync
Funkcja ta zwraca najnowszą wartość dostarczonego klucza i instancjaDataStoreKeyInfo.Jeśli klucz nie istnieje lub najnowsza wersja została oznaczona jako usunięta, obie wartości zwracane będą nil .
Klucze są przechowywane lokalnie przez 4 sekund po pierwszym przeczytane.Wezwanie GlobalDataStore:GetAsync() w ciągu tych 4 sekund zwraca wartość z cache.Modyfikacje klucza przez GlobalDataStore:SetAsync() lub GlobalDataStore:UpdateAsync() mają zastosowanie do pamięci buforowej natychmiast i ponowne uruchomienie czasomierza 4 sekund.
Aby uzyskać określoną wersję, taką jak wersja przed najnowszą, użyj DataStore:GetVersionAsync().
Parametry
Nazwa klucza, dla której wartość jest żądana.Jeśli DataStoreOptions.AllScopes został ustawiony na prawdę przy uzyskiwaniu przechowywania danych za pośrednictwem DataStoreService:GetDataStore() , nazwa klucza musi być dodana z oryginalnym zakresem, jak w "scope/key".
Zwroty
Wartość wpisu w magazynie danych z danym kluczem i instancją DataStoreKeyInfo, która zawiera numer wersji, datę i czas, w którym wersja została utworzona, oraz funkcje do odzyskania UserIds i metadanych.
IncrementAsync
Funkcja ta zwiększa wartość klucza o podany wynik (obie muszą być liczbami całkowitymi).
Wartości w GlobalDataStores są zarchiwizowane zgodnie z opisanym w wersjonowaniu .OrderedDataStores nie wspiera wersjonowania, więc wezwanie tej metody na kluczu sklepu danych zamówionego nie zastąpi obecną wartość z zwiększoną wartością i uniemożliwi dostęp do poprzednich wersji.
Parametry
Nazwa klucza, dla której wartość powinna zostać zaktualizowana.Jeśli DataStoreOptions.AllScopes został ustawiony na prawdę przy uzyskiwaniu przechowywania danych za pośrednictwem DataStoreService:GetDataStore() , nazwa klucza musi być dodana z oryginalnym zakresem, jak w "scope/key".
Ilość, przez którą ma zostać zwiększona obecna wartość.
(Opcjonalnie) instancja, która łączy wiele dodatkowych parametrów jako niestandardowe metadane i pozwala na przyszłą rozszerzalność.
Zwroty
Zaktualizowana wartość wpisu w magazynie danych z danym kluczem.
RemoveAsync
Funkcja ta oznacza określony klucz jako usunięty poprzez utworzenie nowej wersji "grobowca" klucza.Przed tym zwraca najnowszą wersję przed usunięciem wezwania.
Po usunięciu klucza za pomocą tej funkcji GlobalDataStore:GetAsync() wezwania dla klucza powrócą nil.Starsze wersje klucza pozostają dostępne za pośrednictwem DataStore:ListVersionsAsync() i DataStore:GetVersionAsync(), zakładając, że nie wygasły.
OrderedDataStore nie wspiera wersjonowania, więc wezwanie RemoveAsync() na kluczu OrderedDataStore usunie go na stałe.
Usuwane obiekty zostaną usunięte na stałe po 30 dniach.
Jeśli poprzednie wartości zostały już usunięte za pomocą GlobalDataStore:RemoveAsync() lub DataStore:RemoveVersionAsync() , funkcja zwróci odpowiednio nil , nil i DataStoreKeyInfo .
Parametry
Nazwa klucza do usunięcia.Jeśli DataStoreOptions.AllScopes został ustawiony na prawdę przy uzyskiwaniu przechowywania danych za pośrednictwem DataStoreService:GetDataStore() , nazwa klucza musi być dodana z oryginalnym zakresem, jak w "scope/key".
Zwroty
Wartość magazynu danych przed usunięciem i instancja DataStoreKeyInfo, która zawiera numer wersji, datę i czas, w którym wersja została utworzona, oraz funkcje do odzyskania UserIds i metadanych.
SetAsync
Funkcja ta ustawia najnowszą wartość, UserIds , oraz metadane dla danego klucza.
Wartości w GlobalDataStores są zarchiwizowane zgodnie z opisanym w wersjonowaniu .OrderedDataStores nie wspiera wersjonowania, więc wezwanie tej metody na kluczu przeznaczonym do przechowywania danych spowoduje nadpisanie obecnej wartości i uniemożliwi dostęp do poprzednich wersji.
Definicje metadanych muszą być zawsze aktualizowane wartością, nawet jeśli nie ma zmian w obecnej wartości; w przeciwnym razie obecna wartość zostanie utracona.
Każda struna przechowywana w magazynie danych musi być ważna UTF-8 .W UTF-8 wartości większe niż 127 są wykorzystywane wyłącznie do kodowania wielobajtowych punktów kodu, więc pojedynczy bajt większy niż 127 nie będzie ważny w UTF-8, a próba GlobalDataStore:SetAsync() nie powiedzie się.
Ustawienie vs. Aktualizacja
GlobalDataStore:SetAsync() jest najlepszy do szybkiej aktualizacji określonego klucza i liczy się tylko przeciwko ograniczeniu pisania.Może to jednak spowodować niezgodność danych, jeśli dwa serwery próbują ustawić ten sam klucz w tym samym czasie.GlobalDataStore:UpdateAsync() jest bezpieczniejszy do obsługi wieloseryjnych prób, ponieważ odczytuje obecną wartość klucza (z dowolnego serwera, który ostatnio został zaktualizowany) przed wprowadzeniem jakichkolwiek zmian.Jednak jest nieco wolniejszy, ponieważ czyta przed pisaniem, a także liczy się przeciwko zarówno ograniczeniu odczytu, jak i pisania.
Parametry
Nazwa klucza, dla której wartość powinna zostać ustawiać.Jeśli DataStoreOptions.AllScopes został ustawiony na prawdę przy uzyskiwaniu przechowywania danych za pośrednictwem DataStoreService:GetDataStore() , nazwa klucza musi być dodana z oryginalnym zakresem, jak w "scope/key".
Wartość, do której zostanie ustawiony klucz przechowywania danych.
Tabela UserIds, bardzo zalecana do pomocy w śledzeniu/usuwaniu GDPR.
(Opcjonalnie) instancja, która pozwala na określenie metadanych na kluczu.
Zwroty
Identyfikator wersji nowo utworzonej wersji. Można go użyć do odzyskania kluczowych informacji za pomocą GetVersionAsync() lub usunąć za pomocą RemoveVersionAsync().
UpdateAsync
Funkcja ta odzyskuje wartość i metadane klucza z magazynu danych i aktualizuje go za pomocą nowej wartości określonej przez funkcję powrotną określoną za pomocą drugiego parametru.Jeśli powrót wezwania zwraca nil, operacja pisania jest anulowana, a wartość pozostaje niezmieniona.
Wartości w GlobalDataStores są zarchiwizowane zgodnie z opisanym w wersjonowaniu .OrderedDataStores nie wspiera wersjonowania, więc wezwanie tej metody na kluczu przeznaczonym do przechowywania danych spowoduje nadpisanie obecnej wartości i uniemożliwi dostęp do poprzednich wersji.
W przypadkach, gdy inny serwer gier zaktualizował klucz w krótkim okresie czasu między odzyskaniem obecnej wartości klucza a ustawieniem wartości klucza, GlobalDataStore:UpdateAsync() wezwie funkcję ponownie, odrzucając wynik poprzedniego wezwania.Funkcja zostanie wywołana tak wiele razy, jak to konieczne, aż dane zostaną zapisane lub aż funkcja powrotna zwróci nil .Można tego użyć, aby upewnić się, że żadne dane nie zostaną nadpisane.
Każda struna przechowywana w magazynie danych musi być ważna UTF-8 .W UTF-8 wartości większe niż 127 są wykorzystywane wyłącznie do kodowania wielobajtowych punktów kodu, więc pojedynczy bajt większy niż 127 nie będzie ważny w UTF-8, a próba GlobalDataStore:UpdateAsync() nie powiedzie się.
Ustawienie vs. Aktualizacja
GlobalDataStore:SetAsync() jest najlepszy do szybkiej aktualizacji określonego klucza i liczy się tylko przeciwko ograniczeniu pisania.Może to jednak spowodować niezgodność danych, jeśli dwa serwery próbują ustawić ten sam klucz w tym samym czasie.GlobalDataStore:UpdateAsync() jest bezpieczniejszy do obsługi wieloseryjnych prób, ponieważ odczytuje obecną wartość klucza (z dowolnego serwera, który ostatnio został zaktualizowany) przed wprowadzeniem jakichkolwiek zmian.Jednak jest nieco wolniejszy, ponieważ czyta przed pisaniem, a także liczy się przeciwko zarówno ograniczeniu odczytu, jak i pisania.
Funkcja powrotu
Funkcja powrotna akceptuje dwa argumenty:
- Obecna wartość klucza przed aktualizacja.
- DataStoreKeyInfo instancja, która zawiera najnowsze informacje o wersji (ten argument może zostać pominięty, jeśli nie są używane metadane).
Z kolei funkcja powrotna zwraca do trzech wartości:
- Nowa wartość do ustawienia dla klucza.
- Zbiór UserIds do powiązania z kluczemDataStoreKeyInfo:GetUserIds() powinny zostać zwrócone, chyba że istniejące ID są zmieniane; w przeciwnym razie wszystkie istniejące ID zostaną wyczyszczone.
- Tabela Luau zawierająca metadane do powiązania z kluczem.DataStoreKeyInfo:GetMetadata() powinno zostać zwrócone, chyba że istniejące metadane zostaną zmienione; w przeciwnym razie wszystkie istniejące metadane zostaną wyczyszczone.
Jeśli zamiast tego powrót do wezwania zwraca nil, obecny serwer przestanie próbować aktualizować klucz.
Funkcja powrotna nie może zwrócić, więc nie dodawaj nie wezwania takich jak task.wait().
Parametry
Nazwa klucza, dla której wartość powinna zostać zaktualizowana.Jeśli DataStoreOptions.AllScopes został ustawiony na prawdę przy uzyskiwaniu przechowywania danych za pośrednictwem DataStoreService:GetDataStore() , nazwa klucza musi być dodana z oryginalnym zakresem, jak w "scope/key".
Transformuj funkcję, która bierze obecną wartość i DataStoreKeyInfo jako parametry i zwraca nową wartość wraz z opcjonalnym UserIds i metadanymi.
Zwroty
Zaktualizowana wartość wpisu w magazynie danych z danym kluczem i instancją DataStoreKeyInfo, która zawiera numer wersji, datę i czas, w którym wersja została utworzona, oraz funkcje do odzyskania UserIds i metadanych.