世界数据存储

7min
ZEPETO的DataStorage是一个远程数据库，按世界基础存储和管理用户的游戏数据。
它适合存储需要在多个游戏会话中维护或更新的用户游戏数据，因为它是由用户ID存储和管理的。
使用 API 管理用户的游戏数据，
您可以从ZEPETO Studio的世界数据管理菜单中查看和修改存储在Data Storage中的用户特定游戏数据。
📘 请参考以下指南。  [世界数据管理﻿]
﻿
数据存储API
📘 请参考以下API文档。ZEPETO.Multiplay.DataStorage API﻿
请填写服务器代码 index.ts Sandbox。
在 Unity 编辑器环境中的本地服务器上，当服务器关闭并重新运行时，数据不会被保留。
在世界部署后，数据存储在 ZEPETO 数据库中并保持。
如果不满足以下规则，数据将不会被保存：
未提供值
输入了无法存储的值
数据存储限制
键长度限制：50 个字符
键中只允许字母、数字和下划线 (_)
最大键数：每个用户 ID 1000 个
最大值数据大小：500,000 个字符
请注意，值数据在实际服务器上存储时与内部标识符一起序列化。请留有安全余量。
﻿
读取 / 写入 / 删除单个键的数据
您可以使用 DataStorage.get, DataStorage.set 和 DataStorage.remove.
TypeScript
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");
    }
}
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.
TypeScript
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);
            });
        }
    }
}
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);
            });
        }
    }
}
﻿
﻿
错误处理
您可以通过参考在 DataStorageError 中定义的错误类型来实现对调用 DataStorage API 时发生的异常的适当处理。
TypeScript
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);
            }
        }
    }
}
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, 而不是本地玩家的数据存储。
TypeScript
    const userStorage: DataStorage = await loadDataStorage(userId);
    const userStorage: DataStorage = await loadDataStorage(userId);
﻿
﻿
👍 提示
如果您想在不同的世界之间存储数据，请使用 httpService﻿ 
﻿
更新日期 11 Oct 2024
此页面是否对您有帮助？
上一个
来自Multiplay服务器的HTTP请求
下一个