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

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

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




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

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

GS2-Script がトランザクションに指定できるアクションは 1 つです。GS2-Script 自身はユーザーごとの状態を持たないため、このアクションが GS2-Script を理由に他と衝突することはありません。何と衝突しうるかは、スクリプトが何をするかで決まります。

操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界
--- | --- | --- | ---
スクリプトの実行<br>`InvokeScript` | 統合されず、それぞれ独立に実行される | 統合されず、それぞれ独立に実行される | （それぞれの実行が常に独立）

スクリプト・ユーザー・引数・乱数シードが完全に同じ実行を複数指定した場合も、それぞれ独立に実行されます。ただし `acquireActionUseJobQueue` を有効にしてジョブキュー経由で実行する場合は、完全に同じ実行が 1 回に統合されることがあります。

### 制限はスクリプトが行うことから来ます

スクリプトが書き込んだものは、それを呼び出したトランザクションに入ります。そのため、そのアクションを自分で指定した場合とまったく同じように、スクリプトが触るサービスの制限が当てはまります。2 つの実行がどちらも同じウォレットに加算する、あるいはどちらも同じ図鑑を書き換える場合、そうしたアクションを並べて書いたときと同じ制限に当たります。

あるリソースを触るのがトランザクションの中でそのスクリプトだけであれば、ここまでの話は関係ありません。注意が必要なのは、同じリソースをトランザクションに直接指定したアクションや別のスクリプトも触る場合です。

スクリプトが自身のトランザクションを発行する場合は入れ子になり、下記が当てはまります。

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

内側のトランザクションから届く更新は、外側に直接指定したアクションの対象外です。そのため、外側のトランザクションも書き込むリソースにスクリプトが書き込むと、そのリソースが 2 つの書き込みを許さない場合にトランザクションが失敗します。

トランザクションにスクリプトが含まれる場合は、そのスクリプトもトランザクションの一部として読んでください。

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

スクリプトの実行は入手アクションなので、`acquireActionUseJobQueue` を有効にすれば他の入手アクションから分離できます。`enableAtomicCommit` を無効にすると、スクリプトと他のアクションが 1 回の書き込みに集まらなくなります。

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

GS2-Script 自身がコンフリクトを返すことはありません。同時実行のリクエストと衝突するかどうかはスクリプトが何を書き込むかによって決まり、リトライの指針もそのサービスのものが当てはまります。

---




## Acquire Action

入手アクション

### Gs2Script:InvokeScript

スクリプトを実行<br>

指定されたLuaスクリプトを提供されたJSON引数で同期的に実行します。ステータスコード、戻り値、トランザクション情報、乱数状態、実行時間、標準出力を含む実行結果を返します。GS2サービス間のアトミック操作のためのトランザクション処理をサポートしています。

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| scriptId | string |  | ✓|  |  ~ 1024文字 | スクリプトGRN |
| userId | string |  | |  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| args | string |  | | "{}" |  ~ 5242880文字 | スクリプトに渡される引数 (JSON形式) |
| randomStatus | RandomStatus |  | |  |  | 乱数の状態 |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Script:InvokeScript",
    "request": {
        "scriptId": "[string]スクリプトGRN",
        "userId": "[string]ユーザーID",
        "args": "[string]スクリプトに渡される引数 (JSON形式)",
        "randomStatus": {
            "seed": "[long]乱数シード",
            "used": [
                {
                    "category": "[long]カテゴリ",
                    "used": "[long]使用回数"
                }
            ]
        },
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Script:InvokeScript
request:
  scriptId: "[string]スクリプトGRN"
  userId: "[string]ユーザーID"
  args: "[string]スクリプトに渡される引数 (JSON形式)"
  randomStatus: 
    seed: "[long]乱数シード"
    used: 
    - category: "[long]カテゴリ"
      used: "[long]使用回数"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("script").acquire.invoke_script({
    scriptId="[string]スクリプトGRN",
    userId="[string]ユーザーID",
    args="[string]スクリプトに渡される引数 (JSON形式)",
    randomStatus={
        seed="[long]乱数シード",
        used={
                {
                    category="[long]カテゴリ",
                    used="[long]使用回数"
                }
            }
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---