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

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

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




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

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

GS2-Idle のトランザクションアクションは、ネームスペース・ユーザー・カテゴリの組で決まる 1 つのステータスを対象にします。ステータスは最大放置時間と放置の進行状況を保持し、各アクションは自分が変える値だけを書き込みます。

操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界 | 直列実行モード有効時
--- | --- | --- | --- | ---
最大放置時間の加算・減算<br>`IncreaseMaximumIdleMinutesByUserId` `DecreaseMaximumIdleMinutesByUserId` | 混在してよい。統合され、値が合算される | 合算される | ネームスペース・ユーザー・カテゴリ・最大放置時間 | 変わらない。もともと合算されて成立する
最大放置時間の設定<br>`SetMaximumIdleMinutesByUserId` | 同値なら統合。値が違えば発行時にエラー | 失敗する | ネームスペース・ユーザー・カテゴリ・最大放置時間 | 同値なら入れ子越しでも成立する。値が違う場合は引き続きエラー (400)。値の絶対指定なので、後から実行された方が先の値を黙って上書きすることは許されない
報酬の受け取り<br>`ReceiveByUserId` | 失敗する | 失敗する | ネームスペース・ユーザー・カテゴリ・放置の進行状況 | 引き続き失敗する。ただし理由が変わる（下記参照）

最大放置時間は統合後の合計に対して判定され、カテゴリで許された範囲に収まる必要があるので、単独なら収まる加算でも他の加算と合わさると弾かれることがあります。

1 つのトランザクションで報酬を 2 回受け取ることは、意図的に拒否されます。報酬はトランザクション開始時点の状態から算出されるため、2 回目は同じ放置時間ぶんをもう一度配ることになるからです。どうしても 2 回必要な場合はトランザクションを分けてください。ただし 2 回目はほとんど放置時間が溜まっていない状態からの算出になります。**直列実行モード（`enableSequentialExecution` または `TransactionSettingV2`）を有効にしても、これはできません。各 `ReceiveByUserId` は 1 件ずつ実行され、直前の受け取りがリセットした後の放置の進行状況を読むようになるので、同じ放置時間分がもう一度配られることはありません。しかし受け取りは進行状況に新しい値を刻み、同時に自分が読んだ値がそのまま残っていることを要求するため、2 件の要求を同時に満たすことができず、コミット時にトランザクションが失敗します。同じカテゴリの受け取りを 2 回行うには、引き続きトランザクションを分けてください。**

最大放置時間の変更と報酬の受け取りは変える値が違うので、同居させてかまいません。

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

最大放置時間の変更は入れ子越しでも安全です。どちらの経路から届いても 1 回の更新にまとまります。

報酬の受け取りは違います。受け取りが内側から届き、もう一方の受け取りが外側に指定されている場合は、トランザクションが失敗します。**直列実行モードを有効にしても、これも同じ理由で失敗したままです。外側の受け取りは内側がリセットした後の進行状況を見られるようになりますが、2 件の書き込みがそれぞれ自分の見た値を要求するため両立せず、コミット時に失敗します。**

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

報酬の受け取りと最大放置時間の加算・設定は入手アクション、最大放置時間の減算は消費アクションです。受け取りどうしの衝突は `acquireActionUseJobQueue` を有効にすれば解消できますが、受け取りが 1 つずつ実行されるようになるだけなので、2 回目はほとんど放置時間が溜まっていない状態から算出されます。

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

最大放置時間の変更は、結果が範囲に収まるかぎり、同時実行のリクエストが何本重なってもコンフリクトしません。

報酬の受け取りは、算出の基にした状態を照合して書き込むため、同じステータスへの別の更新と重なるとコンフリクト (409) になります。リクエストの内容に問題があるわけではないので、リトライすれば成功します。

---



## Consume Action

消費アクション

### Gs2Idle:DecreaseMaximumIdleMinutesByUserId

ユーザーIDを指定して最大放置時間を減算<br>

指定されたカテゴリーにおけるユーザーの最大放置時間から指定された分数を減算します。<br>
最大放置時間はゼロを下回ることはできません。<br>
ステータスがまだ存在しない場合、減算を適用する前に自動的に作成されます。

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| categoryName | string |  | ✓|  |  ~ 128文字 | カテゴリーモデル名<br>このステータスが属するカテゴリーモデルの名前です。放置報酬計算に使用される報酬間隔、最大放置時間、入手アクション、スケジュール設定を含むカテゴリーモデル定義を参照します。 |
| decreaseMinutes | int |  | |  | 1 ~ 2147483646 | 最大放置時間を減らす分数 |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Idle:DecreaseMaximumIdleMinutesByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "categoryName": "[string]カテゴリーモデル名",
        "decreaseMinutes": "[int]最大放置時間を減らす分数",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Idle:DecreaseMaximumIdleMinutesByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  categoryName: "[string]カテゴリーモデル名"
  decreaseMinutes: "[int]最大放置時間を減らす分数"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("idle").consume.decrease_maximum_idle_minutes_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    categoryName="[string]カテゴリーモデル名",
    decreaseMinutes="[int]最大放置時間を減らす分数",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

## Acquire Action

入手アクション

### Gs2Idle:IncreaseMaximumIdleMinutesByUserId

ユーザーIDを指定して最大放置時間を加算<br>

指定されたカテゴリーにおけるユーザーの最大放置時間に指定された分数を加算します。<br>
最大放置時間は、放置報酬が蓄積される時間の上限を決定します。<br>
ステータスがまだ存在しない場合、加算を適用する前に自動的に作成されます。

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| categoryName | string |  | ✓|  |  ~ 128文字 | カテゴリーモデル名<br>このステータスが属するカテゴリーモデルの名前です。放置報酬計算に使用される報酬間隔、最大放置時間、入手アクション、スケジュール設定を含むカテゴリーモデル定義を参照します。 |
| increaseMinutes | int |  | |  | 1 ~ 2147483646 | 最大放置時間を増やす分数 |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Idle:IncreaseMaximumIdleMinutesByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "categoryName": "[string]カテゴリーモデル名",
        "increaseMinutes": "[int]最大放置時間を増やす分数",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Idle:IncreaseMaximumIdleMinutesByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  categoryName: "[string]カテゴリーモデル名"
  increaseMinutes: "[int]最大放置時間を増やす分数"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("idle").acquire.increase_maximum_idle_minutes_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    categoryName="[string]カテゴリーモデル名",
    increaseMinutes="[int]最大放置時間を増やす分数",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

### Gs2Idle:SetMaximumIdleMinutesByUserId

ユーザーIDを指定して最大放置時間を設定<br>

指定されたカテゴリーにおけるユーザーの最大放置時間を指定された絶対値に設定します。<br>
加算/減算操作とは異なり、現在の最大放置時間を直接置き換えます。<br>
更新後のステータスと更新前のステータスの両方を返すため、呼び出し元は変更内容を確認できます。<br>
ステータスがまだ存在しない場合、値を適用する前に自動的に作成されます。

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| categoryName | string |  | ✓|  |  ~ 128文字 | カテゴリーモデル名<br>このステータスが属するカテゴリーモデルの名前です。放置報酬計算に使用される報酬間隔、最大放置時間、入手アクション、スケジュール設定を含むカテゴリーモデル定義を参照します。 |
| maximumIdleMinutes | int |  | |  | 1 ~ 2147483646 | 設定する最大放置時間（分） |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Idle:SetMaximumIdleMinutesByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "categoryName": "[string]カテゴリーモデル名",
        "maximumIdleMinutes": "[int]設定する最大放置時間（分）",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Idle:SetMaximumIdleMinutesByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  categoryName: "[string]カテゴリーモデル名"
  maximumIdleMinutes: "[int]設定する最大放置時間（分）"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("idle").acquire.set_maximum_idle_minutes_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    categoryName="[string]カテゴリーモデル名",
    maximumIdleMinutes="[int]設定する最大放置時間（分）",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

### Gs2Idle:ReceiveByUserId

ユーザーIDを指定して報酬を受け取る<br>

指定されたユーザーとカテゴリーの蓄積された放置時間に基づいて放置報酬を受け取ります。<br>
報酬量は、経過した放置時間を rewardIntervalMinutes で割った値から計算され、maximumIdleMinutes で上限が設定されます。<br>
receiveScript が設定されている場合、報酬付与前に実行され、受け取り操作を変更または拒否できます。<br>
overrideAcquireActionsScriptId によって入手アクション（レート修正の適用など）を変更することも可能です。<br>
受け取り後、放置タイマーは現在時刻にリセットされます。<br>
計算された報酬の入手アクションを含むトランザクションを返します。

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| categoryName | string |  | ✓|  |  ~ 128文字 | カテゴリーモデル名<br>このステータスが属するカテゴリーモデルの名前です。放置報酬計算に使用される報酬間隔、最大放置時間、入手アクション、スケジュール設定を含むカテゴリーモデル定義を参照します。 |
| config | [List&lt;Config&gt;](../sdk/#config) |  | | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Idle:ReceiveByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "categoryName": "[string]カテゴリーモデル名",
        "config": [
            {
                "key": "[string]名前",
                "value": "[string]値"
            }
        ],
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Idle:ReceiveByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  categoryName: "[string]カテゴリーモデル名"
  config: 
    - key: "[string]名前"
      value: "[string]値"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("idle").acquire.receive_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    categoryName="[string]カテゴリーモデル名",
    config={
        {
            key="[string]名前",
            value="[string]値"
        }
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---