GS2-Distributor SDK for Game Engine API リファレンス

ゲームエンジン向け GS2-Distributor SDK の モデルの仕様 と API のリファレンス

モデル

EzStampSheetResult

トランザクション実行結果(レガシー)

サーバーサイドの自動実行で処理されたトランザクションの実行結果を記録します。
各フェーズのリクエスト内容とレスポンス結果を含みます:検証アクション(事前条件チェック)、消費アクション、入手アクション。エラー検出とリトライロジックのために HTTP ステータスコードも追跡します。

有効化条件必須デフォルト値の制限説明
transactionIdstring
36 ~ 36文字トランザクションID
このトランザクションを一意に識別する UUID です。トランザクションとその実行結果、および連鎖する後続トランザクションの関連付けに使用されます。
taskRequestsList<EzConsumeAction>0 ~ 100 items消費アクションのリクエスト内容
sheetRequestEzAcquireAction
入手アクションのリクエスト内容
taskResultsList<string>[]0 ~ 100 items消費アクションの実行結果
sheetResultstring~ 1048576文字入手アクションの実行結果レスポンス内容

EzTransactionResult

トランザクション実行結果

サーバーサイドの自動実行で処理された分散トランザクションの実行結果を記録します。
各フェーズの構造化された結果を含みます:検証アクション(事前条件チェック)、消費アクション(リソース消費)、入手アクション(リソース付与)。各アクション結果にはリクエスト、HTTP ステータスコード、レスポンスペイロードが含まれます。ステータスコード(非2xx)によるエラー検出と、コンフリクト(409)やサーバーエラー(5xx)でのリトライがサポートされます。

有効化条件必須デフォルト値の制限説明
transactionIdstring
36 ~ 36文字トランザクションID
この分散トランザクションを一意に識別する UUID です。実行結果の検索や、元の API リクエストとの関連付けに使用されます。
verifyResultsList<EzVerifyActionResult>0 ~ 100 items検証アクションの実行結果リスト
consumeResultsList<EzConsumeActionResult>0 ~ 100 items消費アクションの実行結果リスト
acquireResultsList<EzAcquireActionResult>0 ~ 100 items入手アクションの実行結果リスト

EzDistributorModel

配信モデル

配信モデルとはエンティティの入手時に所持枠を超えて入手した時のポリシーを設定するエンティティです。
GS2-Distributor を通して入手処理を行うことで、あふれたリソースを GS2-Inbox のメッセージとして転送することができます。

有効化条件必須デフォルト値の制限説明
namestring
~ 128文字配信モデル名
配信モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
metadatastring~ 2048文字メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。
inboxNamespaceIdstring~ 1024文字あふれたリソースを転送する GS2-Inbox のネームスペース GRN
リソースの入手がプレイヤーの所持枠を超えた場合、あふれたリソースは指定された GS2-Inbox ネームスペースにメッセージとして転送されます。プレイヤーは後から受信箱からリソースを受け取ることができます。
whiteListTargetIdsList<string>[]0 ~ 1000 itemsGS2-Distributorを通して処理出来る対象のリソースGRNのホワイトリスト
この配信モデルを使用して入手処理を行える対象となるリソースのGRNプレフィックスを指定します。

EzConfig

コンフィグ設定

トランザクションの変数に適用する設定値

有効化条件必須デフォルト値の制限説明
keystring
~ 64文字名前
valuestring~ 51200文字

EzDistributeResource

リソース配布

入手アクションとそのリクエストパラメータで構成される単一のリソース配布操作を表します。プレイヤーにリソースを配布する際に、どの GS2 API アクションをどのパラメータで実行するかを指定するために使用されます。

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
入手アクションで実行するアクションの種類
requeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列

EzBatchRequestPayload

API一括実行リクエスト

一括実行内の単一の API リクエストを表します。複数のバッチリクエストペイロードをまとめて送信することで、複数の GS2 API 呼び出しを1回のラウンドトリップで実行でき、ネットワークオーバーヘッドとレイテンシーを削減できます。

有効化条件必須デフォルト値の制限説明
requestIdstring
~ 128文字リクエストID
バッチ内でこのリクエストに対してクライアントが割り当てた識別子です。バッチレスポンス内で各リクエストと対応する結果を関連付けるために使用されます。
service文字列列挙型
enum {
  “account”,
  “adReward”,
  “auth”,
  “buff”,
  “chat”,
  “datastore”,
  “deploy”,
  “dictionary”,
  “distributor”,
  “enchant”,
  “enhance”,
  “exchange”,
  “experience”,
  “formation”,
  “friend”,
  “gateway”,
  “grade”,
  “guard”,
  “guild”,
  “identifier”,
  “idle”,
  “inbox”,
  “inventory”,
  “jobQueue”,
  “key”,
  “limit”,
  “lock”,
  “log”,
  “loginReward”,
  “lottery”,
  “matchmaking”,
  “megaField”,
  “mission”,
  “money”,
  “money2”,
  “news”,
  “quest”,
  “ranking”,
  “ranking2”,
  “realtime”,
  “schedule”,
  “script”,
  “seasonRating”,
  “serialKey”,
  “showcase”,
  “skillTree”,
  “stamina”,
  “stateMachine”,
  “version”
}
マイクロサービス名
呼び出す GS2 マイクロサービス名です(例: “inventory”、“experience”、“money”)。この API リクエストを受信するサービスエンドポイントを決定します。
定義説明
“account”GS2-Account
“adReward”GS2-AdReward
“auth”GS2-Auth
“buff”GS2-Buff
“chat”GS2-Chat
“datastore”GS2-Datastore
“deploy”GS2-Deploy
“dictionary”GS2-Dictionary
“distributor”GS2-Distributor
“enchant”GS2-Enchant
“enhance”GS2-Enhance
“exchange”GS2-Exchange
“experience”GS2-Experience
“formation”GS2-Formation
“friend”GS2-Friend
“gateway”GS2-Gateway
“grade”GS2-Grade
“guard”GS2-Guard
“guild”GS2-Guild
“identifier”GS2-Identifier
“idle”GS2-Idle
“inbox”GS2-Inbox
“inventory”GS2-Inventory
“jobQueue”GS2-JobQueue
“key”GS2-Key
“limit”GS2-Limit
“lock”GS2-Lock
“log”GS2-Log
“loginReward”GS2-LoginReward
“lottery”GS2-Lottery
“matchmaking”GS2-Matchmaking
“megaField”GS2-MegaField
“mission”GS2-Mission
“money”GS2-Money
“money2”GS2-Money2
“news”GS2-News
“quest”GS2-Quest
“ranking”GS2-Ranking
“ranking2”GS2-Ranking2
“realtime”GS2-Realtime
“schedule”GS2-Schedule
“script”GS2-Script
“seasonRating”GS2-SeasonRating
“serialKey”GS2-SerialKey
“showcase”GS2-Showcase
“skillTree”GS2-SkillTree
“stamina”GS2-Stamina
“stateMachine”GS2-StateMachine
“version”GS2-Version
methodNamestring
~ 128文字メソッド名
対象サービスで呼び出す API メソッド名です(例: “describeNamespaces”、“getInventory”)。指定されたサービスの有効な API メソッドと一致する必要があります。
parameterstring
~ 10240文字パラメータ
API メソッドの JSON シリアライズされたリクエストパラメータです。指定されたサービスメソッドのリクエストスキーマに準拠する必要があります。

EzBatchResultPayload

API一括実行結果

一括実行内の単一の API リクエストの結果を表します。各結果はリクエスト ID によって元のリクエストと関連付けられ、HTTP ステータスコードと JSON レスポンスペイロードを含みます。

有効化条件必須デフォルト値の制限説明
requestIdstring
~ 128文字リクエストID
対応するバッチリクエストと一致するクライアント割り当て識別子です。この結果を元のリクエストと関連付けるために使用されます。
statusCodeint
100 ~ 1000ステータスコード
このバッチリクエストに対して GS2 API が返した HTTP ステータスコードです。2xx は成功、4xx はクライアントエラー、5xx はサーバーエラーを示します。
resultPayloadstring
~ 10240文字レスポンス
このバッチリクエストに対して GS2 API が返した JSON レスポンスボディです。API メソッドのレスポンスデータまたはエラー詳細を含みます。

EzAcquireAction

入手アクション

分散トランザクション内のリソース入手操作を表します。プレイヤーにリソース(アイテム、通貨、経験値など)を付与する入手アクションに対応します。GS2 API のアクション識別子と JSON シリアライズされたリクエストパラメータを含みます。

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
入手アクションで実行するアクションの種類
requeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列

EzConsumeAction

消費アクション

分散トランザクション内のリソース消費操作を表します。プレイヤーからリソース(アイテム、通貨、スタミナなど)を消費する消費アクションに対応します。消費アクションは入手アクションの前に実行され、プレイヤーが必要なコストを満たしていることを確認します。

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
消費アクションで実行するアクションの種類
requeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列

EzVerifyAction

検証アクション

分散トランザクション内の事前条件検証操作を表します。消費・入手アクションの前に実行され、条件が満たされていることを検証します(例:所持枠の確認、クエスト完了状態の検証など)。いずれかの検証アクションが失敗した場合、トランザクション全体が中止されます。

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
検証アクションで実行するアクションの種類
requeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列

EzAcquireActionResult

入手アクションの実行結果

単一の入手アクション実行の結果を記録します。アクション識別子、元のリクエスト、成功・失敗を示す HTTP ステータスコード、GS2 API からの JSON レスポンスペイロードを含みます。

有効化条件必須デフォルト値の制限説明
acquireRequeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列
statusCodeint0 ~ 999ステータスコード
この入手アクションに対して GS2 API が返した HTTP ステータスコードです。2xx は成功、409 はリトライが必要なコンフリクト、5xx はサーバーエラーを示します。
acquireResultstring~ 1048576文字結果内容
入手アクションの実行後に GS2 API が返した JSON レスポンスボディです。入手したリソースの詳細を含み、連鎖するトランザクション ID が含まれる場合もあります。

EzConsumeActionResult

消費アクションの実行結果

単一の消費アクション実行の結果を記録します。アクション識別子、元のリクエスト、成功・失敗を示す HTTP ステータスコード、GS2 API からの JSON レスポンスペイロードを含みます。

有効化条件必須デフォルト値の制限説明
consumeRequeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列
statusCodeint0 ~ 999ステータスコード
この消費アクションに対して GS2 API が返した HTTP ステータスコードです。2xx は成功、409 はリトライが必要なコンフリクト、5xx はサーバーエラーを示します。
consumeResultstring~ 1048576文字結果内容
消費アクションの実行後に GS2 API が返した JSON レスポンスボディです。消費されたリソースの詳細を含みます。

EzVerifyActionResult

検証アクションの実行結果

単一の検証アクション実行の結果を記録します。アクション識別子、元のリクエスト、成功・失敗を示す HTTP ステータスコード、GS2 API からの JSON レスポンスペイロードを含みます。

有効化条件必須デフォルト値の制限説明
verifyRequeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列
statusCodeint0 ~ 999ステータスコード
この検証アクションに対して GS2 API が返した HTTP ステータスコードです。2xx は検証成功、非2xx は事前条件が満たされなかったことを示します。
verifyResultstring~ 1048576文字結果内容
検証アクションの実行後に GS2 API が返した JSON レスポンスボディです。検証結果の詳細を含みます。

メソッド

getDistributorModel

名前を指定して配信モデル定義を取得する

名前を指定して、配信モデルを1件取得します。
取得できる情報には、許可されているサービスアクションと、溢れ処理用に設定されたプレゼントボックスのネームスペースが含まれます。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
distributorNamestring
~ 128文字配信モデル名
配信モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

Result

説明
itemEzDistributorModel配信モデル

実装例

    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).DistributorModel(
        distributorName: "distributor-model-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).DistributorModel(
        distributorName: "distributor-model-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Distributor->Namespace(
        "namespace-0001" // namespaceName
    )->DistributorModel(
        "distributor-model-0001" // distributorName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
値の変更イベントハンドリング
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).DistributorModel(
        distributorName: "distributor-model-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).DistributorModel(
        distributorName: "distributor-model-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Distributor->Namespace(
        "namespace-0001" // namespaceName
    )->DistributorModel(
        "distributor-model-0001" // distributorName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Distributor::Model::FDistributorModel> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

listDistributorModels

配信モデル定義の一覧を取得する

このネームスペースに登録されているすべての配信モデルを取得します。
配信モデルは、リソース配信のルールを定義します。許可するサービスアクションや、プレイヤーのインベントリが満杯のときに溢れたアイテムをどこに送るか(例: プレゼントボックス / 受信箱)を設定します。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

Result

説明
itemsList<EzDistributorModel>配信モデルのリスト

実装例

    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.DistributorModelsAsync(
    ).ToListAsync();
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.DistributorModels(
    );
    List<EzDistributorModel> items = new List<EzDistributorModel>();
    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->Distributor->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->DistributorModels(
    );
    TArray<Gs2::UE5::Distributor::Model::FEzDistributorModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
値の変更イベントハンドリング
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeDistributorModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeDistributorModels(callbackId);
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeDistributorModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeDistributorModels(callbackId);
    const auto Domain = Gs2->Distributor->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeDistributorModels(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeDistributorModels(CallbackId);

batchExecuteApi

複数の API 呼び出しを一括実行する

複数の GS2 API リクエストを1回の呼び出しでまとめて送信し、レスポンスをまとめて受け取ります。
通信の往復回数が減り、複数の API を同時に呼ぶ必要がある場面でパフォーマンスが向上します。
たとえば、プレイヤーがホーム画面を開いたときに、インベントリ・スタミナ・クエスト進捗をまとめて取得する場合などに便利です。

Request

有効化条件必須デフォルト値の制限説明
requestPayloadsList<EzBatchRequestPayload>
1 ~ 100 itemsバッチリクエスト

Result

説明
resultsList<EzBatchResultPayload>バッチリザルト

実装例

    var domain = gs2.Distributor.Namespace(
        namespaceName: null
    );
    var result = await domain.BatchExecuteApiAsync(
        requestPayloads: new List<Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload> {
            new Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload() {
                Service = "inventory",
                Method = "describeSimpleItems",
                Request = "{\"namespaceName\": \"namespace-0001\", \"inventoryName\": \"inventory-0001\", \"accessToken\": \"accessToken-0001\"}",
            },
            new Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload() {
                Service = "exchange",
                Method = "describeRateModels",
                Request = "{\"namespaceName\": \"namespace-0001\"}",
            },
        }
    );
    var results = result.Results;
    var domain = gs2.Distributor.Namespace(
        namespaceName: null
    );
    var future = domain.BatchExecuteApiFuture(
        requestPayloads: new List<Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload> {
            new Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload() {
                Service = "inventory",
                Method = "describeSimpleItems",
                Request = "{\"namespaceName\": \"namespace-0001\", \"inventoryName\": \"inventory-0001\", \"accessToken\": \"accessToken-0001\"}",
            },
            new Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload() {
                Service = "exchange",
                Method = "describeRateModels",
                Request = "{\"namespaceName\": \"namespace-0001\"}",
            },
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var results = future.Result.Results;
    const auto Domain = Gs2->Distributor->Namespace(
        nullptr // namespaceName
    );
    const auto Future = Domain->BatchExecuteApi(
        []
        {
            auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Distributor::Model::FEzBatchRequestPayload>>>();
            v->Add(
                MakeShared<Gs2::UE5::Distributor::Model::FEzBatchRequestPayload>()
                ->WithService(TOptional<FString>("inventory"))
                ->WithMethod(TOptional<FString>("describeSimpleItems"))
                ->WithRequest(TOptional<FString>("{\"namespaceName\": \"namespace-0001\", \"inventoryName\": \"inventory-0001\", \"accessToken\": \"accessToken-0001\"}"))
            );
            v->Add(
                MakeShared<Gs2::UE5::Distributor::Model::FEzBatchRequestPayload>()
                ->WithService(TOptional<FString>("exchange"))
                ->WithMethod(TOptional<FString>("describeRateModels"))
                ->WithRequest(TOptional<FString>("{\"namespaceName\": \"namespace-0001\"}"))
            );
            return v;
        }() // requestPayloads
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();
    const auto Results = Result->Results;

freezeMasterData

現時点のマスターデータを固定化する

現在のマスターデータのスナップショットを作成し、以降のトランザクションがこの固定バージョンを使うようにします。マスターデータが後で更新されても影響を受けません。
整合性を保つために便利です。たとえば、プレイヤーがクエストを開始した場合、報酬はクリア時ではなく開始時のマスターデータに基づくべきです。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSessionGameSession
GameSession

Result

説明
newContextStackstringマスターデータを固定する時刻を記録したコンテキスト

実装例

    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Distribute(
    );
    var result = await domain.FreezeMasterDataAsync(
        accessToken: null
    );
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Distribute(
    );
    var future = domain.FreezeMasterDataFuture(
        accessToken: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Distributor->Namespace(
        "namespace-0001" // namespaceName
    )->Distribute(
    );
    const auto Future = Domain->FreezeMasterData(
        nullptr // accessToken
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

freezeMasterDataBySignedTimestamp

署名付きタイムスタンプの時点でマスターデータを固定化する

署名付きタイムスタンプを使って、特定の時点のマスターデータを固定化します。
FreezeMasterData(「今」の時点で固定)とは異なり、正確な時刻を指定できます。固定する時点がサーバー側で事前に決まっている場合などに使います。
署名付きタイムスタンプは SignFreezeMasterDataTimestamp で発行できます。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSessionGameSession
GameSession
bodystring
~ 1024文字ボディ
signaturestring
~ 256文字署名
keyIdstring
~ 1024文字署名計算に使用した GS2-Key の暗号鍵 GRN

Result

説明
newContextStackstringマスターデータを固定する時刻を記録したコンテキスト

実装例

    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Distribute(
    );
    var result = await domain.FreezeMasterDataBySignedTimestampAsync(
        accessToken: null,
        body: "body",
        signature: "signature",
        keyId: "key-0001"
    );
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Distribute(
    );
    var future = domain.FreezeMasterDataBySignedTimestampFuture(
        accessToken: null,
        body: "body",
        signature: "signature",
        keyId: "key-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Distributor->Namespace(
        "namespace-0001" // namespaceName
    )->Distribute(
    );
    const auto Future = Domain->FreezeMasterDataBySignedTimestamp(
        nullptr, // accessToken
        "body", // body
        "signature", // signature
        "key-0001" // keyId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

runStampSheet

入手アクションを実行する(リソースの付与)

トランザクションの一部として、プレイヤーにリソースを付与する入手アクションを1つ実行します。
たとえば、アイテムの付与、経験値の加算、ゲーム内通貨の付与などです。
通常は直接呼び出す必要はありません。トランザクション処理時に SDK が自動的に処理します。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
stampSheetstring
~ 5242880文字トランザクション
keyIdstring
~ 1024文字暗号鍵 GRN
contextStackstring~ 32768文字リクエストコンテキスト

Result

説明
statusCodeintステータスコード
resultstringレスポンス内容

実装例

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません

runStampSheetExpress

トランザクション内の全アクションを一括実行する(エクスプレスモード)

トランザクションの検証・消費・入手アクションを1回の API 呼び出しでまとめて実行します。個別に実行するより高速です。
エラーが発生した場合は再度呼び出してください。消費アクションが重複して適用されない仕組みがあるため、安全にリトライできます。
通常は直接呼び出す必要はありません。トランザクション処理時に SDK が自動的に処理します。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
stampSheetstring
~ 5242880文字トランザクション
keyIdstring
~ 1024文字暗号鍵 GRN

Result

説明
verifyTaskResultCodesList<int>検証アクションの実行ステータスコード
verifyTaskResultsList<string>検証アクションの実行結果
taskResultCodesList<int>消費アクションの実行ステータスコード
taskResultsList<string>消費アクションの実行結果
sheetResultCodeint入手アクションの実行ステータスコード
sheetResultstring入手アクションの実行結果レスポンス内容

実装例

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません

runStampSheetExpressWithoutNamespace

ネームスペースなしでトランザクション内の全アクションを一括実行する(エクスプレスモード)

エクスプレスモードの高速性と、ネームスペース省略の軽量さを組み合わせたバージョンです。
検証・消費・入手アクションを1回の呼び出しでまとめて実行します。重複実行排除の仕組みがあるため、安全にリトライできます。
トレードオフ: トランザクションログが GS2-Log に記録されない、溢れ処理が使えないなどの制約があります。
通常は直接呼び出す必要はありません。トランザクション処理時に SDK が自動的に処理します。

Request

有効化条件必須デフォルト値の制限説明
stampSheetstring
~ 5242880文字トランザクション
keyIdstring
~ 1024文字暗号鍵 GRN

Result

説明
verifyTaskResultCodesList<int>検証アクションの実行ステータスコード
verifyTaskResultsList<string>検証アクションの実行結果
taskResultCodesList<int>消費アクションの実行ステータスコード
taskResultsList<string>消費アクションの実行結果
sheetResultCodeint入手アクションの実行ステータスコード
sheetResultstring入手アクションの実行結果レスポンス内容

実装例

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません

runStampSheetWithoutNamespace

ネームスペースを指定せずに入手アクションを実行する

ネームスペースの指定を省略した、RunStampSheet の軽量バージョンです。
オーバーヘッドが減りますが、トランザクションログが GS2-Log に記録されない、溢れ処理が使えないなどのトレードオフがあります。
通常は直接呼び出す必要はありません。トランザクション処理時に SDK が自動的に処理します。

Request

有効化条件必須デフォルト値の制限説明
stampSheetstring
~ 5242880文字トランザクション
keyIdstring
~ 1024文字暗号鍵 GRN
contextStackstring~ 32768文字リクエストコンテキスト

Result

説明
statusCodeintステータスコード
resultstringレスポンス内容

実装例

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません

runStampTask

消費アクションを実行する(リソースの消費)

トランザクションの一部として、プレイヤーからリソースを差し引く消費アクションを1つ実行します。
たとえば、ゲーム内通貨の支払い、スタミナの消費、アイテムの使用などです。
通常は直接呼び出す必要はありません。トランザクション処理時に SDK が自動的に処理します。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
stampTaskstring
~ 5242880文字消費アクション
keyIdstring
~ 1024文字暗号鍵 GRN
contextStackstring~ 32768文字リクエストコンテキスト

Result

説明
contextStackstringタスクの実行結果を反映したコンテキストスタック
statusCodeintステータスコード
resultstringレスポンス内容

実装例

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません

runStampTaskWithoutNamespace

ネームスペースを指定せずに消費アクションを実行する

ネームスペースの指定を省略した、RunStampTask の軽量バージョンです。
オーバーヘッドが減りますが、トランザクションログが GS2-Log に記録されない、溢れ処理が使えないなどのトレードオフがあります。
通常は直接呼び出す必要はありません。トランザクション処理時に SDK が自動的に処理します。

Request

有効化条件必須デフォルト値の制限説明
stampTaskstring
~ 5242880文字消費アクション
keyIdstring
~ 1024文字暗号鍵 GRN
contextStackstring~ 32768文字リクエストコンテキスト

Result

説明
contextStackstringタスクの実行結果を反映したコンテキストスタック
statusCodeintステータスコード
resultstringレスポンス内容

実装例

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません

runVerifyTask

検証アクションを実行する(前提条件のチェック)

トランザクションが進む前に前提条件が満たされているかどうかをチェックする、検証アクションを1つ実行します。
たとえば、プレイヤーが必要なアイテムを持っているか、特定のレベルに達しているかなどの検証です。
通常は直接呼び出す必要はありません。トランザクション処理時に SDK が自動的に処理します。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
verifyTaskstring
~ 5242880文字検証アクション
keyIdstring
~ 1024文字暗号鍵 GRN
contextStackstring~ 32768文字リクエストコンテキスト

Result

説明
contextStackstringタスクの実行結果を反映したコンテキストスタック
statusCodeintステータスコード
resultstringレスポンス内容

実装例

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません

runVerifyTaskWithoutNamespace

ネームスペースを指定せずに検証アクションを実行する

ネームスペースの指定を省略した、RunVerifyTask の軽量バージョンです。
オーバーヘッドが減りますが、トランザクションログが GS2-Log に記録されない、溢れ処理が使えないなどのトレードオフがあります。
通常は直接呼び出す必要はありません。トランザクション処理時に SDK が自動的に処理します。

Request

有効化条件必須デフォルト値の制限説明
verifyTaskstring
~ 5242880文字検証アクション
keyIdstring
~ 1024文字暗号鍵 GRN
contextStackstring~ 32768文字リクエストコンテキスト

Result

説明
contextStackstringタスクの実行結果を反映したコンテキストスタック
statusCodeintステータスコード
resultstringレスポンス内容

実装例

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません

setDefaultConfig

トランザクションのデフォルト設定値を登録する

トランザクション発行時に使用されるデフォルトの Config 値を保持したコンテキストを準備します。
Config はトランザクションのアクションに埋め込める変数として機能します。たとえば、スロット名や数量の指定などに使います。
ここでデフォルト値を設定しておけば、トランザクション発行のたびに毎回指定する必要がなくなります。

Request

有効化条件必須デフォルト値の制限説明
gameSessionGameSession
GameSession
configList<EzConfig>
1 ~ 1000 itemsトランザクションのプレースホルダの適用する設定値

Result

説明
newContextStackstringデフォルトコンフィグを反映するためのコンテキストスタック

実装例

    var domain = gs2.Distributor.Namespace(
        namespaceName: null
    );
    var result = await domain.SetDefaultConfigAsync(
        accessToken: null,
        config: new List<Gs2.Unity.Gs2Distributor.Model.EzConfig> {
            new Gs2.Unity.Gs2Distributor.Model.EzConfig() {
                Key = "key-0001",
                Value = "value-0001",
            },
            new Gs2.Unity.Gs2Distributor.Model.EzConfig() {
                Key = "key-0002",
                Value = "value-0002",
            },
        }
    );
    var domain = gs2.Distributor.Namespace(
        namespaceName: null
    );
    var future = domain.SetDefaultConfigFuture(
        accessToken: null,
        config: new List<Gs2.Unity.Gs2Distributor.Model.EzConfig> {
            new Gs2.Unity.Gs2Distributor.Model.EzConfig() {
                Key = "key-0001",
                Value = "value-0001",
            },
            new Gs2.Unity.Gs2Distributor.Model.EzConfig() {
                Key = "key-0002",
                Value = "value-0002",
            },
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Distributor->Namespace(
        nullptr // namespaceName
    );
    const auto Future = Domain->SetDefaultConfig(
        nullptr, // accessToken
        []
        {
            auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Distributor::Model::FEzConfig>>>();
            v->Add(
                MakeShared<Gs2::UE5::Distributor::Model::FEzConfig>()
                ->WithKey(TOptional<FString>("key-0001"))
                ->WithValue(TOptional<FString>("value-0001"))
            );
            v->Add(
                MakeShared<Gs2::UE5::Distributor::Model::FEzConfig>()
                ->WithKey(TOptional<FString>("key-0002"))
                ->WithValue(TOptional<FString>("value-0002"))
            );
            return v;
        }() // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

getStampSheetResult

完了したトランザクションの結果を取得する(レガシー)

トランザクションIDを指定して、過去に完了したトランザクションの実行結果を取得します。
結果には、実行された各アクション(検証・消費・入手)のステータスとレスポンスが含まれます。
トランザクションで何が起きたかを確認するために使います。たとえば、実際にどの報酬が付与されたかの確認などに便利です。

この API はレガシー(スタンプシート方式)のトランザクション結果を取得します。新しいトランザクション形式の場合は GetTransactionResult を使用してください。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSessionGameSession
GameSession
transactionIdstring
36 ~ 36文字トランザクションID
このトランザクションを一意に識別する UUID です。トランザクションとその実行結果、および連鎖する後続トランザクションの関連付けに使用されます。

Result

説明
itemEzStampSheetResultトランザクションの実行結果

実装例

    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).StampSheetResult(
        transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).StampSheetResult(
        transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Distributor->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->StampSheetResult(
        "cc1985c3-54f0-4fc3-b295-dc30214284ec" // transactionId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
値の変更イベントハンドリング
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).StampSheetResult(
        transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).StampSheetResult(
        transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Distributor->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->StampSheetResult(
        "cc1985c3-54f0-4fc3-b295-dc30214284ec" // transactionId
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Distributor::Model::FStampSheetResult> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

getTransactionResult

完了したトランザクションの結果を取得する

トランザクションIDを指定して、過去に完了したトランザクションの実行結果を取得します。
結果には、実行された各アクション(検証・消費・入手)のステータスとレスポンスが含まれます。
トランザクションで何が起きたかを確認するために使います。たとえば、実際にどの報酬が付与されたか、どのリソースが消費されたかの確認に便利です。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSessionGameSession
GameSession
transactionIdstring
36 ~ 36文字トランザクションID
この分散トランザクションを一意に識別する UUID です。実行結果の検索や、元の API リクエストとの関連付けに使用されます。

Result

説明
itemEzTransactionResultトランザクションの実行結果

実装例

    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TransactionResult(
        transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TransactionResult(
        transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Distributor->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TransactionResult(
        "cc1985c3-54f0-4fc3-b295-dc30214284ec" // transactionId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
値の変更イベントハンドリング
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TransactionResult(
        transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    var domain = gs2.Distributor.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TransactionResult(
        transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Distributor->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TransactionResult(
        "cc1985c3-54f0-4fc3-b295-dc30214284ec" // transactionId
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Distributor::Model::FTransactionResult> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

イベントハンドラ

OnAutoRunStampSheetNotification

トランザクションの自動実行が完了した際に通知

名前説明
namespaceNamestringネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userIdstringユーザーID
transactionIdstringトランザクションID
このトランザクションを一意に識別する UUID です。トランザクションとその実行結果、および連鎖する後続トランザクションの関連付けに使用されます。

実装例

    gs2.Distributor.OnAutoRunStampSheetNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var transactionId = notification.TransactionId;
    };
    gs2.Distributor.OnAutoRunStampSheetNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var transactionId = notification.TransactionId;
    };
    Gs2->Distributor->OnAutoRunStampSheetNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto UserId = Notification->UserIdValue;
        const auto TransactionId = Notification->TransactionIdValue;
    });

OnAutoRunTransactionNotification

トランザクションの自動実行が完了した際に通知

名前説明
namespaceNamestringネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userIdstringユーザーID
transactionIdstringトランザクションID
この分散トランザクションを一意に識別する UUID です。実行結果の検索や、元の API リクエストとの関連付けに使用されます。

実装例

    gs2.Distributor.OnAutoRunTransactionNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var transactionId = notification.TransactionId;
    };
    gs2.Distributor.OnAutoRunTransactionNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var transactionId = notification.TransactionId;
    };
    Gs2->Distributor->OnAutoRunTransactionNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto UserId = Notification->UserIdValue;
        const auto TransactionId = Notification->TransactionIdValue;
    });