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

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

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

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

GS2-Limit のトランザクションアクションは、ネームスペース・ユーザー・回数制限の種類・カウンター名の組で決まる 1 つのカウンターを対象にします。

操作	同じ行を重ねたとき	入れ子越し	別の対象になる境界
カウントアップ・カウントダウン `CountUpByUserId` `CountDownByUserId`	混在してよい。統合され、値が合算される。ただし `maxValue` が違うカウントアップを並べると発行時にエラー	合算される	ネームスペース・ユーザー・回数制限の種類・カウンター名
カウンターの削除 `DeleteCounterByUserId`	統合される	失敗する	ネームスペース・ユーザー・回数制限の種類・カウンター名
検証 `VerifyCounterByUserId`	しきい値が合算されるので、まったく同じ検証を 2 回書くと 2 倍になる。回数が違う検証はそれぞれ判定される	読み取りだけなので衝突しない	カウンター・検証タイプ・回数

カウントアップとカウントダウンが同じ行なのは、どちらも同じ値への純粋な増分として書き込まれるからです。混在させてかまいません。結果は統合後の合計に対して判定されます。カウントは 0 を下回れず、回数制限の種類に設定された上限も超えられないので、単独なら収まるカウントアップでも他のカウントアップと合わさると弾かれることがあります。

上限が違うカウントアップは、同じカウンターに並べられません。 上限が食い違ったまま合算すると、厳しい上限が消えたり緩い加算が厳しい上限で弾かれたりするため、maxValue が違うカウントアップを同じカウンターに指定すると発行時にエラーになります。分けて指定してください。

カウンターの削除は値を変えるのではなくカウンターそのものを消すため、同じカウンターを触る他のアクションと同居できません。カウンターをリセットしてから数え直したい場合は、トランザクションを分けてください。

検証アクションはトランザクション開始時点のカウンターを見ます。同じトランザクションで到達するカウントを検証することはできません。

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

カウントアップ・カウントダウンは入れ子越しでも安全です。どちらの経路から届いても 1 回の更新にまとまります。

カウンターの削除は違います。削除が内側から届き、同じカウンターを外側から数えている場合は、トランザクションが失敗します。

制限を回避したい場合

カウントダウンとカウンターの削除は入手アクション、カウントアップは消費アクションです。削除とカウントダウンの衝突は acquireActionUseJobQueue を有効にすれば解消できますが、削除とカウントアップの同居は enableAtomicCommit を無効にしないと解消しません。

同時実行とリトライ

カウントアップ・カウントダウンは、結果が範囲に収まるかぎり、同時実行のリクエストが何本重なってもコンフリクトしません。同時に走ったカウントアップの合計が上限を超えた場合や、カウントダウンの合計が 0 を下回る場合にコンフリクト (409) になります。リトライすると最新のカウントで判定し直されます。

カウンターは設定に従って定期的にリセットされます。リセット境界にちょうど重なったリクエストはコンフリクト (409) になることがあります。リセットが落ち着いてからリトライすれば成功します。

Verify Action

検証アクション

Gs2Limit:VerifyCounterByUserId

ユーザーIDを指定してカウンター値を検証

指定されたユーザーのカウンター値が指定された条件を満たすことを検証します。
6つの比較演算子をサポートします：less、lessEqual、greater、greaterEqual、equal、notEqual。

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

型有効化条件必須デフォルト値の制限説明

namespaceName

string

✓

~ 128文字

ネームスペース名

ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

userId

string

✓

~ 128文字

ユーザーID
#{userId} と設定することでログイン中のユーザーIDに置換されます。

limitName

string

✓

~ 128文字

回数制限モデル名

このカウンターが属する回数制限モデルの名前です。このカウンターの値に適用されるリセットスケジュール（毎日、毎週、毎月など）を決定します。

counterName

string

✓

~ 128文字

カウンターの名前

回数制限モデル内でこのカウンターを一意に識別する名前です。同じ回数制限モデルを異なる名前の複数のカウンターで共有でき、個別の回数制限モデルを作成せずに別々の使用回数追跡（例：クエストごとや商品ごとに1カウンター）が可能です。

verifyType

文字列列挙型
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}

✓

検証の種類

定義	説明
less	カウンター値が指定値未満であること
lessEqual	カウンター値が指定値以下であること
greater	カウンター値が指定値超過であること
greaterEqual	カウンター値が指定値以上であること
equal	カウンター値が指定値と一致すること
notEqual	カウンター値が指定値と一致しないこと

count

int

0 ~ 2147483646

カウント値

このカウンターの現在の使用回数です。countUp操作でインクリメントされ、その際に指定された最大値と比較されます。回数制限モデルのリセットタイミングに達すると自動的にゼロにリセットされます。

multiplyValueSpecifyingQuantity bool true 数量指定した際に、検証に使用する値も乗算するか

timeOffsetToken string ~ 1024文字タイムオフセットトークン

{
    "action": "Gs2Limit:VerifyCounterByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "limitName": "[string]回数制限モデル名",
        "counterName": "[string]カウンターの名前",
        "verifyType": "[string]検証の種類",
        "count": "[int]カウント値",
        "multiplyValueSpecifyingQuantity": "[bool]数量指定した際に、検証に使用する値も乗算するか",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Limit:VerifyCounterByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  limitName: "[string]回数制限モデル名"
  counterName: "[string]カウンターの名前"
  verifyType: "[string]検証の種類"
  count: "[int]カウント値"
  multiplyValueSpecifyingQuantity: "[bool]数量指定した際に、検証に使用する値も乗算するか"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("limit").verify.verify_counter_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    limitName="[string]回数制限モデル名",
    counterName="[string]カウンターの名前",
    verifyType="[string]検証の種類",
    count="[int]カウント値",
    multiplyValueSpecifyingQuantity="[bool]数量指定した際に、検証に使用する値も乗算するか",
    timeOffsetToken="[string]タイムオフセットトークン",
})

Consume Action

消費アクション

Gs2Limit:CountUpByUserId

ユーザーIDを指定してカウントアップ

指定されたユーザーのカウンターを指定されたカウントアップ値だけ増加させます。
maxValue が指定された場合、カウンターはその上限を超えません。操作が最大値を超える場合は Overflow エラーが返されます。
カウンターがまだ存在しない場合、自動的に作成されます。

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

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

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
limitName	string	✓		~ 128文字	回数制限モデル名このカウンターが属する回数制限モデルの名前です。このカウンターの値に適用されるリセットスケジュール（毎日、毎週、毎月など）を決定します。
counterName	string	✓		~ 128文字	カウンターの名前回数制限モデル内でこのカウンターを一意に識別する名前です。同じ回数制限モデルを異なる名前の複数のカウンターで共有でき、個別の回数制限モデルを作成せずに別々の使用回数追跡（例：クエストごとや商品ごとに1カウンター）が可能です。
userId	string	✓		~ 128文字	ユーザーID `#{userId}` と設定することでログイン中のユーザーIDに置換されます。
countUpValue	int		1	1 ~ 2147483646	カウントアップする量
maxValue	int			1 ~ 2147483646	カウントアップを許容する最大値
timeOffsetToken	string			~ 1024文字	タイムオフセットトークン

{
    "action": "Gs2Limit:CountUpByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "limitName": "[string]回数制限モデル名",
        "counterName": "[string]カウンターの名前",
        "userId": "[string]ユーザーID",
        "countUpValue": "[int]カウントアップする量",
        "maxValue": "[int]カウントアップを許容する最大値",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Limit:CountUpByUserId
request:
  namespaceName: "[string]ネームスペース名"
  limitName: "[string]回数制限モデル名"
  counterName: "[string]カウンターの名前"
  userId: "[string]ユーザーID"
  countUpValue: "[int]カウントアップする量"
  maxValue: "[int]カウントアップを許容する最大値"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("limit").consume.count_up_by_user_id({
    namespaceName="[string]ネームスペース名",
    limitName="[string]回数制限モデル名",
    counterName="[string]カウンターの名前",
    userId="[string]ユーザーID",
    countUpValue="[int]カウントアップする量",
    maxValue="[int]カウントアップを許容する最大値",
    timeOffsetToken="[string]タイムオフセットトークン",
})

Acquire Action

入手アクション

Gs2Limit:CountDownByUserId

ユーザーIDを指定してカウントダウン

指定されたユーザーのカウンターを指定されたカウントダウン値だけ減少させます。
カウンター値は 0 を下回りません。

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

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

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
limitName	string	✓		~ 128文字	回数制限モデル名このカウンターが属する回数制限モデルの名前です。このカウンターの値に適用されるリセットスケジュール（毎日、毎週、毎月など）を決定します。
counterName	string	✓		~ 128文字	カウンターの名前回数制限モデル内でこのカウンターを一意に識別する名前です。同じ回数制限モデルを異なる名前の複数のカウンターで共有でき、個別の回数制限モデルを作成せずに別々の使用回数追跡（例：クエストごとや商品ごとに1カウンター）が可能です。
userId	string	✓		~ 128文字	ユーザーID `#{userId}` と設定することでログイン中のユーザーIDに置換されます。
countDownValue	int		1	1 ~ 2147483646	カウントダウンする量
timeOffsetToken	string			~ 1024文字	タイムオフセットトークン

{
    "action": "Gs2Limit:CountDownByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "limitName": "[string]回数制限モデル名",
        "counterName": "[string]カウンターの名前",
        "userId": "[string]ユーザーID",
        "countDownValue": "[int]カウントダウンする量",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Limit:CountDownByUserId
request:
  namespaceName: "[string]ネームスペース名"
  limitName: "[string]回数制限モデル名"
  counterName: "[string]カウンターの名前"
  userId: "[string]ユーザーID"
  countDownValue: "[int]カウントダウンする量"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("limit").acquire.count_down_by_user_id({
    namespaceName="[string]ネームスペース名",
    limitName="[string]回数制限モデル名",
    counterName="[string]カウンターの名前",
    userId="[string]ユーザーID",
    countDownValue="[int]カウントダウンする量",
    timeOffsetToken="[string]タイムオフセットトークン",
})

Gs2Limit:DeleteCounterByUserId

ユーザーIDを指定してカウンターを削除

指定されたユーザーのカウンターを削除し、使用回数をリセットします。
これにより、このカウンターに対する回数制限が実質的に解除され、ユーザーは再び 0 からカウントを開始できます。

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

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

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
limitName	string	✓	~ 128文字	回数制限モデル名このカウンターが属する回数制限モデルの名前です。このカウンターの値に適用されるリセットスケジュール（毎日、毎週、毎月など）を決定します。
userId	string	✓	~ 128文字	ユーザーID `#{userId}` と設定することでログイン中のユーザーIDに置換されます。
counterName	string	✓	~ 128文字	カウンターの名前回数制限モデル内でこのカウンターを一意に識別する名前です。同じ回数制限モデルを異なる名前の複数のカウンターで共有でき、個別の回数制限モデルを作成せずに別々の使用回数追跡（例：クエストごとや商品ごとに1カウンター）が可能です。
timeOffsetToken	string		~ 1024文字	タイムオフセットトークン

{
    "action": "Gs2Limit:DeleteCounterByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "limitName": "[string]回数制限モデル名",
        "userId": "[string]ユーザーID",
        "counterName": "[string]カウンターの名前",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Limit:DeleteCounterByUserId
request:
  namespaceName: "[string]ネームスペース名"
  limitName: "[string]回数制限モデル名"
  userId: "[string]ユーザーID"
  counterName: "[string]カウンターの名前"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("limit").acquire.delete_counter_by_user_id({
    namespaceName="[string]ネームスペース名",
    limitName="[string]回数制限モデル名",
    userId="[string]ユーザーID",
    counterName="[string]カウンターの名前",
    timeOffsetToken="[string]タイムオフセットトークン",
})