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

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

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

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

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

1 つのトランザクションで報酬を 2 回受け取ることは、意図的に拒否されます。報酬はトランザクション開始時点の状態から算出されるため、2 回目は同じ放置時間ぶんをもう一度配ることになるからです。どうしても 2 回必要な場合はトランザクションを分けてください。ただし 2 回目はほとんど放置時間が溜まっていない状態からの算出になります。

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

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

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

報酬の受け取りは違います。受け取りが内側から届き、もう一方の受け取りが外側に指定されている場合は、トランザクションが失敗します。

制限を回避したい場合

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

同時実行とリトライ

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

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

Consume Action

消費アクション

Gs2Idle:DecreaseMaximumIdleMinutesByUserId

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

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

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

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

• Format:
• JSON
• YAML
• GS2-Script

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

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

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を指定して最大放置時間を加算

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

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

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

• Format:
• JSON
• YAML
• GS2-Script

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

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

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を指定して最大放置時間を設定

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

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

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

• Format:
• JSON
• YAML
• GS2-Script

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

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

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を指定して報酬を受け取る

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

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

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

• Format:
• JSON
• YAML
• GS2-Script

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

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

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