ワールドデータストレージ

7 分

ZEPETOのデータストレージは、ユーザーのゲームプレイデータをワールドごとに保存および管理するリモートデータベースです。

これは、ユーザーIDによって保存および管理されるため、複数のプレイセッションにわたって維持または更新する必要があるユーザーのゲームプレイデータを保存するのに適しています。

ユーザーのプレイデータを管理するには、APIを使用して、ZEPETOマルチプレイサーバーで利用可能です。

ZEPETO Studioのワールドデータ管理メニューから、データストレージに保存されたユーザー特有のプレイデータを表示および変更できます。

📘 次のガイドを参照してください。 [ワールドデータ管理]

データストレージAPI

📘 以下のAPIリファレンスを参照してください。ZEPETO.Multiplay.DataStorage API

サーバーコード index.ts サンドボックスに記入してください。
Unityエディタ環境のローカルサーバーでは、サーバーがシャットダウンされ再起動されるとデータは保持されません。
ワールドデプロイ後、データはZEPETO DBに保存され、維持されます。
以下のルールが満たされない場合、データは保存されません：
- 値が提供されていない
- 保存できない値が入力されている
データストレージ制約
- キーの長さ制限：50文字
  - キーにはアルファベット、数字、アンダースコア(_)のみが許可されています。
- 最大キー数：ユーザーIDごとに1000
- 最大値データサイズ：500,000文字
  - 値データは、実際のサーバーに保存される際に内部識別子と共にシリアライズされることに注意してください。安全マージンを持って使用してください。

単一キーのデータを読み書き/削除する

ローカルプレイヤーのDataStorageで単一のキーのデータを読み書きおよび削除できます。DataStorage.get, DataStorage.set と DataStorage.remove.

import { DataStorage } from 'ZEPETO.Multiplay.DataStorage';

export default class extends Sandbox {

    //...

    async onJoin(client: SandboxPlayer) {
        // ローカルプレイヤーのデータストレージを読み込む
        const playerStorage: DataStorage = client.loadDataStorage();

        // 'level'キーに関連付けられた値を取得
	      let playerLevel = await playerStorage.get("level") as number;
        if (playerLevel == null) {
            playerLevel += 1; 
        }

        // 増加した値を保存
        await playerStorage.set("level", playerLevel);

        // データを削除
        await playerStorage.remove("level");
    }
}

複数のキーのデータを読み書きする

ローカルプレイヤーのデータストレージを使用して、複数のキーのデータを読み書きおよび削除できます。DataStorage.mget と DataStorage.mset.

import { DataStorage } from 'ZEPETO.Multiplay.DataStorage';

export default class extends Sandbox {

    //...

    async onJoin(client: SandboxPlayer) {
        const storage = client.loadDataStorage();
        // mset (マルチキー値) ストア
        const success = await storage.mset<number>([
            { key: 'key1', value: 1 },
            { key: 'key2', value: 2 }
        ]);
        // 成功した場合
        if (success) {
            // key1 と key2 の値を一度に取得
            const keys = ['key1', 'key2'];
            const keyValeus = await storage.mget(keys);
            keys.forEach(key => {
                const value = keyValeus[key];
                console.log(value);
            });
        }
    }
}

エラーハンドリング

DataStorage APIを呼び出す際に発生する例外に対して適切なハンドリングを実装することができます。これは、DataStorageErrorで定義されたエラータイプを参照してください。

import { DataStorage } from 'ZEPETO.Multiplay.DataStorage';

export default class extends Sandbox {

    //...

    async onJoin(client: SandboxPlayer) {
        // ローカルプレイヤーのデータストレージを読み込む
        const playerStorage: DataStorage = client.loadDataStorage();

        try {
            let playerLevel = await playerStorage.get("level") as number;
        } catch (error) {
            let systemError = (error as SystemError);

            if (systemError.code === DataStorageError.Unknown || systemError.code === DataStorageError.NetworkError) {
                // システムエラーまたはネットワークエラー
                console.log(systemError.message);

            } else if (systemError.code === DataStorageError.KeyConstraintViolated) {
                // キー制約違反
                console.log(systemError.message);
                
            } else if (systemError.code === DataStorageError.ValueConstraintViolated) {
                // 値制約違反
                console.log(systemError.message);
            }
        }
    }
}

ユーザーIDによるデータストレージへのアクセス

特定のユーザーのデータストレージにユーザーIDを使用してアクセスすることも可能です。DataStorage.loadDataStorage, ローカルプレイヤーのデータストレージの代わりに。

    const userStorage: DataStorage = await loadDataStorage(userId);

👍 ヒント

異なるワールド間でデータを保存したい場合は、httpServiceを使用して実装してください。