---
title: World DataStorage
slug: world-sdk-guide-kr/world-datastorage
docTags: 
createdAt: 2024-09-02T08:34:13.134Z
---

ZEPETO의 데이터 저장소는 사용자 게임 플레이 데이터를 월드별로 저장하고 관리하는 원격 데이터베이스입니다.

사용자 ID에 의해 저장되고 관리되므로 여러 플레이 세션에서 유지되거나 업데이트해야 하는 사용자 게임 플레이 데이터를 저장하는 데 적합합니다.

사용자의 플레이 데이터를 관리하려면 [API](https://developer.zepeto.me/docs/multiplay-server/interfaces/ZEPETO_Multiplay_DataStorage.DataStorage/)를 사용하여 ZEPETO 멀티플레이 서버에서 사용할 수 있습니다.

ZEPETO 스튜디오의 월드 데이터 관리 메뉴에서 데이터 저장소에 저장된 사용자별 플레이 데이터를 보고 수정할 수 있습니다.

:::hint{type="info"}
**📘 **다음 가이드를 참조하십시오.  \[[월드 데이터 매니지먼트](docId\:QGGR-FyhsT_0FTVoPQzix)]
:::



## 데이터 저장소 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 Editor 환경의 로컬 서버에서 서버가 종료되고 다시 실행될 때 데이터가 보존되지 않습니다.
- 월드 배포 후 데이터는 ZEPETO DB에 저장되고 유지됩니다.
- 아래 규칙이 충족되지 않으면 데이터가 저장되지 않습니다:
  - 값이 제공되지 않음
  - 저장할 수 없는 값이 입력됨
- 데이터 저장 제약 조건
  - 키 길이 제한: 50자
    - 키에는 알파벳, 숫자 및 밑줄(\_)만 허용됩니다.
  - 최대 키 수: 사용자 ID당 1000개
  - 최대 값 데이터 크기: 500,000자
    - 값 데이터는 실제 서버에 저장될 때 내부 식별자와 함께 직렬화됩니다. 안전 여유를 두고 사용하세요.
:::



## 단일 키에 대한 데이터 읽기 / 쓰기 / 삭제

로컬 플레이어의 DataStorage에서 단일 키에 대한 데이터를 읽고, 쓰고, 삭제할 수 있습니다.[`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);
            });
        }
    }
}
```



## 오류 처리

DataStorage API를 호출할 때 발생하는 예외에 대한 적절한 처리를 구현할 수 있습니다. 이는 [`DataStorageError`](https://developer.zepeto.me/docs/multiplay-server/enums/ZEPETO_Multiplay_DataStorage.DataStorageError).

```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로 데이터 저장소에 접근하기

특정 사용자의 데이터 저장소에 UserID를 사용하여 접근하는 것도 가능합니다. [`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\:f2P5Ntq-0lu4Os_IavgJ8) 구현하세요.
:::