API Reference of GS2-Datastore SDK for Game Engine

Model

EzDataObject

Data Object

Data objects are data uploaded by game players. Data is generation managed, with 30 days of historical data stored.

Access permissions can be set for the data. There are three scopes: public, which can be accessed by anyone; protected, which can be accessed only by the game player with the specified user ID; and private, which can be accessed only by the game player himself.

TypeRequireDefaultLimitationDescription
dataObjectIdstring~ 1024 charsData object GRN
namestringUUID~ 128 charsData object Name
userIdstring~ 128 charsUser Id
scopeenum {
    “public”,
    “protected”,
    “private”
}
“private”~ 128 charsFile access permission
allowUserIdsList<string>{scope} != none and {scope} == “protected”[]~ 10000 itemsList of user IDs to be published
statusenum {
    “ACTIVE”,
    “UPLOADING”,
    “DELETED”
}
~ 128 charsStatus
generationstring~ 128 charsData Generation
createdAtlongNowDatetime of creation (Unix time unit:milliseconds)
updatedAtlongNowDatetime of last update (Unix time unit:milliseconds)

Enumeration type definition to specify as scope

Enumerator String DefinitionDescription
publicPublic
protectedOnly to specified users
privatePrivate

Enumeration type definition to specify as status

Enumerator String DefinitionDescription
ACTIVEActive
UPLOADINGUploading
DELETEDDeleted(Actual deletion 30 days after the deletion process)

EzDataObjectHistory

Data Object History

You can check the update history of data objects.

TypeRequireDefaultLimitationDescription
dataObjectHistoryIdstring~ 1024 charsHistory of Data object GRN
generationstring~ 128 charsGenerations ID
contentLengthlong~ 10485760File size
createdAtlongNowDatetime of creation (Unix time unit:milliseconds)

Methods

deleteDataObject

Delete uploaded data

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
accessTokenstring~ 128 charsUser Id
dataObjectNamestringUUID~ 128 charsData object Name

Result

TypeDescription
itemEzDataObjectData object

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

TypeBase TypeDescription
InvalidStatusExceptionBadRequestExceptionDataObject is not in operable state.

Implementation Example

try {
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var result = await domain.DeleteDataObjectAsync(
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Datastore.Exception.InvalidStatus e) {
    // DataObject is not in operable state.
}
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var future = domain.DeleteDataObjectFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Datastore.Exception.InvalidStatusException)
        {
            // DataObject is not in operable state.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->DataObject(
        "dataObject-0001" // dataObjectName
    );
    const auto Future = Domain->DeleteDataObject(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Datastore::Error::FInvalidStatusError::Class))
        {
            // DataObject is not in operable state.
        }
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

doneUpload

Report completion of data upload

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
accessTokenstring~ 128 charsUser Id
dataObjectNamestringUUID~ 128 charsData object Name

Result

TypeDescription
itemEzDataObjectData object

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

TypeBase TypeDescription
InvalidStatusExceptionBadRequestExceptionDataObject is not in operable state.
NotUploadedExceptionBadRequestExceptionDataObject is not uploaded.

Implementation Example

try {
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var result = await domain.DoneUploadAsync(
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Datastore.Exception.InvalidStatus e) {
    // DataObject is not in operable state.
} catch(Gs2.Gs2Datastore.Exception.NotUploaded e) {
    // DataObject is not uploaded.
}
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var future = domain.DoneUploadFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Datastore.Exception.InvalidStatusException)
        {
            // DataObject is not in operable state.
        }
        if (future.Error is Gs2.Gs2Datastore.Exception.NotUploadedException)
        {
            // DataObject is not uploaded.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->DataObject(
        "dataObject-0001" // dataObjectName
    );
    const auto Future = Domain->DoneUpload(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Datastore::Error::FInvalidStatusError::Class))
        {
            // DataObject is not in operable state.
        }
        if (e->IsChildOf(Gs2::Datastore::Error::FNotUploadedError::Class))
        {
            // DataObject is not uploaded.
        }
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

listMyDataObjects

Get list of data objects

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
accessTokenstring~ 128 charsUser Id
statusenum {
    “ACTIVE”,
    “UPLOADING”,
    “DELETED”
}
~ 128 charsStatus
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data acquired

Enumeration type definition to specify as status

Enumerator String DefinitionDescription
ACTIVEActive
UPLOADINGUploading
DELETEDDeleted(Actual deletion 30 days after the deletion process)

Result

TypeDescription
itemsList<EzDataObject>List of Data object
nextPageTokenstringPage token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.DataObjectsAsync(
        status: "ACTIVE"
    ).ToListAsync();
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.DataObjects(
        status: "ACTIVE"
    );
    List<EzDataObject> items = new List<EzDataObject>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->DataObjects(
        "ACTIVE" // status
    );
    TArray<Gs2::UE5::Datastore::Model::FEzDataObjectPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeDataObjects(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeDataObjects(callbackId);
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.DataObjects(
        status: "ACTIVE"
    );
    List<EzDataObject> items = new List<EzDataObject>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeDataObjects(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeDataObjects(CallbackId);

prepareDownload

Report completion of data upload

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
dataObjectIdstring~ 1024 charsData object GRN
accessTokenstring~ 128 charsUser Id

Result

TypeDescription
itemEzDataObjectData object
fileUrlstringURL to download the file
contentLengthlongFile size

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.PrepareDownloadAsync(
        dataObjectId: "grn:dataObject-0001"
    );
    var item = await result.ModelAsync();
    var fileUrl = result.FileUrl;
    var contentLength = result.ContentLength;
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.PrepareDownloadFuture(
        dataObjectId: "grn:dataObject-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    var fileUrl = future.Result.FileUrl;
    var contentLength = future.Result.ContentLength;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->PrepareDownload(
        "grn:dataObject-0001" // dataObjectId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();
    const auto FileUrl = Result->FileUrl;
    const auto ContentLength = Result->ContentLength;

prepareDownloadByUserIdAndDataObjectName

Prepare to download data by specifying user ID and data name

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
userIdstring~ 128 charsUser Id
dataObjectNamestringUUID~ 128 charsData object Name

Result

TypeDescription
itemEzDataObjectData object
fileUrlstringURL to download the file
contentLengthlongFile size

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var result = await domain.PrepareDownloadByUserIdAndDataObjectNameAsync(
    );
    var item = await result.ModelAsync();
    var fileUrl = result.FileUrl;
    var contentLength = result.ContentLength;
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var future = domain.PrepareDownloadByUserIdAndDataObjectNameFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    var fileUrl = future.Result.FileUrl;
    var contentLength = future.Result.ContentLength;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->User(
        "user-0001" // userId
    )->DataObject(
        "dataObject-0001" // dataObjectName
    );
    const auto Future = Domain->PrepareDownloadByUserIdAndDataObjectName(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();
    const auto FileUrl = Result->FileUrl;
    const auto ContentLength = Result->ContentLength;

prepareDownloadOwnData

Prepare to download your own data

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
dataObjectNamestringUUID~ 128 charsData object Name
accessTokenstring~ 128 charsUser Id

Result

TypeDescription
itemEzDataObjectData object
fileUrlstringURL to download the file
contentLengthlongFile size

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var result = await domain.PrepareDownloadOwnDataAsync(
    );
    var item = await result.ModelAsync();
    var fileUrl = result.FileUrl;
    var contentLength = result.ContentLength;
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var future = domain.PrepareDownloadOwnDataFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    var fileUrl = future.Result.FileUrl;
    var contentLength = future.Result.ContentLength;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->DataObject(
        "dataObject-0001" // dataObjectName
    );
    const auto Future = Domain->PrepareDownloadOwnData(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();
    const auto FileUrl = Result->FileUrl;
    const auto ContentLength = Result->ContentLength;

Download

Download Data

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
dataObjectIdstring~ 1024 charsData object GRN
accessTokenstring~ 128 charsUser Id

Result

TypeDescription
itembyte arraybinary data

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.DownloadAsync(
        dataObjectId: "grn:dataObject-0001"
    );
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: dataObject.Name
    );
    var future = domain.DownloadFuture(
        dataObjectId: "grn:dataObject-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var result = future.Result;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->Download(
        "grn:dataObject-0001" // dataObjectId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

DownloadByUserIdAndDataObjectName

Download data by specifying user ID and data name

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
userIdstring~ 128 charsUser Id
dataObjectNamestringUUID~ 128 charsData object Name

Result

TypeDescription
itembyte arraybinary data

Implementation Example

var domain = gs2.Datastore.Namespace(
    namespaceName: "namespace-0001"
).User(
    userId: "user-0001"
).DataObject(
    dataObjectName: "dataObject-0001"
);
var result = await domain.DownloadByUserIdAndDataObjectNameAsync(
);
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var future = domain.DownloadByUserIdAndDataObjectNameFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var result = future.Result;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->User(
        "user-0001" // userId
    )->DataObject(
        "dataObject-0001", // dataObjectName
    );
    const auto Future = Domain->DownloadByUserIdAndDataObjectName(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

DownloadOwnData

Download own data

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
dataObjectNamestringUUID~ 128 charsData object Name
accessTokenstring~ 128 charsUser Id

Result

TypeDescription
itembyte arraybinary data

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var result = await domain.DownloadOwnDataAsync(
    );
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var future = domain.DownloadFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var result = future.Result;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    )->DataObject(
        "dataObject-0001" // dataObjectName
    );
    const auto Future = Domain->DownloadOwnData(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

prepareReUpload

Prepare to re-upload data

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
accessTokenstring~ 128 charsUser Id
dataObjectNamestringUUID~ 128 charsData object Name
contentTypestring“application/octet-stream”~ 256 charsMIME-Type of the data to be uploaded

Result

TypeDescription
itemEzDataObjectData object
uploadUrlstringURL used to execute the upload process

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var result = await domain.PrepareReUploadAsync(
        contentType: null
    );
    var item = await result.ModelAsync();
    var uploadUrl = result.UploadUrl;
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var future = domain.PrepareReUploadFuture(
        contentType: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    var uploadUrl = future.Result.UploadUrl;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->DataObject(
        "dataObject-0001" // dataObjectName
    );
    const auto Future = Domain->PrepareReUpload(
        // contentType
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();
    const auto UploadUrl = Result->UploadUrl;

prepareUpload

Prepare to upload data

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
accessTokenstring~ 128 charsUser Id
namestring~ 128 charsData object name
scopeenum {
    “public”,
    “protected”,
    “private”
}
“private”~ 128 charsFile access permission
contentTypestring“application/octet-stream”~ 256 charsMIME-Type of the data to be uploaded
allowUserIdsList<string>{scope} != none and {scope} == “protected”[]~ 10000 itemsList of user IDs to be published
updateIfExistsboolfalseWhether to raise an error if data already exists or to update the data

Enumeration type definition to specify as scope

Enumerator String DefinitionDescription
publicPublic
protectedOnly to specified users
privatePrivate

Result

TypeDescription
itemEzDataObjectData object
uploadUrlstringURL used to execute the upload process

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.PrepareUploadAsync(
        name: "dataObject-0001",
        scope: "public",
        contentType: null,
        allowUserIds: null,
        updateIfExists: null
    );
    var item = await result.ModelAsync();
    var uploadUrl = result.UploadUrl;
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.PrepareUploadFuture(
        name: "dataObject-0001",
        scope: "public",
        contentType: null,
        allowUserIds: null,
        updateIfExists: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    var uploadUrl = future.Result.UploadUrl;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->PrepareUpload(
        "dataObject-0001", // name
        "public" // scope
        // contentType
        // allowUserIds
        // updateIfExists
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();
    const auto UploadUrl = Result->UploadUrl;

restoreDataObject

Repair data management information

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
dataObjectIdstring~ 1024 charsData object GRN

Result

TypeDescription
itemEzDataObjectData object

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

TypeBase TypeDescription
InvalidStatusExceptionBadRequestExceptionDataObject is not in operable state.

Implementation Example

try {
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    );
    var result = await domain.RestoreDataObjectAsync(
        dataObjectId: "grn:dataObject-0001"
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Datastore.Exception.InvalidStatus e) {
    // DataObject is not in operable state.
}
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    );
    var future = domain.RestoreDataObjectFuture(
        dataObjectId: "grn:dataObject-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Datastore.Exception.InvalidStatusException)
        {
            // DataObject is not in operable state.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto Future = Domain->RestoreDataObject(
        "grn:dataObject-0001" // dataObjectId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Datastore::Error::FInvalidStatusError::Class))
        {
            // DataObject is not in operable state.
        }
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

updateDataObject

Update data objects

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
accessTokenstring~ 128 charsUser Id
scopeenum {
    “public”,
    “protected”,
    “private”
}
“private”~ 128 charsFile access permission
allowUserIdsList<string>{scope} != none and {scope} == “protected”[]~ 10000 itemsList of user IDs to be published

Enumeration type definition to specify as scope

Enumerator String DefinitionDescription
publicPublic
protectedOnly to specified users
privatePrivate

Result

TypeDescription
itemEzDataObjectData object

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var result = await domain.UpdateDataObjectAsync(
        scope: "public",
        allowUserIds: null
    );
    var item = await result.ModelAsync();
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var future = domain.UpdateDataObjectFuture(
        scope: "public",
        allowUserIds: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->DataObject(
        "dataObject-0001" // dataObjectName
    );
    const auto Future = Domain->UpdateDataObject(
        "public" // scope
        // allowUserIds
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

listDataObjectHistories

Obtain list of data object history

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
accessTokenstring~ 128 charsUser Id
dataObjectNamestringUUID~ 128 charsData object Name
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data acquired

Result

TypeDescription
itemsList<EzDataObjectHistory>List of History of Data object
nextPageTokenstringPage token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var items = await domain.DataObjectHistoriesAsync(
    ).ToListAsync();
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var it = domain.DataObjectHistories(
    );
    List<EzDataObjectHistory> items = new List<EzDataObjectHistory>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->DataObject(
        "dataObject-0001" // dataObjectName
    );
    const auto It = Domain->DataObjectHistories(
    );
    TArray<Gs2::UE5::Datastore::Model::FEzDataObjectHistoryPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeDataObjectHistories(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeDataObjectHistories(callbackId);
    var domain = gs2.Datastore.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).DataObject(
        dataObjectName: "dataObject-0001"
    );
    var it = domain.DataObjectHistories(
    );
    List<EzDataObjectHistory> items = new List<EzDataObjectHistory>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Datastore->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->DataObject(
        "dataObject-0001" // dataObjectName
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeDataObjectHistories(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeDataObjectHistories(CallbackId);