---
title: 世界数据存储
slug: world-sdk-guide-ch/LCodUDiHftW-bSOwDmzN4
docTags: 
createdAt: 2024-09-02T08:34:13.134Z
---

ZEPETO的DataStorage是一个远程数据库，按世界基础存储和管理用户的游戏数据。

它适合存储需要在多个游戏会话中维护或更新的用户游戏数据，因为它是由用户ID存储和管理的。

使用 [API](https://developer.zepeto.me/docs/multiplay-server/interfaces/ZEPETO_Multiplay_DataStorage.DataStorage/) 管理用户的游戏数据，

您可以从ZEPETO Studio的世界数据管理菜单中查看和修改存储在Data Storage中的用户特定游戏数据。

:::hint{type="info"}
**📘 **请参考以下指南。  \[[世界数据管理](docId\:A6ri_4B3oJFZiXkWqWysp)]
:::



## 数据存储API

:::hint{type="info"}
**📘 **请参考以下API文档。[ZEPETO.Multiplay.DataStorage API](https://developer.zepeto.me/docs/multiplay-server/interfaces/ZEPETO_Multiplay_DataStorage.DataStorage)
:::

:::hint{type="danger"}
- 请填写服务器代码 index.ts Sandbox。
- 在 Unity 编辑器环境中的本地服务器上，当服务器关闭并重新运行时，数据不会被保留。
- 在世界部署后，数据存储在 ZEPETO 数据库中并保持。
- 如果不满足以下规则，数据将不会被保存：
  - 未提供值
  - 输入了无法存储的值
- 数据存储限制
  - 键长度限制：50 个字符
    - 键中只允许字母、数字和下划线 (\_)
  - 最大键数：每个用户 ID 1000 个
  - 最大值数据大小：500,000 个字符
    - 请注意，值数据在实际服务器上存储时与内部标识符一起序列化。请留有安全余量。
:::



## 读取 / 写入 / 删除单个键的数据

您可以使用 [`DataStorage.get`](https://developer.zepeto.me/docs/multiplay-server/interfaces/ZEPETO_Multiplay_DataStorage.DataStorage/#get), [`DataStorage.set`](https://developer.zepeto.me/docs/multiplay-server/interfaces/ZEPETO_Multiplay_DataStorage.DataStorage/#set) 和 [`DataStorage.remove`](https://developer.zepeto.me/docs/multiplay-server/interfaces/ZEPETO_Multiplay_DataStorage.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");
    }
}
```



## 读取/写入多个键的数据

您可以使用 [`DataStorage.mget`](https://developer.zepeto.me/docs/multiplay-server/interfaces/ZEPETO_Multiplay_DataStorage.DataStorage/#mget) 和 [`DataStorage.mset`](https://developer.zepeto.me/docs/multiplay-server/interfaces/ZEPETO_Multiplay_DataStorage.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);
            });
        }
    }
}
```



## 错误处理

您可以通过参考在 [`DataStorageError`](https://developer.zepeto.me/docs/multiplay-server/enums/ZEPETO_Multiplay_DataStorage.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);
            }
        }
    }
}
```



## 通过用户ID访问数据存储

也可以通过用户ID访问特定用户的数据存储，使用 [`DataStorage.loadDataStorage`](https://developer.zepeto.me/docs/multiplay-server/namespaces/ZEPETO_Multiplay_DataStorage?_highlight=loaddatastorage#loaddatastorage), 而不是本地玩家的数据存储。

```typescript
    const userStorage: DataStorage = await loadDataStorage(userId);
```



:::hint{type="success"}
**👍 提示**

- 如果您想在不同的世界之间存储数据，请使用 [httpService](docId\:Bp1FJFPLeIaHMNzda9mvk)&#x20;
:::