GlobalDataStore

顯示已棄用項目

*此內容是使用 AI(Beta 測試版)翻譯,可能含有錯誤。若要以英文檢視此頁面,請按一下這裡

無法建立
未複製

一個 全球數據儲存庫 暴露功能來保存和載入資料給 DataStoreService

參見數據儲存以獲得關於數據結構、管理、錯誤處理等方面的詳細指南

排序的數據儲存不支持版本和元數據,因此 DataStoreKeyInfo 永遠是 nil 對於 OrderedDataStore 中的鑰匙。如需版本控制和元數據協助,請使用 DataStore

概要

方法

屬性

方法

GetAsync

暫停

此功能返回提供的鑰匙的最新值和 DataStoreKeyInfo 個實個體、實例。如果鑰匙不存在或最新版本被標記為刪除,兩個返回值都會是 nil

鑰匙在第一次閱已讀後的 4 秒內本地緩存。在這些 4 秒內的一個 GlobalDataStore:GetAsync() 呼叫會從緩存中返回值。由 GlobalDataStore:SetAsync()GlobalDataStore:UpdateAsync() 修改鑰匙將立即適用於緩存並重新啟動 4 秒計時器。

若要獲得特定版本,例如最新版本之前的版本,請使用 DataStore:GetVersionAsync()

參數

key: string

值被要求的鑰匙名稱。如果 DataStoreOptions.AllScopes 在通過 DataStoreService:GetDataStore() 存取資料儲存時設為真實,此鍵名必須與原始範圍一樣在 "scope/key" 中加以前缀。

預設值:""
預設值:"nil"

返回

具有給定鑰匙和包含版本號、日期和時間的版本被創建的功能的數據存儲中的入口值,與包含版本號、日期和時間的版本被創建的功能的 實例。

IncrementAsync

Variant
暫停

此功能會將鑰匙的值增加所提供的數量(兩者都必須是整數)。

GlobalDataStores 中的值被視為 版本化 ,如同在 版本化 中所述。OrderedDataStores 不支持版本控制,因此在訂購的數據儲存鑰匙上呼叫此方法會覆蓋當前值以增量值,使以前版本無法使用。

參數

key: string

值應更新的鑰匙名稱。如果 DataStoreOptions.AllScopes 在通過 DataStoreService:GetDataStore() 存取資料儲存時設為真實,此鍵名必須與原始範圍一樣在 "scope/key" 中加以前缀。

預設值:""
delta: number

用於增加目前值的數量。

預設值:1
userIds: Array

(可選) 一個表的 UserIds 與鍵匙相關。

預設值:"{}"

(可選) 結合多個額外參數作為自定義元數據,並允許未來擴展的實例。

預設值:"nil"

返回

Variant

指定鑰匙的數據儲存中入口的更新值。

RemoveAsync

暫停

此功能標記指定的鑰匙為刪除新版本的「墓碑」鑰鍵所刪除。在此之前,它返回移除呼叫之前的最新版本。

通過此函數移除鑰匙後,GlobalDataStore:GetAsync() 呼叫鑰匙將返回nil。較舊版本的鑰匙仍然可以通過 DataStore:ListVersionsAsync()DataStore:GetVersionAsync() 存取,假設它們未過期。

OrderedDataStore 不支持版本控制,因此呼叫 RemoveAsync()OrderedDataStore 鍵上會永久刪除它。

移除的對象將在 30 天後永久刪除。

如果以前的值已經通過 GlobalDataStore:RemoveAsync()DataStore:RemoveVersionAsync() 被刪除,那麼函數將返回 nilnilDataStoreKeyInfo 分別對應值和值。

參數

key: string

要移除的鑰匙名稱。如果 DataStoreOptions.AllScopes 在通過 DataStoreService:GetDataStore() 存取資料儲存時設為真實,此鍵名必須與原始範圍一樣在 "scope/key" 中加以前缀。

預設值:""

返回

刪除前資料儲存的值和包含版本號、創建日期和時間的DataStoreKeyInfo實例,以及用於取回UserIds和元數據的功能。

SetAsync

Variant
暫停

此功能設置最新值、UserIds,以及給定鑰鍵的元數據。

GlobalDataStores 中的值被視為 版本化 ,如同在 版本化 中所述。OrderedDataStores 不支持版本控制,因此在訂購的數據儲存鑰匙上呼叫此方法會覆蓋當前值並使以前版本無法使用。

元數據定義必須始終以值更新,即使沒有更改現有值;否則現有值將丟失。

任何被儲存在數據存儲中的字串必須有效 UTF-8 .在 UTF-8 中,超過 127 的值僅用於編碼多個字元代碼點,因此單一超過 127 的字元不會是有效的 UTF-8,且 GlobalDataStore:SetAsync() 嘗試將失敗。

設定與更新

GlobalDataStore:SetAsync() 最適合快速更新特定鍵,只會對寫入限制進行計數。然而,如果兩個伺服器在同一時間嘗試設置相同的鑰匙,可能會導致數據不一致。GlobalDataStore:UpdateAsync() 更安全地處理多個伺服器的嘗試,因為它在進行任何變更之前會閱讀當前的鑰匙值 (從最後更新的伺服器),以便確保沒有問題。但是,它的速度有點慢,因為它先讀再寫,它也會對閱讀和寫入限制進行計數。

參數

key: string

值應設定為的鑰匙名稱。如果 DataStoreOptions.AllScopes 在通過 DataStoreService:GetDataStore() 存取資料儲存時設為真實,此鍵名必須與原始範圍一樣在 "scope/key" 中加以前缀。

預設值:""
value: Variant

數據儲存鑰匙將設為的值。

預設值:""
userIds: Array

表的 UserIds , 高度建議幫助進行GDPR追蹤/移除。

預設值:"{}"

(可選) DataStoreSetOptions 允許在鍵匙上指定元數據規格的實例

預設值:"nil"

返回

Variant

新建版本的版本標識符。可以使用 GetVersionAsync() 來恢復關鍵信息,或使用 RemoveVersionAsync() 來移除它。

UpdateAsync

暫停

此功能從數據存儲中恢復鑰匙的值和元數據,並將其更新為由第二個參數指定的新值。如果回呼返回 nil,寫入操作將被取消,值仍然未變更。

GlobalDataStores 中的值被視為 版本化 ,如同在 版本化 中所述。OrderedDataStores 不支持版本控制,因此在訂購的數據儲存鑰匙上呼叫此方法會覆蓋當前值並使以前版本無法使用。

在另一個遊戲伺服器更新鍵匙的短時間間隔內,GlobalDataStore:UpdateAsync() 將再次呼叫函數,忽略前一次呼叫的結果。函數將被呼叫多次,直到數據被保存 直到回調函數返回nil為止。這可以用來確保沒有資料被覆蓋。

任何被儲存在數據存儲中的字串必須有效 UTF-8 .在 UTF-8 中,超過 127 的值僅用於編碼多個字元代碼點,因此單一超過 127 的字元不會是有效的 UTF-8,且 GlobalDataStore:UpdateAsync() 嘗試將失敗。

設定與更新

GlobalDataStore:SetAsync() 最適合快速更新特定鍵,只會對寫入限制進行計數。然而,如果兩個伺服器在同一時間嘗試設置相同的鑰匙,可能會導致數據不一致。GlobalDataStore:UpdateAsync() 更安全地處理多個伺服器的嘗試,因為它在進行任何變更之前會閱讀當前的鑰匙值 (從最後更新的伺服器),以便確保沒有問題。但是,它的速度有點慢,因為它先讀再寫,它也會對閱讀和寫入限制進行計數。

呼叫回功能

回呼功能接受兩個參數:

  • 更新前鑰匙的當前值。
  • DataStoreKeyInfo 包含最新版本資訊的實例(如果元數據未被使用,此參數可被忽略)。

回到上面,回叫功能可返回最多三個值:

  • 為鑰鍵設置的新值。
  • 與鑰鍵相關的 UserIds 陣列。DataStoreKeyInfo:GetUserIds()應返回,除非現有ID被更改;否則所有現有ID將被清除。
  • 包含與鍵匙相關元數據的 Luau 表。DataStoreKeyInfo:GetMetadata() 應返回,除非現有元數據正在被更改;否則所有現有元數據將被清除。

如果回呼返回 nil 而不是返回,現有伺服器將停止嘗試更新鑰鍵。

回叫功能無法產生,因此不要包含 不包含task.wait() 的呼叫。

參數

key: string

值應更新的鑰匙名稱。如果 DataStoreOptions.AllScopes 在通過 DataStoreService:GetDataStore() 存取資料儲存時設為真實,此鍵名必須與原始範圍一樣在 "scope/key" 中加以前缀。

預設值:""
transformFunction: function

轉換功能,會將當前值和 DataStoreKeyInfo 作為參數,並返回新值以及可選的 UserIds 和元數據。

預設值:""

返回

使用指定的鑰匙和包含版本號、日期和時間的版本被創建的資料儲存中的入口的更新值,以及包含版本號、日期和時間的版本以及功能來恢復 和元數據的實例。

活動