데이터 스토어 사용하기¶

데이터 스토어는 NoSQL 클라우드 데이터베이스를 사용하여 게임 구성 요소나 설정 정보 등 클라이언트에 사용되는 데이터를 저장하고 동기화할 수 있습니다. 배포 및 유지관리할 서버가 필요없는 클라이언트 기반의 게임이나 클라이언트 간 실시간 업데이트가 필요한 경우 좋은 솔루션이 될 수 있습니다.

데이터 스토어의 특징은 다음과 같습니다:

데이터가 각 게임의 개별 저장소에 저장됩니다.
모든 데이터는 암호화되어 안전하게 전송됩니다.
SQL 데이터베이스와 달리 테이블이나 행이 없으며 컬렉션으로 구성된 문서에 데이터를 저장합니다.
데이터는 키-값 쌍으로 문서화해 저장할 수 있습니다.
다수의 작은 문서가 모인 컬렉션을 저장하는 데에 최적화되어 있습니다.
키-값 설계 시 주의사항은 개발자 사이트의 운영 > 게임 데이터 스토어를 참고하세요.

데이터 추가¶

데이터는 하나의 키-값 쌍으로 추가하거나 한꺼번에 여러 쌍을 Map 형태로 추가할 수 있습니다. 요청 후 성공 또는 실패 결과를 받을 수 있습니다.

Warning

key에 해당하는 value는 단순한 문자열(String) 혹은 백슬래시()가 포함된 1차원의 JSON 문자열로 설정해야 합니다.

다음은 키 값 한 쌍의 데이터를 추가하는 예제 코드입니다.

UnityUnreal EngineC++KotlinJavaSwiftObjective-C

API Reference: DataStore .set

using hive;
        string key = "your data key";
        string value = "your data value";
        DataStore.set(key, value, (ResultAPI result) => {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

#include "HiveDataStore.h"

FString Key = TEXT("your data key");
FString Value = TEXT("your data value");

FHiveDataStore::Set(Key, Value, FHiveDataStoreOnSetDelegate::CreateLambda([this](const FHiveResultAPI& Result) {
        if (Result.IsSuccess()) {
                // API 호출 성공
        } else {
                // 호출 실패. 하단 에러코드 참고
        }
}));

API Reference: DataStore ::set

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        string key = "your data key";
        string value = "your data value";

        DataStore::set(key, value, [=](ResultAPI const & result) {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStore.set

import com.hive.DataStore
        import com.hive.ResultAPI
        val key = "your data key"
        val value = "your data value"
        DataStore.set(key, value, object : DataStore.DataStoreSetListener {
                    override fun onDataStoreSet(result: ResultAPI) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: DataStore.INSTANCE .set

import com.hive.DataStore;
        import com.hive.ResultAPI;
        String key = "your data key";
        String value = "your data value";
        DataStore.INSTANCE.set(key, value, result -> {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStoreInterface.set

import HIVEService
        let key = "your data key"
        let value = "your data value"
        DataStoreInterface.set(key, value: value) { result in
                if result.isSuccess() {
                // call successful
                }
                else {
                // Call failed. See error code below
                }
}

API Reference: HIVEDataStore set

#import <HIVEService/HIVEService-Swift.h>
        NSString *key = @"your data key";
        NSString *value = @"your data value";

        [HIVEDataStore set: key value: value handler: ^(HIVEResultAPI *result) {
                    if ([result isSuccess]) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
}];

Map 형태의 데이터를 추가하는 예제 코드입니다.

UnityUnreal EngineC++KotlinJavaSwiftObjective-C

API Reference: DataStore .set

using hive;
        Dictionary<string, string> map = new Dictionary<string, string> {
                    {"key1", "value1"},
                    {"key2", "value2"},
                    {"key3", "value3"}
        };

        DataStore.set(map, (ResultAPI result) => {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

#include "HiveDataStore.h"

TMap<FString, FString> Data;
Data.Emplace(TEXT("key1"), TEXT("value1"));
Data.Emplace(TEXT("key2"), TEXT("value2"));
Data.Emplace(TEXT("key3"), TEXT("value3"));

FHiveDataStore::Set(Data, FHiveDataStoreOnSetDelegate::CreateLambda([this](const FHiveResultAPI& Result) {
        if (Result.IsSuccess()) {
                // API 호출 성공
        } else {
                // 호출 실패. 하단 에러코드 참고
        }
}));

API Reference: DataStore ::set

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        map<string, string> map = {
                    {"key1", "value1"},
                    {"key2", "value2"},
                    {"key3", "value3"}
        };

        DataStore::set(map, [=](ResultAPI const & result) {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStore.set

import com.hive.DataStore
        import com.hive.ResultAPI
        val map = mapOf(
                    "key1" to "value1",
                    "key2" to "value2",
                    "key3" to "value3",
        )
        DataStore.set(map, object : DataStore.DataStoreSetListener {
                    override fun onDataStoreSet(result: ResultAPI) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: DataStore.INSTANCE .set

import com.hive.DataStore;
        import com.hive.ResultAPI;
        Map<String, String> map = new HashMap<>();
        map.put("key1", "value1");
        map.put("key2", "value2");
        map.put("key3", "value3");
        DataStore.INSTANCE.set(map, result -> {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStoreInterface.set

import HIVEService
        let map: [String: String] = [
        "key1" : "value1",
        "key2" : "value2",
        "key3" : "value3"
        ]
        DataStoreInterface.set(map) { result in
                if result.isSuccess() {
                // call successful
                } else {
                // Call failed. See error code below
                }
}

API Reference: HIVEDataStore set

#import <HIVEService/HIVEService-Swift.h>
        NSDictionary<NSString *, NSString *> *map = @{
                    @"key1" : @"value1",
                    @"key2" : @"value2",
                    @"key3" : @"value3"
        };

        [HIVEDataStore set: map handler: ^(HIVEResultAPI *result) {
                    if ([result isSuccess]) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
}];

데이터 가져오기¶

데이터를 가져오는 3가지 방법은 다음과 같습니다:

- 내 데이터 하나 가져오기
- 내 데이터 모두 가져오기
- 키로 전체 데이터 가져오기

내 정보를 하나 또는 모두 가져올 수 있는 방법이 있고, 요청 키에 해당하는 전체 데이터를 가져오는 방법이 있습니다. 아래에 각 방법에 따라 제시된 예제 코드를 확인해보세요.

다음은 내 데이터 하나를 가져오는 예제 코드입니다.

UnityUnreal EngineC++KotlinJavaSwiftObjective-C

API Reference: DataStore .get

using hive;
        string key = "your data key";

        DataStore.get(key, (ResultAPI result, string data) => {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

#include "HiveDataStore.h"

FString Key = TEXT("your data key");
FHiveDataStore::Get(Key, FHiveDataStoreOnGetDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FString& Data) {
        if (Result.IsSuccess()) {
                // API 호출 성공
        } else {
                // 호출 실패. 하단 에러코드 참고
        }
}));

API Reference: DataStore ::get

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        string key = "your data key";

        DataStore::get(key, [=](ResultAPI const & result, string data) {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStore.get

import com.hive.DataStore
        import com.hive.ResultAPI
        val key = "your data key"
        DataStore.get(key, object : DataStore.DataStoreGetListener {
                    override fun onDataStoreGet(result: ResultAPI, data: String?) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: DataStore.INSTANCE .get

import com.hive.DataStore;
        import com.hive.ResultAPI;
        String key = "your data key";
        DataStore.INSTANCE.get(key, (result, data) -> {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStoreInterface.get

import HIVEService
        let key = "your data key"
        DataStoreInterface.get(key) { result, data in
                if result.isSuccess() {
                // call successful
                } else {
                // Call failed. See error code below
                }
}

API Reference: HIVEDataStore get

#import <HIVEService/HIVEService-Swift.h>
        NSString* key = @"your data key";

        [HIVEDataStore get: key handler: ^(HIVEResultAPI *result, NSString *data) {
                    if ([result isSuccess]) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
}];

내 모든 데이터를 가져오는 예제 코드입니다.

UnityUnreal EngineC++KotlinJavaSwiftObjective-C

API Reference: DataStore .getMyData

using hive;
        DataStore.getMyData((ResultAPI result, Dictionary<string, string> myData) => {
                    if (result.isSuccess()) {
                            // call successful
                            // myData: the added key-value map
                    } else {
                            // Call failed. See error code below
                    }
});

#include "HiveDataStore.h"

FHiveDataStore::GetMyData(FHiveDataStoreOnMyDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const DataStoreData& MyData) {

        if (Result.IsSuccess()) {
                // API 호출 성공
                // MyData: 추가했던 <Key, Value> 형태의 Map
        } else {
                // 호출 실패. 하단 에러코드 참고
        }
}));

API Reference: DataStore .getMyData

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;
        DataStore.getMyData([=](ResultAPI const & result, map<string, string> const & myData) {
                    if (result.isSuccess()) {
                            // call successful
                            // myData: the added key-value map
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStore.getMyData

import com.hive.DataStore
        import com.hive.ResultAPI
        DataStore.getMyData(object : DataStore.DataStoreMyDataListener {
                    override fun onDataStoreMyData(result: ResultAPI, myData: Map<String, String>) {
                            if (result.isSuccess) {
                                    // call successful
                                    // myData: the added key-value map
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: DataStore.INSTANCE .getMyData

import com.hive.DataStore
        import com.hive.ResultAPI
        DataStore.INSTANCE.getMyData((result, myData) -> {
                    if (result.isSuccess()) {
                            // call successful
                            // myData: the added key-value map
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStoreInterface .getMyData

import HIVEService
        DataStoreInterface.getMyData() { result, myData in
                if result.isSuccess() {
                // call successful
                                // myData: the added key-value map
                } else {
                // Call failed. See error code below
                }
}

API Reference: HIVEDataStore getMyData

#import <HIVEService/HIVEService-Swift.h>
        [HIVEDataStore getMyData: ^(HIVEResultAPI *result, NSDictionary<NSString *, NSString *> *myData) {
                    if ([result isSuccess]) {
                            // call successful
                            // myData: the added key-value map
                    } else {
                            // Call failed. See error code below
                    }
}];

키로 전체 데이터를 가져오는 예제 코드입니다.

UnityUnreal EngineC++KotlinJavaSwiftObjective-C

API Reference: DataStore .getUsersData

using hive;
        string key = "your data key";
        DataStore.getUsersData(key, (ResultAPI result, string key, Dictionary<long, string> usersData) => {
                    if (result.isSuccess()) {
                            // call successful
                            // key: Entered key
                            // usersData: Map in PlayerId-value format. Be careful about the long key type.
                    } else {
                            // Call failed. See error code below
                    }
});

#include "HiveDataStore.h"

FString Key = TEXT("your data key");
FHiveDataStore::GetUsersData(Key, FHiveDataStoreOnUsersDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FString& Key, const DataStoreUsersData& UsersData) {
        if (Result.IsSuccess()) {
                // API 호출 성공
                // Key: 입력한 키
                // UsersData: PlayerId-값 형태의 Map. 키가 int64 타입에 주의
        } else {
                // 호출 실패. 하단 에러코드 참고
        }
}));

API Reference: DataStore ::getUsersData

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        string key = "your data key";

        DataStore::getUsersData(key, [=](ResultAPI const & result, string key, map const & usersData) {
                    if (result.isSuccess()) {
                            // call successful
                            // key: Entered key
                            // usersData: Map in PlayerId-value format. Be careful that the key is of long long type.
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStore.getUsersData

import com.hive.DataStore
        import com.hive.ResultAPI
        val key = "your data key"
        DataStore.getUsersData(key, object : DataStore.DataStoreUsersDataListener {
                    override fun onDataStoreUsersData(result: ResultAPI, key: String?, usersData: Map<Long, String>) {
                            if (result.isSuccess) {
                                    // call successful
                                    // key: Entered key
                                    // usersData: Map in PlayerId-value format. Be careful about the long type.
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: DataStore.INSTANCE .getUsersData

import com.hive.DataStore;
        import com.hive.ResultAPI;
        String key = "your data key";
        DataStore.INSTANCE.getUsersData(key, (result, key1, usersData) -> {
                    if (result.isSuccess()) {
                            // call successful
                            // key: Entered key
                            // usersData: Map in PlayerId-value format. Be careful about the long type.
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: DataStoreInterface.getUsersData

import HIVEService
        let key = "your data key"
        DataStoreInterface.getUsersData(key) { result, key, usersData in
                if result.isSuccess() {
                // call successful
                // key: Entered key
                // usersData: Map in PlayerId-value format. Note that the key is of type Int64.
                } else {
                // Call failed. See error code below
                }
}

API Reference: HIVEDataStore getUsersData

#import <HIVEService/HIVEService-Swift.h>
        NSString* key = @"your data key";
        [HIVEDataStore getUsersData: key handler: ^(HIVEResultAPI *result, NSString *key, NSDictionary<NSNumber *, NSString *> *usersData) {
                    if ([result isSuccess]) {
                            // success
                            // key: Entered key
                            // usersData: Map in PlayerId-value format. Note that the key is of type NSNumber *.
                    } else {
                            // Call failed. See error code below
                    }
}];

에러 코드¶

Error Code	Message	Description
RESPONSE_FAIL	DataStoreNotExistKey	서버에 해당 키가 없을 경우
RESPONSE_FAIL	DataStoreNotExistColumn	서버에 Column Family(table)이 없을 경우
RESPONSE_FAIL	DataStoreGameIsBeingInspected	해당 게임의 데이터 스토어가 점검중인 경우
DEVELOPER_ERROR	DataStoreNotExistPublicKey	공개키가 없을 경우. 콘솔 설정 확인 필요
NEED_INITIALIZE	DataStoreNotInitialized	SDK Setup이 되어 있지 않을 경우 (AuthV4.setup)
INVALID_SESSION	DataStoreNeedSignIn	Sign-In 이 되어 있지 않을 경우
DEVELOPER_ERROR	DataStoreDisabled	데이터 스토어 미사용으로 설정되어 있을 경우. 콘솔 설정 확인 필요
RESPONSE_FAIL	DataStoreResponseError	서버에 연결은 됐으나 작업에 실패했을 경우. 에러 메시지 확인 필요
INVALID_PARAM	DataStoreInvalidParam	`set()` API 호출 과정에서 잘못 입력된 파라미터로 실패한 경우