> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Showcase トランザクションアクション
検証/消費/入手の各トランザクションアクションの仕様
## アクションの組み合わせと同時実行
すべてのサービスに共通する前提は [トランザクションアクションの組み合わせ]() にまとめています。先にそちらを読んでください。この節の残りは GS2-Showcase 固有の内容です。
GS2-Showcase のトランザクションアクションは、ネームスペース・ユーザー・陳列棚の組で決まる 1 つの陳列状態を対象にします。陳列状態は、どの商品が並んでいるかと、商品ごとの購入回数を保持します。
操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界 | 直列実行モード有効時
--- | --- | --- | --- | ---
購入回数の加算・減算
`IncrementPurchaseCountByUserId` `DecrementPurchaseCountByUserId` | 混在してよい。商品ごとに統合され、値が合算される。違う商品どうしは影響しない | 合算される | ネームスペース・ユーザー・陳列棚 | 変わらない。もともと合算されて成立する
陳列の引き直し
`ForceReDrawByUserId` | 統合され、引き直しは 1 回だけ行われる | 失敗する | ネームスペース・ユーザー・陳列棚 | 入れ子越しでも成立する。ただし同じトランザクションの中とは違い、引き直しは 2 回行われる。1 件にまとめられなくなるため、プレイヤーに見える陳列は後から実行された引き直しの結果になる
購入回数は商品ごとに書き込まれるので、違う商品の回数どうしが衝突することはありません。回数はその商品に設定された上限以下で、0 を下回れません。統合後の合計に対して判定されるので、単独なら収まる加算でも他の加算と合わさると弾かれることがあります。
引き直しは、どの商品が並ぶかを含めて陳列全体を置き換えます。購入回数はその中に入っているので、同じ陳列の購入回数の変更とは同居できません。トランザクションを分けてください。
### 入れ子になったトランザクションに注意
購入回数は入れ子越しでも安全です。どちらの経路から届いても 1 回の更新にまとまります。
引き直しは違います。引き直しが内側から届き、購入回数の変更が外側に指定されている場合は、トランザクションが失敗します。（これは同じ陳列棚に対する引き直しと購入回数の変更が衝突するケースです。同じ陳列棚への引き直しどうしが内側と外側の両方から届く場合は、上の表で扱っているケースに当たります。）**直列実行モードを有効にしても、この失敗は無くなりません。引き直しは購入回数のまとまり全体を置き換え、購入回数の変更はその中の 1 項目を増減するので、この 2 つの書き込みを同じ陳列棚に対してまとめることはできないためです。**
### 制限を回避したい場合
陳列の引き直しと購入回数の減算は入手アクション、購入回数の加算は消費アクションです。引き直しと減算の衝突は `acquireActionUseJobQueue` を有効にすれば解消できますが、引き直しと加算の同居は `enableAtomicCommit` を無効にしないと解消しません。
### 同時実行とリトライ
購入回数の変更は、結果が範囲に収まるかぎり、同時実行のリクエストが何本重なってもコンフリクトしません。
引き直しは陳列全体を書き換えるため、同じ陳列棚への別の更新と重なるとコンフリクト (409) になります。リクエストの内容に問題があるわけではないので、リトライすれば成功します。
---
## Consume Action
消費アクション
### Gs2Showcase:IncrementPurchaseCountByUserId
ユーザーIDを指定して購入回数を加算
指定されたユーザーのランダム陳列棚の特定の商品の購入回数を加算します。ローテーション期間ごとの購入制限を追跡するために使用されます。
**数量指定可能なアクション：はい**
**反転可能なアクション：はい**
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| showcaseName | string | | ✓| | ~ 128文字 | ランダム陳列棚名 |
| displayItemName | string | | ✓| | ~ 128文字 | 商品購入回数名
購入回数を追跡するランダム陳列商品の名前です。ランダム陳列棚内の陳列商品名に対応します。 |
| userId | string | | ✓| | ~ 128文字 | ユーザーID
`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| count | int | | ✓| | 0 ~ 100 | 加算する購入回数 |
| timeOffsetToken | string | | | | ~ 1024文字 | タイムオフセットトークン |
**JSON**
```json
{
"action": "Gs2Showcase:IncrementPurchaseCountByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"showcaseName": "[string]ランダム陳列棚名",
"displayItemName": "[string]商品購入回数名",
"userId": "[string]ユーザーID",
"count": "[int]加算する購入回数",
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}
```
**YAML**
```yaml
action: Gs2Showcase:IncrementPurchaseCountByUserId
request:
namespaceName: "[string]ネームスペース名"
showcaseName: "[string]ランダム陳列棚名"
displayItemName: "[string]商品購入回数名"
userId: "[string]ユーザーID"
count: "[int]加算する購入回数"
timeOffsetToken: "[string]タイムオフセットトークン"
```
**GS2-Script**
```lua
transaction.service("showcase").consume.increment_purchase_count_by_user_id({
namespaceName="[string]ネームスペース名",
showcaseName="[string]ランダム陳列棚名",
displayItemName="[string]商品購入回数名",
userId="[string]ユーザーID",
count="[int]加算する購入回数",
timeOffsetToken="[string]タイムオフセットトークン",
})
```
---
## Acquire Action
入手アクション
### Gs2Showcase:DecrementPurchaseCountByUserId
ユーザーIDを指定して購入回数を減算
ランダム陳列棚の特定の商品の購入回数を減算します。購入の取り消しや購入カウンターの調整に使用されます。
**数量指定可能なアクション：はい**
**反転可能なアクション：はい**
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| showcaseName | string | | ✓| | ~ 128文字 | ランダム陳列棚名 |
| displayItemName | string | | ✓| | ~ 128文字 | 商品購入回数名
購入回数を追跡するランダム陳列商品の名前です。ランダム陳列棚内の陳列商品名に対応します。 |
| userId | string | | ✓| | ~ 128文字 | ユーザーID
`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| count | int | | ✓| | 0 ~ 100 | 減算する購入回数 |
| timeOffsetToken | string | | | | ~ 1024文字 | タイムオフセットトークン |
**JSON**
```json
{
"action": "Gs2Showcase:DecrementPurchaseCountByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"showcaseName": "[string]ランダム陳列棚名",
"displayItemName": "[string]商品購入回数名",
"userId": "[string]ユーザーID",
"count": "[int]減算する購入回数",
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}
```
**YAML**
```yaml
action: Gs2Showcase:DecrementPurchaseCountByUserId
request:
namespaceName: "[string]ネームスペース名"
showcaseName: "[string]ランダム陳列棚名"
displayItemName: "[string]商品購入回数名"
userId: "[string]ユーザーID"
count: "[int]減算する購入回数"
timeOffsetToken: "[string]タイムオフセットトークン"
```
**GS2-Script**
```lua
transaction.service("showcase").acquire.decrement_purchase_count_by_user_id({
namespaceName="[string]ネームスペース名",
showcaseName="[string]ランダム陳列棚名",
displayItemName="[string]商品購入回数名",
userId="[string]ユーザーID",
count="[int]減算する購入回数",
timeOffsetToken="[string]タイムオフセットトークン",
})
```
---
### Gs2Showcase:ForceReDrawByUserId
ユーザーIDを指定してランダム陳列棚の内容を再抽選
指定されたユーザーのランダム陳列棚の商品を強制的に再抽選し、現在の選択をリセットして設定されたプールから新しいランダム商品の選択をトリガーします。
**数量指定可能なアクション：いいえ**
**反転可能なアクション：いいえ**
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| showcaseName | string | | ✓| | ~ 128文字 | ランダム陳列棚名 |
| userId | string | | ✓| | ~ 128文字 | ユーザーID
`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| timeOffsetToken | string | | | | ~ 1024文字 | タイムオフセットトークン |
**JSON**
```json
{
"action": "Gs2Showcase:ForceReDrawByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"showcaseName": "[string]ランダム陳列棚名",
"userId": "[string]ユーザーID",
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}
```
**YAML**
```yaml
action: Gs2Showcase:ForceReDrawByUserId
request:
namespaceName: "[string]ネームスペース名"
showcaseName: "[string]ランダム陳列棚名"
userId: "[string]ユーザーID"
timeOffsetToken: "[string]タイムオフセットトークン"
```
**GS2-Script**
```lua
transaction.service("showcase").acquire.force_re_draw_by_user_id({
namespaceName="[string]ネームスペース名",
showcaseName="[string]ランダム陳列棚名",
userId="[string]ユーザーID",
timeOffsetToken="[string]タイムオフセットトークン",
})
```
---