GS2-Version SDK for Game Engine API リファレンス
モデル
EzVersion
バージョン
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
major | int | ✓ | ~ 2147483646 | メジャーバージョン | |
minor | int | ✓ | ~ 2147483646 | マイナーバージョン | |
micro | int | ✓ | ~ 2147483646 | マイクロバージョン |
EzVersionModel
バージョンモデル
ログインを受け入れるが、バージョンアップ出来ることを通知する警告バージョンと、ログインを受け入れないエラーバージョンを設定できます。
現在のバージョンをクライアントに申告させるのに、署名の有無を指定できます。
署名付きを選択した場合、クライアントは嘘のバージョン申告を出来なくなります。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
name | string | ✓ | ~ 128文字 | バージョンモデル名 | |
metadata | string | ~ 2048文字 | メタデータ | ||
warningVersion | EzVersion | {type} == “simple” | バージョンアップを促すバージョン | ||
errorVersion | EzVersion | {type} == “simple” | バージョンチェックでエラーになるバージョン | ||
scope | enum { “passive”, “active” } | ✓ | ~ 128文字 | 判定に使用するバージョン値の種類 | |
currentVersion | EzVersion | {type} == “simple” and {scope} == “active” | 現在のバージョン | ||
needSignature | bool | {scope} == “passive” | 判定するバージョン値に署名検証を必要とするか |
scope に指定する列挙型の定義
定義 | 説明 |
---|---|
passive | クライアントから送信 |
active | 過去明示的に承認したバージョン |
EzAcceptVersion
承認したバージョン
アプリバージョンや、アセットバージョンのようなデータに紐づいたバージョンではなく
同意した利用規約のバージョンのようなユーザ毎にバージョン管理が必要なエンティティで使用します。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
versionName | string | ✓ | ~ 128文字 | バージョン名 | |
userId | string | ✓ | ~ 128文字 | ユーザーID | |
version | EzVersion | ✓ | バージョン |
EzStatus
バージョンの状態
バージョンの検証結果を表します。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
versionModel | EzVersionModel | ✓ | バージョンモデル | ||
currentVersion | EzVersion | 現在のバージョン |
EzTargetVersion
検証するバージョン
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
versionName | string | ✓ | ~ 128文字 | バージョンモデル名 | |
version | EzVersion | {signature} == "" | バージョン | ||
body | string | ~ 1048576文字 | ボディ | ||
signature | string | ~ 256文字 | 署名 |
メソッド
getVersionModel
バージョンモデルを取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
versionName | string | ✓ | ~ 128文字 | バージョンモデル名 |
Result
型 | 説明 | |
---|---|---|
item | EzVersionModel | バージョンモデル |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).VersionModel(
versionName: "version-0001"
);
var item = await domain.ModelAsync();
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).VersionModel(
versionName: "version-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->VersionModel(
"version-0001" // versionName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
値の変更イベントハンドリング
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).VersionModel(
versionName: "version-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).VersionModel(
versionName: "version-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->VersionModel(
"version-0001" // versionName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Version::Model::FVersionModel> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listVersionModels
バージョンモデルの一覧を取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 |
Result
型 | 説明 | |
---|---|---|
items | List<EzVersionModel> | バージョンモデルのリスト |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.VersionModelsAsync(
).ToListAsync();
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.VersionModels(
);
List<EzVersionModel> items = new List<EzVersionModel>();
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->Version->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->VersionModels(
);
TArray<Gs2::UE5::Version::Model::FEzVersionModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
値の変更イベントハンドリング
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeVersionModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeVersionModels(callbackId);
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.VersionModels(
);
List<EzVersionModel> items = new List<EzVersionModel>();
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->Version->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeVersionModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeVersionModels(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
accept
バージョンを承認する
利用規約などで使用します。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
versionName | string | ✓ | ~ 128文字 | バージョン名 | |
version | EzVersion | 承認したバージョン |
Result
型 | 説明 | |
---|---|---|
item | EzAcceptVersion | 承認したバージョン |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
型 | 基底クラス | 説明 |
---|---|---|
AcceptVersionInvalidException | BadRequestException | 承認プロセスの途中でサーバーバージョンが更新された結果、エラーとなりました |
実装例
try {
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "eula"
);
var result = await domain.AcceptAsync(
version: new Gs2.Unity.Gs2Version.Model.EzVersion {
Major = 2,
Minor = 2,
Micro = 2,
}
);
var item = await result.ModelAsync();
} catch(Gs2.Gs2Version.Exception.AcceptVersionInvalid e) {
// Error as a result of an updated server version during the approval process
}
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "eula"
);
var future = domain.AcceptFuture(
version: new Gs2.Unity.Gs2Version.Model.EzVersion {
Major = 2,
Minor = 2,
Micro = 2,
}
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Version.Exception.AcceptVersionInvalidException)
{
// Error as a result of an updated server version during the approval process
}
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->AcceptVersion(
"eula" // versionName
);
const auto Future = Domain->Accept(
MakeShared<Gs2::UE5::Version::Model::FEzVersion>()
->WithMajor(
2,
->WithMinor(
2,
->WithMicro(
2
) // version
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Version::Error::FAcceptVersionInvalidError::Class))
{
// Error as a result of an updated server version during the approval process
}
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();
delete
承認したバージョンを削除する
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
versionName | string | ✓ | ~ 128文字 | バージョン名 |
Result
型 | 説明 | |
---|---|---|
item | EzAcceptVersion | 削除した承認バージョン |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "eula"
);
var result = await domain.DeleteAsync(
);
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "eula"
);
var future = domain.DeleteFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->AcceptVersion(
"eula" // versionName
);
const auto Future = Domain->Delete(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();
list
承認したバージョンの一覧を取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン | ||
limit | int | ✓ | 30 | 1 ~ 1000 | データの取得件数 |
Result
型 | 説明 | |
---|---|---|
items | List<EzAcceptVersion> | 承認したバージョンのリスト |
nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.AcceptVersionsAsync(
).ToListAsync();
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.AcceptVersions(
);
List<EzAcceptVersion> items = new List<EzAcceptVersion>();
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->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->AcceptVersions(
);
TArray<Gs2::UE5::Version::Model::FEzAcceptVersionPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
値の変更イベントハンドリング
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeAcceptVersions(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeAcceptVersions(callbackId);
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.AcceptVersions(
);
List<EzAcceptVersion> items = new List<EzAcceptVersion>();
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->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeAcceptVersions(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeAcceptVersions(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
checkVersion
バージョンチェックを実行
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
targetVersions | List<EzTargetVersion> | [] | ~ 1000 items | 検証するバージョンリスト |
Result
型 | 説明 | |
---|---|---|
projectToken | string | サインインしたプロジェクトトークン |
warnings | List<EzStatus> | バージョンの検証結果 警告のリスト |
errors | List<EzStatus> | バージョンの検証結果 エラーのリスト |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Checker(
);
var result = await domain.CheckVersionAsync(
targetVersions: new List<Gs2.Unity.Gs2Version.Model.EzTargetVersion> {
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
VersionName = "app",
Version =
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
Major = 1,
Minor = 2,
Micro = 3,
},
},
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
VersionName = "asset",
Version =
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
Major = 1,
Minor = 2,
Micro = 3,
},
},
}
);
var projectToken = result.ProjectToken;
var warnings = result.Warnings;
var errors = result.Errors;
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Checker(
);
var future = domain.CheckVersionFuture(
targetVersions: new List<Gs2.Unity.Gs2Version.Model.EzTargetVersion> {
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
VersionName = "app",
Version =
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
Major = 1,
Minor = 2,
Micro = 3,
},
},
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
VersionName = "asset",
Version =
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
Major = 1,
Minor = 2,
Micro = 3,
},
},
}
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var projectToken = future.Result.ProjectToken;
var warnings = future.Result.Warnings;
var errors = future.Result.Errors;
const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Checker(
);
const auto Future = Domain->CheckVersion(
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Version::Model::FEzTargetVersion>>>();
v->Add(
MakeShared<Gs2::UE5::Version::Model::FEzTargetVersion>()
->WithVersionName(TOptional<FString>("app"))
->WithVersion(MakeShared<Gs2::UE5::Version::Model::FEzVersion>()
->WithMajor(TOptional<int32>(1))
->WithMinor(TOptional<int32>(2))
->WithMicro(TOptional<int32>(3))
);
);
v->Add(
MakeShared<Gs2::UE5::Version::Model::FEzTargetVersion>()
->WithVersionName(TOptional<FString>("asset"))
->WithVersion(MakeShared<Gs2::UE5::Version::Model::FEzVersion>()
->WithMajor(TOptional<int32>(1))
->WithMinor(TOptional<int32>(2))
->WithMicro(TOptional<int32>(3))
);
);
return v;
}() // targetVersions
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();
const auto ProjectToken = Result->ProjectToken;
const auto Warnings = Result->Warnings;
const auto Errors = Result->Errors;