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

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

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




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

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

GS2-Schedule のトランザクションアクションは、ネームスペース・ユーザー・トリガー名の組で決まる 1 つのトリガーを対象にします。トリガーは更新のたびに全体が書き換わります。

操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界 | 直列実行モード有効時
--- | --- | --- | --- | ---
トリガーを引く<br>`TriggerByUserId` | 1 件に統合される | 失敗する | ネームスペース・ユーザー・トリガー名 | 入れ子越しでも成立する。ただし 1 件には統合されない。2 件目は 1 件目が残したトリガーに対して実行され、自分の `triggerStrategy` を適用する
トリガーの延長<br>`ExtendTriggerByUserId` | 統合され、秒数が合算される | 失敗する | ネームスペース・ユーザー・トリガー名 | 入れ子越しでも成立する。2 件目は 1 件目が残した期限に対して実行されるので、結果として秒数は合算される
トリガーの削除<br>`DeleteTriggerByUserId` | 1 件に統合される | 失敗する | ネームスペース・ユーザー・トリガー名 | 引き続き失敗する。1 件にまとめられなくなるため、2 件目はすでに無くなったトリガーに対して実行され、見つからない (404) として弾かれる
トリガーの検証<br>`VerifyTriggerByUserId` | まったく同じ検証は 1 件にまとめられる | 読み取りだけなので衝突しない | トリガー・検証タイプ・経過時間 | 変わらない。読み取りだけなのでもともと衝突しない
イベントの検証<br>`VerifyEventByUserId` | まったく同じ検証は 1 件にまとめられる | 読み取りだけなので衝突しない | イベント・検証タイプ・ユーザー | 変わらない。読み取りだけなのでもともと衝突しない

引く・延長する・削除するは 3 つの異なる行で、境界が同じです。このうち 2 つを 1 つのトリガーに対して指定すると衝突します。トリガーを引いてから延長したいという要求はよくありますが、これにはトランザクションが 2 つ必要です。延長はトランザクション開始時点の状態から動くため、同じトランザクションが引いたトリガーが見えていないからです。**直列実行モード（`enableSequentialExecution` または `TransactionSettingV2`）を有効にすると、引くと延長するを 1 つのトランザクションに入れられるようになります。ただし順序は期待どおりではありません。フェーズの中での実行順はアクション名で決まるため、`ExtendTriggerByUserId` が `TriggerByUserId` より必ず先に実行されます。トリガーがまだ無ければ延長がトリガーを作り、その上に引く操作が自分の `triggerStrategy` を適用します。引いてからその結果を同じトランザクションで延長することはできません。削除と引く・延長するの組み合わせは解消しません。削除は消費アクションとして先に実行されますが、1 つのトランザクションでトリガーを消してから作り直すのは同じ行への 2 つの書き込みになり、まとめられずにエラー (400) になります。**

検証アクションはトランザクション開始時点の状態を見ます。同じトランザクションで引いたトリガーや、削除したトリガーを検証することはできません。

イベントが開催中かどうかは時間オフセットに依存し、オフセットはユーザーごとなので、イベントの検証はユーザーごとに別の対象になります。

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

トリガーは全体が書き換わるため、内側から引かれたトリガーと、外側から延長または削除された同じトリガーが衝突して、トランザクションが失敗します。**直列実行モードを有効にしても、外側が削除する場合は解消しません。削除は先に実行されますが、後に続く引く操作はトリガーを作り直すことになり、同じ行に対する削除と作成を 1 つのトランザクションでまとめることはできないためエラー (400) になります。**

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

トリガーを引く・延長するは入手アクション、削除は消費アクションです。引くと延長の衝突は `acquireActionUseJobQueue` を有効にすれば解消できますが、削除との同居は `enableAtomicCommit` を無効にしないと解消しません。

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

トリガーはリビジョンの照合を伴って全体が書き換わるため、同じトリガーを複数のリクエストが同時に更新すると、後から確定した側がコンフリクト (409) になります。リクエストの内容に問題があるわけではないので、リトライすれば成功します。

トリガー名が違えば別の対象なので、違うトリガーへのリクエストどうしはコンフリクトしません。

---


## Verify Action

検証アクション

### Gs2Schedule:VerifyTriggerByUserId

ユーザーIDを指定してトリガーが引かれてからの経過時間を検証<br>

指定したユーザーのトリガーの状態に関する条件を検証します。verifyType は `notTriggerd`、`elapsed`、`notElapsed` を設定できます。検証条件が満たされない場合はエラーを返します。

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| triggerName | string |  | ✓|  |  ~ 128文字 | トリガー名<br>トリガー固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| verifyType | 文字列列挙型<br>enum {<br>"notTriggerd",<br>"elapsed",<br>"notElapsed"<br>}<br> |  | ✓|  |  | 検証の種類notTriggerd: トリガーが引かれていない / elapsed: 指定時間が経過している / notElapsed: 指定時間が経過していない /  |
| elapsedMinutes | int | {verifyType} in ["elapsed", "notElapsed"] | ✓※|  | 0 ~ 2147483646 | 経過時間(分)<br>※ verifyType が "elapsed","notElapsed"であれば 必須 |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Schedule:VerifyTriggerByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "triggerName": "[string]トリガー名",
        "verifyType": "[string]検証の種類",
        "elapsedMinutes": "[int]経過時間(分)",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Schedule:VerifyTriggerByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  triggerName: "[string]トリガー名"
  verifyType: "[string]検証の種類"
  elapsedMinutes: "[int]経過時間(分)"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("schedule").verify.verify_trigger_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    triggerName="[string]トリガー名",
    verifyType="[string]検証の種類",
    elapsedMinutes="[int]経過時間(分)",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

### Gs2Schedule:VerifyEventByUserId

ユーザーIDを指定してイベントの開催期間であるかを検証<br>

指定したユーザーにおいて、指定されたイベントが現在アクティブなスケジュール期間内であるかを検証します。verifyType は `inSchedule` または `notInSchedule` を設定できます。検証条件が満たされない場合はエラーを返します。

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| eventName | string |  | ✓|  |  ~ 128文字 | イベント名<br>イベント固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| verifyType | 文字列列挙型<br>enum {<br>"inSchedule",<br>"notInSchedule"<br>}<br> |  | ✓|  |  | 検証の種類inSchedule: イベントの開催期間である / notInSchedule: イベントの開催期間ではない /  |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Schedule:VerifyEventByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "eventName": "[string]イベント名",
        "verifyType": "[string]検証の種類",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Schedule:VerifyEventByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  eventName: "[string]イベント名"
  verifyType: "[string]検証の種類"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("schedule").verify.verify_event_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    eventName="[string]イベント名",
    verifyType="[string]検証の種類",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

## Consume Action

消費アクション

### Gs2Schedule:DeleteTriggerByUserId

ユーザーIDを指定してトリガーを削除<br>

指定したユーザーの指定されたトリガーを削除します。トリガーを削除すると、関連する相対スケジュールイベントが無効化されます。

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

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

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




**JSON**
```json
{
    "action": "Gs2Schedule:DeleteTriggerByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "triggerName": "[string]トリガー名",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Schedule:DeleteTriggerByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  triggerName: "[string]トリガー名"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("schedule").consume.delete_trigger_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    triggerName="[string]トリガー名",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

## Acquire Action

入手アクション

### Gs2Schedule:TriggerByUserId

ユーザーIDを指定してトリガーを実行<br>

指定したユーザーのトリガーを引きます。トリガー戦略により動作が決まります：`renew` は新しいTTLでリセット、`extend` は既存のTTLを延長、`drop` は既に引かれている場合は無視、`repeatCycleEnd`/`repeatCycleNextStart`/`absoluteEnd` は指定したイベントのスケジュールに有効期限を合わせます。トリガーを引くと関連する相対スケジュールイベントが有効化されます。

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| triggerName | string |  | ✓|  |  ~ 128文字 | トリガー名<br>トリガー固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| triggerStrategy | 文字列列挙型<br>enum {<br>"renew",<br>"extend",<br>"drop",<br>"repeatCycleEnd",<br>"repeatCycleNextStart",<br>"absoluteEnd"<br>}<br> |  | ✓|  |  | トリガーの引き方の方針renew: すでにトリガーが引かれている場合は再度新しい期間で引き直す / extend: すでにトリガーが引かれている場合は期間を延長 / drop: すでにトリガーが引かれている場合は無視 / repeatCycleEnd: 指定したイベントの繰り返し期間の終了日時に有効期限を迎えるようにトリガーを引く / repeatCycleNextStart: 指定したイベントの繰り返しで、次回の繰り返し開始日時に有効期限を迎えるようにトリガーを引く / absoluteEnd: 指定したイベントの終了日時に有効期限を迎えるようにトリガーを引く /  |
| ttl | int | {triggerStrategy} in ["renew", "extend", "drop"] | ✓※|  | 0 ~ 2147483646 | トリガーの有効期限(秒)<br>※ triggerStrategy が "renew","extend","drop"であれば 必須 |
| eventId | string | {triggerStrategy} in ["repeatCycleEnd", "repeatCycleNextStart", "absoluteEnd"] | ✓※|  |  ~ 1024文字 | イベントGRN<br>※ triggerStrategy が "repeatCycleEnd","repeatCycleNextStart","absoluteEnd"であれば 必須 |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Schedule:TriggerByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "triggerName": "[string]トリガー名",
        "userId": "[string]ユーザーID",
        "triggerStrategy": "[string]トリガーの引き方の方針",
        "ttl": "[int]トリガーの有効期限(秒)",
        "eventId": "[string]イベントGRN",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Schedule:TriggerByUserId
request:
  namespaceName: "[string]ネームスペース名"
  triggerName: "[string]トリガー名"
  userId: "[string]ユーザーID"
  triggerStrategy: "[string]トリガーの引き方の方針"
  ttl: "[int]トリガーの有効期限(秒)"
  eventId: "[string]イベントGRN"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("schedule").acquire.trigger_by_user_id({
    namespaceName="[string]ネームスペース名",
    triggerName="[string]トリガー名",
    userId="[string]ユーザーID",
    triggerStrategy="[string]トリガーの引き方の方針",
    ttl="[int]トリガーの有効期限(秒)",
    eventId="[string]イベントGRN",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

### Gs2Schedule:ExtendTriggerByUserId

ユーザーIDを指定してトリガーの期間を延長<br>

指定したユーザーの既存のトリガーの有効期限を指定した秒数だけ延長します。トリガーが存在しない場合は、指定した延長期間をTTLとして新しいトリガーが作成されます。

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

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

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




**JSON**
```json
{
    "action": "Gs2Schedule:ExtendTriggerByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "triggerName": "[string]トリガー名",
        "userId": "[string]ユーザーID",
        "extendSeconds": "[int]トリガーを延長する期間(秒)",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Schedule:ExtendTriggerByUserId
request:
  namespaceName: "[string]ネームスペース名"
  triggerName: "[string]トリガー名"
  userId: "[string]ユーザーID"
  extendSeconds: "[int]トリガーを延長する期間(秒)"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("schedule").acquire.extend_trigger_by_user_id({
    namespaceName="[string]ネームスペース名",
    triggerName="[string]トリガー名",
    userId="[string]ユーザーID",
    extendSeconds="[int]トリガーを延長する期間(秒)",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---