> For the complete documentation index, see [llms.txt](/llms.txt)

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

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



## モデル

### EzAwait

交換待機<br>

報酬を受け取る前に実時間の経過が必要な交換の実行状態を表します。<br>
`timingType` が `await` の交換レートに対してプレイヤーが交換を開始した際に作成され、報酬が受け取れるようになるまでの待機期間を追跡します。<br>

対価は交換を開始した時点で消費され、報酬の入手だけが先送りされます。<br>
クラフトや施設の建設のように、時間そのものを対価とする仕組みに使用するモデルです。<br>

`acquirableAt` は `exchangedAt` + 交換レートの `lockTime` - `skipSeconds` として計算され、現在時刻がこれを過ぎると報酬を受け取れるようになります。<br>
`count` を指定すると複数回の交換を1つの待機にまとめられ、その場合は対価と報酬の両方が乗算されます。<br>

待ち時間はスキップによって短縮でき、完全にスキップする方法のほか、分数を指定する方法、全体の待機時間に対する割合を指定する方法、残りの待機時間に対する割合を指定する方法の4種類があります。<br>
スキップした分は `skipSeconds` に積み上がり `acquirableAt` を前倒しします。これによって、リソースを支払って待ち時間を短縮する仕組みを実装できます。<br>

`config` には、報酬を配布する際にトランザクションのプレースホルダ変数へ適用する値を保持します。値は交換の開始時点で確定します。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string |  | ✓ |  |  ~ 128文字 | ユーザーID |
| rateName | string |  | ✓ |  |  ~ 128文字 | 交換レートモデル名<br>交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| name | string |  | ✓ | UUID |  ~ 36文字 | 交換待機の名前<br>交換待機の一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、交換待機を識別するために使用されます。 |
| skipSeconds | int |  |  | 0 | 0 ~ 2147483646 | スキップ秒数<br>待ち時間から差し引く秒数です。スキップ秒数が適用されると、acquirableAt のタイムスタンプがこの分だけ前倒しされます。プレイヤーがリソースを支払って待ち時間を短縮する仕組みを実装するために使用されます。 |
| config | [List&lt;EzConfig&gt;](#ezconfig) |  |  | [] | 0 ~ 32 items | 報酬取得時に適用するデフォルト設定値<br>待機完了時に報酬が配布される際にトランザクションのプレースホルダ変数として使用されるキーと値のペアです。これらの値は交換開始時に設定され、入手アクションのトランザクションパラメータに適用されます。 |
| exchangedAt | long |  |  |  |  | 交換時間<br>交換が開始され待機が作成されたタイムスタンプです。報酬が利用可能になる時刻を計算するための基準時刻として使用されます（acquirableAt = exchangedAt + lockTime - skipSeconds）。 |
| acquirableAt | long |  |  |  |  | 報酬を受け取れるようになる時間<br>待機期間が満了し報酬が受け取り可能になるタイムスタンプです。exchangedAt + lockTime - skipSeconds として計算されます。現在時刻がこのタイムスタンプを過ぎると、プレイヤーは取得 API を呼び出せるようになります。 |

**関連するメソッド:**
getAwait - 特定の待機中の時間制交換を取得する
listAwaits - 待機中の時間制交換の一覧を取得する
acquire - 完了した時間制交換の報酬を受け取る
deleteAwait - 待機中の時間制交換をキャンセルする


---

### EzRateModel

交換レートモデル<br>

交換レートモデルはリソースとリソースを交換する際に使用するレートを定義するエンティティです。<br>

直ちに交換できるレートだけでなく、現実時間で一定時間経過したのちに交換できるレートを設定できます。<br>
現実時間での時間経過が必要な交換レートには、更に即時交換を実行するために必要なリソースを定義することが可能です。<br>

1つの交換レートは、検証アクション・消費アクション・入手アクションで構成されます。<br>
検証アクションは交換を実行する前の事前条件チェックで、1つでも失敗すると何も消費せずに交換が中止されます。<br>
消費アクションには交換の対価を、入手アクションには交換で受け取る報酬を定義します。<br>
検証アクションと消費アクションはそれぞれ最大10件、入手アクションは最大100件まで設定できます。<br>

`timingType` で報酬を配送するタイミングを選択します。<br>
`immediate` は交換の実行と同時に報酬を配送します。<br>
`await` は対価を消費したうえで報酬の入手を先送りし、`lockTime` に指定した分数が経過してから受け取れるようになります。この待機状態は交換待機として保持され、スキップによって待ち時間を短縮できます。<br>

`lockTime` は `timingType` が `await` の場合にのみ適用されます。<br>
クラフトや施設の建設のように時間そのものを対価に含める仕組みには `await` を、アイテムの売却や進化素材の変換のように常設の交換には `immediate` を使用します。<br>

購入するたびに価格が上がるレートを実現する場合は、このモデルではなくコスト上昇型交換レートモデル (IncrementalRateModel) を使用します。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | 交換レートモデル名<br>交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| timingType | 文字列列挙型<br>enum {<br>"immediate",<br>"await"<br>}<br> |  |  | "immediate" |  | 交換の種類<br>交換実行後に報酬がいつ配送されるかを決定します。`immediate` は交換実行時に即座に報酬を配送します。`await` は報酬を受け取る前に実時間の経過が必要で、待機期間（例: クラフト時間）を設けます。immediate: 即時 / await: 現実時間の経過待ち /  |
| lockTime | int | {timingType} == "await" | ✓※ |  | 0 ~ 538214400 | 交換実行から実際に報酬を受け取れるようになるまでの待ち時間（分）<br>timingType が `await` の場合にのみ適用されます。交換が開始されてからプレイヤーが報酬を受け取れるようになるまでに経過する必要がある実時間の分数を指定します。待ち時間はスキップ機能を使用して短縮できます。<br><br>※ timingType が "await" であれば 必須 |
| verifyActions | [List&lt;EzVerifyAction&gt;](#ezverifyaction) |  |  | [] | 0 ~ 10 items | 検証アクションリスト<br>交換が実行される前にすべてパスする必要がある事前条件チェックです。いずれかの検証アクションが失敗すると、リソースを消費せずに交換が中止されます。レベル要件やインベントリ容量などの条件を強制するために使用されます。 |
| consumeActions | [List&lt;EzConsumeAction&gt;](#ezconsumeaction) |  |  | [] | 0 ~ 10 items | 消費アクションリスト<br>この交換を実行するためにプレイヤーが支払う必要があるリソース（コスト）を定義します。複数の消費アクションを指定でき、ゴールドとアイテムの両方を必要とするような複雑な交換コストを実現できます。これらのアクションは分散トランザクション内の消費アクションとして実行されます。 |
| acquireActions | [List&lt;EzAcquireAction&gt;](#ezacquireaction) |  |  | [] | 0 ~ 100 items | 入手アクションリスト<br>交換完了時にプレイヤーが受け取るリソース（報酬）を定義します。複数の入手アクションを指定して、さまざまなリソースタイプを同時に付与できます。これらのアクションは分散トランザクション内の入手アクションとして実行されます。 |

**関連するメソッド:**
getRateModel - 名前を指定して交換レートモデルを取得する
listRateModels - 交換レートモデルの一覧を取得する
exchange - 交換を実行する


---

### EzIncrementalRateModel

コスト上昇型交換レートモデル<br>

通常の交換レートは常に一定のレートでの交換を提供します。<br>
上昇型交換レートでは、交換回数に応じてコストが上昇していくレートを定義することができます。<br>
例えば、1回目の交換では 1:1 で交換できるが、2回目の交換では 2:1 で交換できる、といったレートを定義することができます。<br>
このようなレートを定義することで、プレイヤーがゲームを進めることで得られるリソースの価値を上げることができます。<br>

交換回数は現実時間の経過でリセットすることができます。<br>
この機能を利用することで、毎日あるいは毎週交換に必要なコストをリセットすることができます。<br>

`consumeAction` には交換で消費する対価を1つ定義し、その消費数量がそれまでの交換回数に応じて再計算されます。<br>
コストの上昇のしかたは `calculateType` で選択します。`linear` は `baseValue` +（`coefficientValue` × 交換回数）、`power` は `coefficientValue` ×（交換回数 + 1）^2 として計算します。<br>
`gs2_script` を選ぶと `calculateScriptId` に指定した GS2-Script に計算を委譲するため、任意のロジックでコストを決定できます。<br>

交換回数は `exchangeCountId` で参照する GS2-Limit の回数制限モデルによって管理されます。<br>
GS2-Limit のカウンターであるため、コストを初期値に戻すのはそこで設定したリセットタイミングです。これによって毎日あるいは毎週のリセットを実現します。<br>

`maximumExchangeCount` にはユーザーが交換を実行できる最大回数を設定します。<br>
交換回数がこの上限に達すると、GS2-Limit のカウンターがリセットされるまで以降の交換は拒否されます。<br>

`acquireActions` には交換で受け取る報酬を定義し、最大100件まで設定できます。<br>
交換レートモデル (RateModel) とは異なり、このモデルには検証アクションと待機時間がなく、報酬は常に即時に配送されます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | コスト上昇型交換レートモデルの名前<br>コスト上昇型交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| calculateType | 文字列列挙型<br>enum {<br>"linear",<br>"power",<br>"gs2_script"<br>}<br> |  | ✓ |  |  | コスト上昇量の計算方式<br>交換回数に応じてコストがどのように上昇するかを決定します。`linear` はコストを baseValue +（coefficientValue × 交換回数）として計算します。`power` はコストを coefficientValue ×（交換回数 + 1）^2 として計算します。`gs2_script` は任意のロジックのためにカスタム GS2-Script に計算を委任します。linear: ベース値 + (係数 * 交換回数) / power: 係数 * (交換回数 + 1) ^ 2 / gs2_script: GS2-Script による任意のロジック /  |
| consumeAction | [EzConsumeAction](#ezconsumeaction) |  | ✓ |  |  | 消費アクション（数量/値は自動的に上書きされます）<br>交換のコストとして消費されるリソースの種類を定義します。実際の数量は交換回数と計算方式（線形、べき乗、スクリプト）に基づいて動的に計算されます。アクションの種類と対象リソースのみ指定すればよく、数量フィールドは自動的に上書きされます。 |
| baseValue | long | {calculateType} == "linear" | ✓※ |  | 0 ~ 9223372036854775805 | ベース値<br>`linear` 計算方式を使用する場合の初回交換時の基本コストです。合計コストは baseValue +（coefficientValue × 交換回数）として計算されます。<br><br>※ calculateType が "linear" であれば 必須 |
| coefficientValue | long | {calculateType} in ["linear", "power"] | ✓※ |  | 0 ~ 9223372036854775805 | 係数<br>交換回数に応じてコストがどれだけ速く上昇するかを制御する乗数です。`linear` モードでは、各交換でこの値がコストに加算されます。`power` モードでは、コストは coefficientValue ×（交換回数 + 1）^2 として計算されます。<br><br>※ calculateType が "linear","power"であれば 必須 |
| exchangeCountId | string |  | ✓ |  |  ~ 1024文字 | 交換実行回数を管理する GS2-Limit の回数制限モデル GRN<br>各ユーザーがこのコスト上昇型交換を何回実行したかを追跡する GS2-Limit の回数制限モデルを参照します。カウントは上昇するコストの計算に使用され、GS2-Limit のリセットタイミングを使用して定期的（例: 毎日または毎週）にリセットできます。 |
| maximumExchangeCount | int |  |  | 2147483646 | 0 ~ 2147483646 | 交換回数の上限<br>ユーザーがこのコスト上昇型交換を実行できる最大回数です。交換回数がこの上限に達すると、GS2-Limit によるカウントリセットまでそれ以降の交換が拒否されます。 |
| acquireActions | [List&lt;EzAcquireAction&gt;](#ezacquireaction) |  |  | [] | 0 ~ 100 items | 入手アクションリスト<br>コスト上昇型交換の完了時にプレイヤーが受け取るリソース（報酬）を定義します。報酬は交換回数に関わらず一定で、コストのみが交換ごとに増加します。 |

**関連するメソッド:**
getIncrementalRateModel - 名前を指定してコスト上昇型交換レートモデルを取得する
listIncrementalRateModels - コスト上昇型交換レートモデルの一覧を取得する
incrementalExchange - コスト上昇型の交換を実行する


---

### EzConfig

コンフィグ設定<br>

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string |  | ✓ |  |  ~ 64文字 | 名前 |
| value | string |  |  |  |  ~ 51200文字 | 値 |

**関連するメソッド:**
exchange - 交換を実行する
incrementalExchange - コスト上昇型の交換を実行する


**関連するモデル:**
EzAwait - 交換待機



---

### EzAcquireAction

入手アクション

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


**関連するモデル:**
EzRateModel - 交換レートモデル
EzIncrementalRateModel - コスト上昇型交換レートモデル



---

### EzConsumeAction

消費アクション

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


**関連するモデル:**
EzRateModel - 交換レートモデル
EzIncrementalRateModel - コスト上昇型交換レートモデル



---

### EzVerifyAction

検証アクション

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


**関連するモデル:**
EzRateModel - 交換レートモデル



---

### EzVerifyActionResult

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 検証アクションで実行するアクションの種類 |
| verifyRequest | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int |  |  |  | 0 ~ 999 | ステータスコード |
| verifyResult | string |  |  |  |  ~ 1048576文字 | 結果内容 |


**関連するモデル:**
EzTransactionResult - トランザクション実行結果



---

### EzConsumeActionResult

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 消費アクションで実行するアクションの種類 |
| consumeRequest | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int |  |  |  | 0 ~ 999 | ステータスコード |
| consumeResult | string |  |  |  |  ~ 1048576文字 | 結果内容 |


**関連するモデル:**
EzTransactionResult - トランザクション実行結果



---

### EzAcquireActionResult

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 入手アクションで実行するアクションの種類 |
| acquireRequest | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int |  |  |  | 0 ~ 999 | ステータスコード |
| acquireResult | string |  |  |  |  ~ 1048576文字 | 結果内容 |


**関連するモデル:**
EzTransactionResult - トランザクション実行結果



---

### EzTransactionResult

トランザクション実行結果<br>

サーバーサイドでのトランザクションの自動実行機能を利用して実行されたトランザクションの実行結果

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| transactionId | string |  | ✓ |  | 36 ~ 36文字 | トランザクションID |
| verifyResults | [List&lt;EzVerifyActionResult&gt;](#ezverifyactionresult) |  |  |  | 0 ~ 10 items | 検証アクションの実行結果リスト |
| consumeResults | [List&lt;EzConsumeActionResult&gt;](#ezconsumeactionresult) |  |  | [] | 0 ~ 10 items | 消費アクションの実行結果リスト |
| acquireResults | [List&lt;EzAcquireActionResult&gt;](#ezacquireactionresult) |  |  | [] | 0 ~ 100 items | 入手アクションの実行結果リスト |

**関連するメソッド:**
acquire - 完了した時間制交換の報酬を受け取る
exchange - 交換を実行する
incrementalExchange - コスト上昇型の交換を実行する


---

## メソッド

### acquire

完了した時間制交換の報酬を受け取る<br>

必要な待機時間が経過した時間制交換の報酬を受け取ります。<br>
待機時間がまだ経過していない場合、この呼び出しは失敗します。事前に GetAwait で残り時間を確認してください。<br>
受け取ると待機レコードは消費され、プレイヤーはレートモデルで定義された報酬を受け取ります。<br>
たとえば、「鉄の剣」の製作で3時間待った後にこれを呼ぶと、プレイヤーに剣が付与されます。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| awaitName | string |  | ✓| UUID |  ~ 36文字 | 交換待機の名前<br>交換待機の一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、交換待機を識別するために使用されます。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzAwait](#ezawait) | 交換待機|
| transactionId | string | 発行されたトランザクションID|
| stampSheet | string | 報酬取得処理の実行に使用するスタンプシート|
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN|
| autoRunStampSheet | bool | トランザクションの自動実行が有効か|
| atomicCommit | bool | トランザクションをアトミックにコミットするか|
| transaction | string | 発行されたトランザクション|
| transactionResult | [EzTransactionResult](#eztransactionresult) | トランザクション実行結果|

#### Error

このAPIには特別な例外が定義されています。<br>
GS2-SDK for Game Engine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。<br>
一般的なエラーの種類や、ハンドリング方法は [こちら]() のドキュメントを参考にしてください。

| 型 | 基底クラス | 説明 |
| --- | --- | --- |
| AwaitNotReadyException | BadRequestException | 交換の待ち時間がまだ経過していません。 |

#### 実装例




**Unity (UniTask)**
```csharp

try {
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var result = await domain.AcquireAsync(
    );
} catch(Gs2.Gs2Exchange.Exception.AwaitNotReadyException e) {
    // The waiting time for the exchange has not yet elapsed.
}
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var future = domain.AcquireFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Exchange.Exception.AwaitNotReadyException)
        {
            // The waiting time for the exchange has not yet elapsed.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Await(
        "await-0001" // awaitName
    );
    const auto Future = Domain->Acquire(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Exchange::Error::FAwaitNotReadyError::Class))
        {
            // The waiting time for the exchange has not yet elapsed.
        }
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).me(game_session).await_(
        "await-0001"
    )

var async_result = await domain.acquire(
)
if async_result.error != null:
    if async_result.error is Gs2ExchangeAwaitNotReadyException:
        # 交換の待ち時間がまだ経過していません。
        pass
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### deleteAwait

待機中の時間制交換をキャンセルする<br>

待機中の交換待機レコードを削除し、交換をキャンセルします。<br>
報酬は付与されず、交換開始時に支払ったリソースも返還されません。<br>
プレイヤーが製作中や建設中の注文をキャンセルしたい場合に使います。コストが戻らないため、確認ダイアログを表示することをおすすめします。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| awaitName | string |  | ✓| UUID |  ~ 36文字 | 交換待機の名前<br>交換待機の一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、交換待機を識別するために使用されます。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzAwait](#ezawait) | 交換待機|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var result = await domain.DeleteAwaitAsync(
    );

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var future = domain.DeleteAwaitFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Await(
        "await-0001" // awaitName
    );
    const auto Future = Domain->DeleteAwait(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).me(game_session).await_(
        "await-0001"
    )

var async_result = await domain.delete_await(
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### getAwait

特定の待機中の時間制交換を取得する<br>

特定の交換待機レコードの詳細を取得します。<br>
取得できる情報には、交換タイプ、リクエストした数量、開始日時、残りの待機時間が含まれます。<br>
特定の待機中交換の詳細画面を表示する際に使います。たとえば、「鉄の剣を製作中… 残り2時間30分」のような表示に便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| awaitName | string |  | ✓| UUID |  ~ 36文字 | 交換待機の名前<br>交換待機の一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、交換待機を識別するために使用されます。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzAwait](#ezawait) | 交換待機|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Await(
        "await-0001" // awaitName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).me(game_session).await_(
        "await-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Await(
        "await-0001" // awaitName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Exchange::Model::FAwait> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

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

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).me(game_session).await_(
        "await-0001"
    )

# イベントハンドリングを開始
var callback_id = domain.subscribe_model(func(value):
    # 値が変化した時に呼び出される
    # value には変更後の値が渡されます
    pass
)

# イベントハンドリングを停止
domain.unsubscribe_model(callback_id)

```


**⚠️ Warning**

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

---

### listAwaits

待機中の時間制交換の一覧を取得する<br>

プレイヤーの交換待機レコードを取得します。報酬を受け取る前に待機が必要な交換（クラフトや建設のような仕組み）の一覧です。<br>
レート名を指定して、特定の交換タイプの待機のみを表示することもできます。<br>
「製作中のアイテム」や「進行中」のリストを構築するのに使います。プレイヤーが何を待っていて、あとどのくらいかかるかを表示できます。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rateName | string |  | |  |  ~ 128文字 | 交換レートモデル名<br>交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| pageToken | string |  | |  |  ~ 1024文字 | データの取得を開始する位置を指定するトークン |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzAwait&gt;](#ezawait) | 交換待機のリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.AwaitsAsync(
        rateName: "material_n_to_r"
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Awaits(
        rateName: "material_n_to_r"
    );
    List<EzAwait> items = new List<EzAwait>();
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Awaits(
        "material_n_to_r" // rateName
    );
    TArray<Gs2::UE5::Exchange::Model::FEzAwaitPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeAwaits(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeAwaits(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeAwaits(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeAwaits(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeAwaits(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

```


**⚠️ Warning**

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

---

### getRateModel

名前を指定して交換レートモデルを取得する<br>

名前を指定して、交換レートモデルを1件取得します。<br>
取得できる情報には、プレイヤーが支払うもの、受け取るもの、即時交換か待機が必要かが含まれます。<br>
特定の交換の詳細を表示する際に使います。たとえば、ショップのアイテム詳細画面で「コスト: ゴールド100 → 報酬: 回復ポーション1個」のように表示するのに便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rateName | string |  | ✓|  |  ~ 128文字 | 交換レートモデル名<br>交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzRateModel](#ezratemodel) | 交換レートモデル|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "character-level"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "character-level"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->RateModel(
        "character-level" // rateName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).rate_model(
        "character-level"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "character-level"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "character-level"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->RateModel(
        "character-level" // rateName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Exchange::Model::FRateModel> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

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

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).rate_model(
        "character-level"
    )

# イベントハンドリングを開始
var callback_id = domain.subscribe_model(func(value):
    # 値が変化した時に呼び出される
    # value には変更後の値が渡されます
    pass
)

# イベントハンドリングを停止
domain.unsubscribe_model(callback_id)

```


**⚠️ Warning**

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

---

### listRateModels

交換レートモデルの一覧を取得する<br>

このネームスペースに登録されているすべての交換レートモデルを取得します。<br>
レートモデルは交換のレシピを定義します。プレイヤーが何を支払い（例: ゴールド100枚）、何を受け取るか（例: 回復ポーション1個）を設定します。<br>
タイミングには2種類あります。「即時」交換はすぐに完了し、「待機」交換はプレイヤーが一定時間待ってから報酬を受け取ります（クラフトのような仕組み）。<br>
ショップやクラフトUIを構築する際に、プレイヤーに利用可能な交換オプションを表示するのに使います。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzRateModel&gt;](#ezratemodel) | 交換レートモデルのリスト|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.RateModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.RateModels(
    );
    List<EzRateModel> items = new List<EzRateModel>();
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->RateModels(
    );
    TArray<Gs2::UE5::Exchange::Model::FEzRateModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


##### 値の変更イベントハンドリング




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

    // イベントハンドリングを停止
    domain.UnsubscribeRateModels(callbackId);

```

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

    // イベントハンドリングを停止
    domain.UnsubscribeRateModels(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeRateModels(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

```


**⚠️ Warning**

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

---

### getIncrementalRateModel

名前を指定してコスト上昇型交換レートモデルを取得する<br>

名前を指定して、コスト上昇型交換レートモデルを1件取得します。<br>
取得できる情報には、コスト計算方法（線形計算式またはカスタムスクリプト）、基本コスト、交換ごとのコスト増加量、最大交換回数、プレイヤーが受け取るものが含まれます。<br>
特定のコスト上昇型交換の詳細を表示する際に使います。たとえば、ショップ画面で「スタミナ回復: ジェム30個（本日3回目、最大5回）」のように表示するのに便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rateName | string |  | ✓|  |  ~ 128文字 | コスト上昇型交換レートモデルの名前<br>コスト上昇型交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzIncrementalRateModel](#ezincrementalratemodel) | コスト上昇型交換レートモデル|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).IncrementalRateModel(
        rateName: "character-level"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).IncrementalRateModel(
        rateName: "character-level"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->IncrementalRateModel(
        "character-level" // rateName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).incremental_rate_model(
        "character-level"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).IncrementalRateModel(
        rateName: "character-level"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).IncrementalRateModel(
        rateName: "character-level"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->IncrementalRateModel(
        "character-level" // rateName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Exchange::Model::FIncrementalRateModel> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

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

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).incremental_rate_model(
        "character-level"
    )

# イベントハンドリングを開始
var callback_id = domain.subscribe_model(func(value):
    # 値が変化した時に呼び出される
    # value には変更後の値が渡されます
    pass
)

# イベントハンドリングを停止
domain.unsubscribe_model(callback_id)

```


**⚠️ Warning**

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

---

### listIncrementalRateModels

コスト上昇型交換レートモデルの一覧を取得する<br>

このネームスペースに登録されているすべてのコスト上昇型交換レートモデルを取得します。<br>
コスト上昇型モデルは、プレイヤーが使うたびに値段が上がる交換を定義します。たとえば、スタミナ回復1回目はジェム10個、2回目は20個、3回目は30個…というような仕組みです。<br>
コストの上昇は、シンプルな線形計算式（基本値 + 係数 × 回数）またはカスタムスクリプトで計算できます。<br>
利用可能なコスト上昇型交換と現在のコストを表示するUIを構築するのに使います。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzIncrementalRateModel&gt;](#ezincrementalratemodel) | コスト上昇型交換レートモデルのリスト|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.IncrementalRateModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.IncrementalRateModels(
    );
    List<EzIncrementalRateModel> items = new List<EzIncrementalRateModel>();
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->IncrementalRateModels(
    );
    TArray<Gs2::UE5::Exchange::Model::FEzIncrementalRateModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


##### 値の変更イベントハンドリング




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

    // イベントハンドリングを停止
    domain.UnsubscribeIncrementalRateModels(callbackId);

```

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

    // イベントハンドリングを停止
    domain.UnsubscribeIncrementalRateModels(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeIncrementalRateModels(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

```


**⚠️ Warning**

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

---

### exchange

交換を実行する<br>

指定した交換レートモデルに基づいてリソースを交換します。<br>
プレイヤーはレートモデルで定義されたコストを支払い、報酬を受け取ります。たとえば、ゴールド100枚を回復ポーション1個と交換するといった処理です。<br>
回数を指定して同じ交換をまとめて実行することもできます（例: ポーション5個をゴールド500枚で購入）。<br>
レートモデルが「待機」タイミングの場合、即時完了ではなく時間待機型の交換が開始されます（報酬の受け取りは Await 系 API を参照してください）。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rateName | string |  | ✓|  |  ~ 128文字 | 交換レートモデル名<br>交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| count | int |  | ✓|  | 1 ~ 1073741821 | 交換回数 |
| config | [List&lt;EzConfig&gt;](#ezconfig) |  | | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzRateModel](#ezratemodel) | 交換レートモデル|
| transactionId | string | 発行されたトランザクションID|
| stampSheet | string | 交換処理の実行に使用するスタンプシート|
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN|
| autoRunStampSheet | bool | トランザクションの自動実行が有効か|
| atomicCommit | bool | トランザクションをアトミックにコミットするか|
| transaction | string | 発行されたトランザクション|
| transactionResult | [EzTransactionResult](#eztransactionresult) | トランザクション実行結果|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Exchange(
    );
    var result = await domain.ExchangeAsync(
        rateName: "rate-0001",
        count: 1,
        config: null
    );
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Exchange(
    );
    var future = domain.ExchangeFuture(
        rateName: "rate-0001",
        count: 1,
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Exchange(
    );
    const auto Future = Domain->Exchange(
        "rate-0001", // rateName
        1 // count
        // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).me(game_session).exchange(
    )

var async_result = await domain.exchange(
    "rate-0001", # rate_name
    1, # count
    null # config
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### incrementalExchange

コスト上昇型の交換を実行する<br>

使うたびにコストが上がるレートモデルを使ってリソースを交換します。<br>
コストはプレイヤーがこれまでに何回交換したかに基づいて自動計算されます。たとえば、スタミナ回復1回目はジェム10個、2回目は20個…というように上がっていきます。<br>
回数を指定してまとめて交換することもできます。その場合、合計コストは各回の価格の合計になります。<br>
毎日のスタミナ回復、回数限定ショップ、繰り返し利用で値上がりさせたい仕組みに使います。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rateName | string |  | ✓|  |  ~ 128文字 | コスト上昇型交換レートモデルの名前<br>コスト上昇型交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| count | int |  | ✓|  | 1 ~ 1073741821 | 交換回数 |
| config | [List&lt;EzConfig&gt;](#ezconfig) |  | | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzIncrementalRateModel](#ezincrementalratemodel) | コスト上昇型交換レートモデル|
| transactionId | string | 発行されたトランザクションID|
| stampSheet | string | 交換処理の実行に使用するスタンプシート|
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN|
| autoRunStampSheet | bool | トランザクションの自動実行が有効か|
| atomicCommit | bool | トランザクションをアトミックにコミットするか|
| transaction | string | 発行されたトランザクション|
| transactionResult | [EzTransactionResult](#eztransactionresult) | トランザクション実行結果|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Exchange(
    );
    var result = await domain.IncrementalExchangeAsync(
        rateName: "rate-0001",
        count: 1,
        config: null
    );
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Exchange(
    );
    var future = domain.IncrementalExchangeFuture(
        rateName: "rate-0001",
        count: 1,
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Exchange(
    );
    const auto Future = Domain->IncrementalExchange(
        "rate-0001", // rateName
        1 // count
        // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.exchange.namespace_(
        "namespace-0001"
    ).me(game_session).exchange(
    )

var async_result = await domain.incremental_exchange(
    "rate-0001", # rate_name
    1, # count
    null # config
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---