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

# GS2-AdReward トランザクションアクション

検証/消費/入手の各トランザクションアクションの仕様




## アクションの組み合わせと同時実行

すべてのサービスに共通する前提は [トランザクションアクションの組み合わせ]() にまとめています。先にそちらを読んでください。この節の残りは GS2-AdReward 固有の内容です。

GS2-AdReward のトランザクションアクションは、ネームスペースとユーザーごとに 1 つだけ存在するポイント残高を対象にします。

操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界 | 直列実行モード有効時
--- | --- | --- | --- | ---
ポイントの入手<br>`AcquirePointByUserId` | 統合され、ポイントが合算される | 合算される | ネームスペース・ユーザー | 変わらない。もともと合算されて成立する
ポイントの消費<br>`ConsumePointByUserId` | 統合され、合計額で残高が判定される | 合算される。ただし合計が残高を超えた場合はコンフリクト (409) になり、残高が増えないかぎりリトライしても解消しない | ネームスペース・ユーザー | 変わらない。コンフリクトになる場合も含めて挙動は同じ

どちらの行も同じ残高への純粋な増分として書き込まれるため、入手と消費を同居させても、それぞれが適用されます。入手 100 と入手 50 を指定すると、ポイント 150 の入手 1 件として扱われます。残高 100 に対して 消費 60 と 消費 30 を指定すると残高は 10 になり、消費 60 と 入手 200 を指定すると残高は 240 になります。

消費の合計が開始時点の残高を超える場合はポイント不足エラー (400) になり、片方だけが適用されることはありません。

**トランザクションの中で入手したポイントは、同じトランザクションの消費には使えません。** 消費アクションは必ず入手アクションより先に実行されるため、使えるのは開始時点の残高だけです。必要な場合はトランザクションを分けてください。

### 入れ子になったトランザクションに注意

GS2-AdReward はこの状況に耐えられます。別々のトランザクションから届いた増減も、最終的には残高への 1 回の更新としてまとめて適用されるため、コンフリクトしません。例外は、この経路で分かれて届いた消費の合計が残高を超えた場合で、そのときはポイント不足エラー (400) ではなくコンフリクト (409) としてトランザクションが拒否され、残高は変化しません。残高が増えないかぎり、リトライしても成功しません。

### 制限を回避したい場合

上の制限は実行順序から来るもので、`enableAtomicCommit` や `acquireActionUseJobQueue` を変えても解消しません。入手したポイントを消費に充てたい場合はトランザクションを分けてください。

### 同時実行とリトライ

入手アクション同士、および入手アクションと消費アクションの同時実行は、増減がそれぞれ確実に反映されるため、原則としてコンフリクトしません。

同じポイント残高への更新が短時間に集中した場合は、一時的なコンフリクト (409) が返ることがあります。残高が原因ではないため、少し間隔を空けてリトライすれば成功します。

別々のトランザクションの消費アクションが同時に実行され、合計が残高を超えた場合はコンフリクト (409) になることがあります。リトライすると最新の残高で判定し直されるので、その時点で残高が足りていれば成功し、足りなければポイント不足エラー (400) が返ります。

---



## Consume Action

消費アクション

### Gs2AdReward:ConsumePointByUserId

ユーザーIDを指定してポイントを消費<br>

指定されたユーザーIDから指定された数のポイントを減算し、更新後のポイント情報を返します。<br>
要求された消費量に対してポイントが不足している場合はエラーが返されます。<br>
ネームスペースの消費スクリプト設定に GS2-Script が設定されている場合、ポイント減算前にスクリプトが実行され、カスタムバリデーションや消費量の変更が可能です。<br>
ポイント減算後、ネームスペース設定で変更通知が構成されている場合は通知が送信されます。

**数量指定可能なアクション：はい**

**反転可能なアクション：はい**

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| point | long |  | ✓|  | 1 ~ 9223372036854775805 | 消費するポイント |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2AdReward:ConsumePointByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "point": "[long]消費するポイント",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2AdReward:ConsumePointByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  point: "[long]消費するポイント"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("adReward").consume.consume_point_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    point="[long]消費するポイント",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

## Acquire Action

入手アクション

### Gs2AdReward:AcquirePointByUserId

ユーザーIDを指定してポイントを入手<br>

指定されたユーザーIDに指定された数のポイントを追加し、更新後のポイント情報を返します。<br>
ユーザーのポイントレコードが存在しない場合、ポイント追加前に新しいレコードが自動的に作成されます。<br>
ネームスペースの入手スクリプト設定に GS2-Script が設定されている場合、ポイント追加前にスクリプトが実行され、カスタムバリデーションや入手量の変更が可能です。<br>
ポイント追加後、ネームスペース設定で変更通知が構成されている場合は通知が送信されます。

**数量指定可能なアクション：はい**

**反転可能なアクション：はい**

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| point | long |  | ✓|  | 1 ~ 9223372036854775805 | 入手するポイント |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2AdReward:AcquirePointByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "point": "[long]入手するポイント",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2AdReward:AcquirePointByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  point: "[long]入手するポイント"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("adReward").acquire.acquire_point_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    point="[long]入手するポイント",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---