データストアのバージョン管理、リスト表示、およびキャッシュ

データをバージョン管理、リスト表示、およびキャッシュを使用して管理します。

バージョン管理

バージョン管理は、データを設定、更新、およびインクリメントするときに行われます。関数 SetAsync()、UpdateAsync()、および IncrementAsync() は、各UTC時間の各キーへの最初の書き込みを使用してデータのバージョン付きバックアップを作成します。同じUTC時間内でのキーへの連続した書き込みは、以前のデータを永久に上書きします。

バージョン付きバックアップは、新しい書き込みによって上書きされてから30日後に期限切れになります。最新のバージョンは決して期限切れになりません。

以下の関数はバージョン管理操作を実行します：

バージョン管理を使用してユーザーのリクエストを処理できます。ユーザーが2020-10-09T01:42に問題が発生したと報告した場合、次の例を使用してデータを以前のバージョンに戻すことができます：

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local DATA_STORE_KEY = "User_1234"

local maxDate = DateTime.fromUniversalTime(2020, 10, 09, 01, 42)

-- 指定された時間に最も近いバージョンを取得
local listSuccess, pages = pcall(function()
    return gameStore:ListVersionsAsync(DATA_STORE_KEY, Enum.SortDirection.Descending, nil, maxDate.UnixTimestampMillis)
end)
if listSuccess then
    local items = pages:GetCurrentPage()
    if #items > 0 then
        -- 最も近いバージョンを読み取る
        local closestEntry = items[1]
        local success, value, info = pcall(function()
            return gameStore:GetVersionAsync(DATA_STORE_KEY, closestEntry.Version)
        end)
        -- 最も近いバージョンで現在の値を上書きして復元
        if success then
            local setOptions = Instance.new("DataStoreSetOptions")
            setOptions:SetMetadata(info:GetMetadata())
            gameStore:SetAsync(DATA_STORE_KEY, value, nil, setOptions)
        end
    else
        -- エントリが見つかりませんでした
    end
end

スナップショット

スナップショットデータストアオープンクラウドAPIを使用すると、ゲーム内のすべてのデータストアのスナップショットを1日1回取得できます。データストレージロジックを変更するゲームの更新を公開する前に、必ずスナップショットを取得してください。スナップショットを取得することで、ゲームの前のバージョンから最新のデータを確保できます。

たとえば、スナップショットがない場合、3:30 UTCにデータが破損する更新を公開すると、破損したデータが3:00-3:30 UTCの間に書き込まれたデータを上書きします。しかし、3:29 UTCにスナップショットを取得すれば、破損したデータは3:29 UTC以前に書き込まれたものを上書きせず、3:00-3:29 UTCの間に書き込まれたすべてのキーの最新データが保持されます。

リスト表示とプレフィックス

データストアでは、プレフィックスによるリスト表示が可能です。たとえば、"d"、"do"、または "dog" のように、"dog" のプレフィックスを持つ任意のキーまたはデータストアの名前の最初の n 文字でリスト表示できます。

すべてのデータストアまたはキーをリスト表示する際にプレフィックスを指定でき、そのプレフィックスに一致するオブジェクトのみを取得できます。ListDataStoresAsync() および ListKeysAsync() 関数は、リストを列挙するために使用できる DataStoreListingPages オブジェクトを返します。

スコープ

データストア内のキーをさらに整理するには、GetDataStore() の第2パラメータとしてユニークな文字列をスコープとして設定します。デフォルトのスコープ（スコープが指定されていない場合）は global です。スコープは、データストアで行われるすべての操作のすべてのキーの先頭に自動的に追加されます。

データストア名、スコープ、およびキーの組み合わせがキーを一意に識別します。スコープを持つキーを識別するには、これら3つの値が必要です。たとえば、User_1234 という名前の global スコープのキーを次のように読み取ることができます：

local DataStoreService = game:GetService("DataStoreService")
local inventoryStore = DataStoreService:GetDataStore("PlayerInventory")
local success, currentGold = pcall(function()
  return inventoryStore:GetAsync("User_1234")
end)

ただし、キー User_1234 が gold のスコープを持つ場合、次のように読み取る必要があります：

local DataStoreService = game:GetService("DataStoreService")
local inventoryStore = DataStoreService:GetDataStore("PlayerInventory", "gold")
local success, currentGold = pcall(function()
  return inventoryStore:GetAsync("User_1234")
end)

AllScopes プロパティ

DataStoreOptions には、リスト内のすべてのスコープからキーを返す AllScopes プロパティがあります。次に、リストアイテムの KeyName プロパティを使用して、データの読み取りや GetAsync()、および データの削除 に使用することができます。

AllScopes プロパティを使用する場合、GetDataStore() の第2パラメータは空の文字列（""）でなければなりません。

local DataStoreService = game:GetService("DataStoreService")

local options = Instance.new("DataStoreOptions")
options.AllScopes = true

local ds = DataStoreService:GetDataStore("DS1", "", options)

AllScopes プロパティを有効にし、データストアに新しいキーを作成する場合、そのキーにはスコープを scope/keyname の形式で指定する必要があります。指定しないと、APIはエラーをスローします。たとえば、gold/player_34545 はスコープとして gold を持つため受け入れられますが、player_34545 はエラーになります。

キャッシュ

キャッシュを使用して、データストアからデータを一時的に保存し、パフォーマンスを向上させ、サーバーへのリクエスト数を減らします。たとえば、ゲームはデータのコピーをキャッシュして、データストアに再度呼び出すことなく迅速にアクセスできるようにします。

キャッシュは、次のようにデータストアキーに対して行う変更に適用されます：

• GetAsync() を使用して データを読み取る。
• SetAsync() を使用して データを作成する。
• UpdateAsync() を使用して データを更新する。
• IncrementAsync() を使用して データをインクリメントする。
• RemoveAsync() を使用して データを削除する。

GetVersionAsync()、ListVersionsAsync()、ListKeysAsync()、および ListDataStoresAsync() はキャッシュを実装しておらず、常にサービスバックエンドから最新のデータを取得します。

デフォルトでは、エンジンは GetAsync() を使用して、バックエンドから取得した値をローカルキャッシュに4秒間保存します。また、デフォルトでは、GetAsync() のキャッシュキーに対するリクエストは、バックエンドに進むことなくキャッシュされた値を返します。キャッシュされた値を返す GetAsync() リクエストは、サーバー制限および スループット制限にカウントされません。

バックエンドからキャッシュされていない値を取得するすべての GetAsync() 呼び出しは、キャッシュを即座に更新し、4秒のタイマーを再起動します。

キャッシュの無効化

キャッシュを無効にして、サーバーから最新の値を取得するためにキャッシュを使用しないようにするには、GetAsync() 呼び出しに DataStoreGetOptions パラメータを追加し、UseCache プロパティを false に設定して、リクエストがキャッシュ内のキーを無視するようにします。

キャッシュを無効にすることは、複数のサーバーが高頻度でキーに書き込んでいる場合や、サーバーから最新の値を取得する必要がある場合に便利です。ただし、キャッシュをバイパスする GetAsync() リクエストは常にスループットおよびサーバー制限にカウントされるため、データストアの制限とクォータを消費する可能性があります。

書き込み後の即時検証読み取りには、DataStoreGetOptions.UseCache = false を使用して GetAsync() を使用します。デフォルトでは、GetAsync() はローカルの4秒キャッシュを使用するため、通常の検証読み取りは古いデータを返す可能性があります。

これは、UpdateAsync()、SetAsync()、IncrementAsync()、または RemoveAsync() がエラーを返すような書き込み操作の後に特に重要です。この場合、コードは再試行、返金、または他の修正アクションを取るかどうかを判断する必要があります。

次の例は、書き込みの結果を検証する際にキャッシュをバイパスする方法を示しています：

local ok = pcall(function()
    store:UpdateAsync(key, transform)
end)

if not ok then
    local options = Instance.new("DataStoreGetOptions")
    options.UseCache = false

    local success, value = pcall(function()
        return store:GetAsync(key, options)
    end)

    if success then
        -- キャッシュされた状態ではなく、バックエンドの状態に基づいて決定します
    end
end

シリアル化

DataStoreService はデータをJSON形式で保存します。スタジオでLuauデータを保存すると、Robloxはシリアル化と呼ばれるプロセスを使用して、そのデータをJSONに変換してデータストアに保存します。Robloxは次に、そのデータをLuauに戻し、デシリアル化と呼ばれる別のプロセスで返します。

シリアル化とデシリアル化は、次のLuauデータ型をサポートしています：

• Nil
• ブーリアン
• 数値

  • 特殊な数値 inf、-inf、および nan を保存しないでください。これらの値はJSON標準に準拠していません。これらの値を含むエントリをOpen Cloudを介して取得すると、レスポンスはタグ付きJSONオブジェクトとして表されます。詳細については、非有限数を参照してください。
• 文字列
• テーブル

  • テーブルは他のサポートされているデータ型のみを含む必要があります
  • 数値キーは、テーブルの長さが0の場合に文字列に変換されます
• バッファ

シリアル化がサポートされていないデータ型を保存しようとすると、次のいずれかが発生します：

• そのデータ型の保存に失敗し、エラーメッセージが表示されます。
• そのデータ型を nil として保存することに成功します。

データ型が nil として保存される理由をデバッグするには、JSONEncode 関数を使用できます。この関数にLuauデータ型を渡すと、Robloxがデータストアに保存した形式で返され、返されたデータをプレビューおよび調査できます。