GS2-Grade トランザクションアクション
アクションの組み合わせと同時実行
すべてのサービスに共通する前提は トランザクションアクションの組み合わせ にまとめています。先にそちらを読んでください。この節の残りは GS2-Grade 固有の内容です。
GS2-Grade のトランザクションアクションは、ApplyRankCapByUserId を除いて、ネームスペース・ユーザー・グレードモデル・プロパティの組で決まる 1 つのグレードステータスを対象にします。ステータスは更新のたびに全体が書き換わります。
| 操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界 |
|---|---|---|---|
グレードの加算AddGradeByUserId | 統合され、値が合算される | 失敗する | ネームスペース・ユーザー・グレードモデル・プロパティ |
グレードの減算SubGradeByUserId | 統合され、値が合算される | 失敗する | ネームスペース・ユーザー・グレードモデル・プロパティ |
ランク上限の適用ApplyRankCapByUserId | 統合される | GS2-Experience 側の扱いに従う | 書き込み先の GS2-Experience のステータス |
他のアクションへの展開MultiplyAcquireActionsByUserId | 統合され、内側のアクションが 1 つのリストにまとめられる | 自身は何も更新しない | — |
| 検証アクション全般 | 先勝ち | 読み取りだけなので衝突しない | 対象・検証タイプ・必要グレード |
加算と減算は行が違い、境界が同じです。同じステータスへの加算と減算を 1 つのトランザクションに入れることはできません。
ApplyRankCapByUserId はグレードステータスを更新しません。現在のグレードを読み取り、対応する GS2-Experience のステータスのランク上限を設定します。同じトランザクションにそのステータスを対象とする GS2-Experience のアクションが含まれていると衝突してトランザクションが失敗するので、そちらで何を同居させられるかは GS2-Experience の記述を確認してください。
MultiplyAcquireActionsByUserId はグレードを読み取り、渡されたアクションに倍率を掛けて自身のトランザクションとして発行します。自身は何も更新しませんが、展開後のアクションが属するサービスの制限がそのまま当てはまり、下記「入れ子になったトランザクションに注意」も当てはまります。
検証アクションはトランザクション開始時点のステータスを見ます。同じトランザクションで到達するグレードを検証することはできません。
入れ子になったトランザクションに注意
グレードステータスは全体が書き換わるため、並べて書けば 1 件に統合されたはずの同じグレードの加算どうしでも、片方が内側から届く場合はトランザクションが失敗します。報酬や抽選の中身まで含めて、1 つのトランザクションの中で同じステータスを更新する箇所が 1 つだけになるように設計してください。
制限を回避したい場合
グレードの加算は入手アクション、減算は消費アクションです。加算どうしの衝突は acquireActionUseJobQueue を有効にすれば解消できますが、加算と減算の同居は enableAtomicCommit を無効にしないと解消しません。
同時実行とリトライ
グレードステータスは全体が書き換わるため、加算どうしであっても、GS2-Experience の経験値のように「一定範囲なら衝突しない」という緩和はありません。同じステータスを複数のリクエストが同時に更新すると、後から確定した側がコンフリクト (409) になります。リクエストの内容に問題があるわけではないので、リトライすれば成功します。ランク上限の適用は、対応する GS2-Experience のステータスへの同時更新ともコンフリクトすることがあります。
Verify Action
検証アクション
Gs2Grade:VerifyGradeByUserId
ユーザーIDを指定してグレードを検証
指定されたユーザーのグレード値が指定された条件を満たすことを検証します(サーバーサイド操作)。
6つの比較演算子をサポートします:less(未満)、lessEqual(以下)、greater(超過)、greaterEqual(以上)、equal(一致)、notEqual(不一致)。
条件が満たされない場合、期待値と実際の値を含む説明的なエラーメッセージが返されます。
multiplyValueSpecifyingQuantity が true の場合、検証の閾値は指定された数量で乗算されます。
数量指定可能なアクション:いいえ
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||||||||||
| userId | string | ✓ | ~ 128文字 | ユーザーID#{userId} と設定することでログイン中のユーザーIDに置換されます。 | ||||||||||||||||
| gradeName | string | ✓ | ~ 128文字 | グレードモデル名 このステータスが属するグレードモデルの名前です。グレードエントリのマッピング、連動する経験値モデル、報酬加算テーブルを含むグレードモデル定義を参照します。 | ||||||||||||||||
| verifyType | 文字列列挙型 enum { “less”, “lessEqual”, “greater”, “greaterEqual”, “equal”, “notEqual” } | ✓ | 検証の種類
| |||||||||||||||||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID このグレードステータスの開発者定義の識別子で、ユーザーとグレードモデル内で一意です。連動する GS2-Experience ステータスのプロパティIDと同じ値を使用することを強く推奨します。これにより、グレード値とランクキャップの正しい同期が保証されます。 | ||||||||||||||||
| gradeValue | long | 1 | 1 ~ 9223372036854775805 | 現在のグレード このステータスの現在のグレード値です。連動する GS2-Experience モデルのランクキャップを決定するために、グレードモデルのグレードエントリ配列のインデックスとして使用されます。この値が変更されると、関連する経験値ステータスのランクキャップが対応するグレードエントリで定義された値に自動更新されます。 | ||||||||||||||||
| multiplyValueSpecifyingQuantity | bool | false | 数量指定した際に、検証に使用する値も乗算するか | |||||||||||||||||
| timeOffsetToken | string | ~ 1024文字 | タイムオフセットトークン |
{
"action": "Gs2Grade:VerifyGradeByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"userId": "[string]ユーザーID",
"gradeName": "[string]グレードモデル名",
"verifyType": "[string]検証の種類",
"propertyId": "[string]プロパティID",
"gradeValue": "[long]現在のグレード",
"multiplyValueSpecifyingQuantity": "[bool]数量指定した際に、検証に使用する値も乗算するか",
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}action: Gs2Grade:VerifyGradeByUserId
request:
namespaceName: "[string]ネームスペース名"
userId: "[string]ユーザーID"
gradeName: "[string]グレードモデル名"
verifyType: "[string]検証の種類"
propertyId: "[string]プロパティID"
gradeValue: "[long]現在のグレード"
multiplyValueSpecifyingQuantity: "[bool]数量指定した際に、検証に使用する値も乗算するか"
timeOffsetToken: "[string]タイムオフセットトークン"transaction.service("grade").verify.verify_grade_by_user_id({
namespaceName="[string]ネームスペース名",
userId="[string]ユーザーID",
gradeName="[string]グレードモデル名",
verifyType="[string]検証の種類",
propertyId="[string]プロパティID",
gradeValue="[long]現在のグレード",
multiplyValueSpecifyingQuantity="[bool]数量指定した際に、検証に使用する値も乗算するか",
timeOffsetToken="[string]タイムオフセットトークン",
})Gs2Grade:VerifyGradeUpMaterialByUserId
ユーザーIDを指定してグレードアップに使用する素材を検証
指定されたユーザーの指定されたプロパティのグレードアップに素材のプロパティIDが有効かどうかを検証します(サーバーサイド操作)。
検証はグレードエントリの PropertyIdRegex と GradeUpPropertyIdRegex から正規表現パターンを構築し、素材のプロパティIDがマッチするかを確認します。
2つの検証タイプをサポートします:‘match’(素材がパターンにマッチすること)と ’notMatch’(素材がパターンにマッチしないこと)。
数量指定可能なアクション:いいえ
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||
| userId | string | ✓ | ~ 128文字 | ユーザーID#{userId} と設定することでログイン中のユーザーIDに置換されます。 | ||||||||
| gradeName | string | ✓ | ~ 128文字 | グレードモデル名 このステータスが属するグレードモデルの名前です。グレードエントリのマッピング、連動する経験値モデル、報酬加算テーブルを含むグレードモデル定義を参照します。 | ||||||||
| verifyType | 文字列列挙型 enum { “match”, “notMatch” } | ✓ | 検証の種類
| |||||||||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID このグレードステータスの開発者定義の識別子で、ユーザーとグレードモデル内で一意です。連動する GS2-Experience ステータスのプロパティIDと同じ値を使用することを強く推奨します。これにより、グレード値とランクキャップの正しい同期が保証されます。 | ||||||||
| materialPropertyId | string | ✓ | ~ 1024文字 | プロパティID このグレードステータスの開発者定義の識別子で、ユーザーとグレードモデル内で一意です。連動する GS2-Experience ステータスのプロパティIDと同じ値を使用することを強く推奨します。これにより、グレード値とランクキャップの正しい同期が保証されます。 | ||||||||
| timeOffsetToken | string | ~ 1024文字 | タイムオフセットトークン |
{
"action": "Gs2Grade:VerifyGradeUpMaterialByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"userId": "[string]ユーザーID",
"gradeName": "[string]グレードモデル名",
"verifyType": "[string]検証の種類",
"propertyId": "[string]プロパティID",
"materialPropertyId": "[string]プロパティID",
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}action: Gs2Grade:VerifyGradeUpMaterialByUserId
request:
namespaceName: "[string]ネームスペース名"
userId: "[string]ユーザーID"
gradeName: "[string]グレードモデル名"
verifyType: "[string]検証の種類"
propertyId: "[string]プロパティID"
materialPropertyId: "[string]プロパティID"
timeOffsetToken: "[string]タイムオフセットトークン"transaction.service("grade").verify.verify_grade_up_material_by_user_id({
namespaceName="[string]ネームスペース名",
userId="[string]ユーザーID",
gradeName="[string]グレードモデル名",
verifyType="[string]検証の種類",
propertyId="[string]プロパティID",
materialPropertyId="[string]プロパティID",
timeOffsetToken="[string]タイムオフセットトークン",
})Consume Action
消費アクション
Gs2Grade:SubGradeByUserId
ユーザーIDを指定してグレードを減算
指定されたグレードモデルとプロパティに対して、指定されたユーザーの現在のグレードから指定値を減算します(サーバーサイド操作)。
グレード値の更新後、リンクされた GS2-Experience ステータスにランクキャップが自動的に適用されます。
ランクキャップ値は新しいグレードレベルに一致するグレードエントリから決定され。
更新されたグレードステータスとともに、Experience ネームスペース名と更新された Experience ステータスを返します。
数量指定可能なアクション:はい
反転可能なアクション:はい
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| userId | string | ✓ | ~ 128文字 | ユーザーID#{userId} と設定することでログイン中のユーザーIDに置換されます。 | ||
| gradeName | string | ✓ | ~ 128文字 | グレードモデル名 このステータスが属するグレードモデルの名前です。グレードエントリのマッピング、連動する経験値モデル、報酬加算テーブルを含むグレードモデル定義を参照します。 | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID このグレードステータスの開発者定義の識別子で、ユーザーとグレードモデル内で一意です。連動する GS2-Experience ステータスのプロパティIDと同じ値を使用することを強く推奨します。これにより、グレード値とランクキャップの正しい同期が保証されます。 | ||
| gradeValue | long | 0 | 0 ~ 9223372036854775805 | 失うグレード | ||
| timeOffsetToken | string | ~ 1024文字 | タイムオフセットトークン |
{
"action": "Gs2Grade:SubGradeByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"userId": "[string]ユーザーID",
"gradeName": "[string]グレードモデル名",
"propertyId": "[string]プロパティID",
"gradeValue": "[long]失うグレード",
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}action: Gs2Grade:SubGradeByUserId
request:
namespaceName: "[string]ネームスペース名"
userId: "[string]ユーザーID"
gradeName: "[string]グレードモデル名"
propertyId: "[string]プロパティID"
gradeValue: "[long]失うグレード"
timeOffsetToken: "[string]タイムオフセットトークン"transaction.service("grade").consume.sub_grade_by_user_id({
namespaceName="[string]ネームスペース名",
userId="[string]ユーザーID",
gradeName="[string]グレードモデル名",
propertyId="[string]プロパティID",
gradeValue="[long]失うグレード",
timeOffsetToken="[string]タイムオフセットトークン",
})Acquire Action
入手アクション
Gs2Grade:AddGradeByUserId
ユーザーIDを指定してグレードを加算
指定されたグレードモデルとプロパティに対して、ユーザーの現在のグレードに指定値を加算します。
グレード値の更新後、リンクされた GS2-Experience ステータスにランクキャップが自動的に適用されます。
ランクキャップ値は新しいグレードレベルに一致するグレードエントリから決定され。
更新されたグレードステータスとともに、Experience ネームスペース名と更新された Experience ステータスを返します。
数量指定可能なアクション:はい
反転可能なアクション:はい
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| userId | string | ✓ | ~ 128文字 | ユーザーID#{userId} と設定することでログイン中のユーザーIDに置換されます。 | ||
| gradeName | string | ✓ | ~ 128文字 | グレードモデル名 このステータスが属するグレードモデルの名前です。グレードエントリのマッピング、連動する経験値モデル、報酬加算テーブルを含むグレードモデル定義を参照します。 | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID このグレードステータスの開発者定義の識別子で、ユーザーとグレードモデル内で一意です。連動する GS2-Experience ステータスのプロパティIDと同じ値を使用することを強く推奨します。これにより、グレード値とランクキャップの正しい同期が保証されます。 | ||
| gradeValue | long | 0 | 0 ~ 9223372036854775805 | 獲得グレード | ||
| timeOffsetToken | string | ~ 1024文字 | タイムオフセットトークン |
{
"action": "Gs2Grade:AddGradeByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"userId": "[string]ユーザーID",
"gradeName": "[string]グレードモデル名",
"propertyId": "[string]プロパティID",
"gradeValue": "[long]獲得グレード",
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}action: Gs2Grade:AddGradeByUserId
request:
namespaceName: "[string]ネームスペース名"
userId: "[string]ユーザーID"
gradeName: "[string]グレードモデル名"
propertyId: "[string]プロパティID"
gradeValue: "[long]獲得グレード"
timeOffsetToken: "[string]タイムオフセットトークン"transaction.service("grade").acquire.add_grade_by_user_id({
namespaceName="[string]ネームスペース名",
userId="[string]ユーザーID",
gradeName="[string]グレードモデル名",
propertyId="[string]プロパティID",
gradeValue="[long]獲得グレード",
timeOffsetToken="[string]タイムオフセットトークン",
})Gs2Grade:ApplyRankCapByUserId
ユーザーIDを指定して GS2-Experienceステータスにランクキャップを適用
指定されたユーザーの現在のグレードに対応するランクキャップを、リンクされた GS2-Experience ステータスに適用します(サーバーサイド操作)。
現在のグレード値に一致するグレードエントリを参照してランクキャップ値を決定し。
グレードが外部で変更され、Experience のランクキャップを同期する必要がある場合に有用です。
更新されたグレードステータスとともに、Experience ネームスペース名と更新された Experience ステータスを返します。
数量指定可能なアクション:いいえ
反転可能なアクション:いいえ
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| userId | string | ✓ | ~ 128文字 | ユーザーID#{userId} と設定することでログイン中のユーザーIDに置換されます。 | ||
| gradeName | string | ✓ | ~ 128文字 | グレードモデル名 このステータスが属するグレードモデルの名前です。グレードエントリのマッピング、連動する経験値モデル、報酬加算テーブルを含むグレードモデル定義を参照します。 | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID このグレードステータスの開発者定義の識別子で、ユーザーとグレードモデル内で一意です。連動する GS2-Experience ステータスのプロパティIDと同じ値を使用することを強く推奨します。これにより、グレード値とランクキャップの正しい同期が保証されます。 | ||
| timeOffsetToken | string | ~ 1024文字 | タイムオフセットトークン |
{
"action": "Gs2Grade:ApplyRankCapByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"userId": "[string]ユーザーID",
"gradeName": "[string]グレードモデル名",
"propertyId": "[string]プロパティID",
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}action: Gs2Grade:ApplyRankCapByUserId
request:
namespaceName: "[string]ネームスペース名"
userId: "[string]ユーザーID"
gradeName: "[string]グレードモデル名"
propertyId: "[string]プロパティID"
timeOffsetToken: "[string]タイムオフセットトークン"transaction.service("grade").acquire.apply_rank_cap_by_user_id({
namespaceName="[string]ネームスペース名",
userId="[string]ユーザーID",
gradeName="[string]グレードモデル名",
propertyId="[string]プロパティID",
timeOffsetToken="[string]タイムオフセットトークン",
})Gs2Grade:MultiplyAcquireActionsByUserId
グレードに基づくレートで入手アクションを乗算
指定された入手アクションの数量を、ユーザーの現在のグレードに基づくレート乗数で乗算します。
レート乗数は指定された rateName と現在のグレード値を使用して、グレードモデルの acquireActionRates から参照されます。
乗算された入手アクションはトランザクションとして実行され、グレードに基づく報酬スケーリング(例:高グレードほど多くのリソースを獲得)を実現します。
数量指定可能なアクション:いいえ
反転可能なアクション:いいえ
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| userId | string | ✓ | ~ 128文字 | ユーザーID#{userId} と設定することでログイン中のユーザーIDに置換されます。 | ||
| gradeName | string | ✓ | ~ 128文字 | グレードモデル名 このステータスが属するグレードモデルの名前です。グレードエントリのマッピング、連動する経験値モデル、報酬加算テーブルを含むグレードモデル定義を参照します。 | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID このグレードステータスの開発者定義の識別子で、ユーザーとグレードモデル内で一意です。連動する GS2-Experience ステータスのプロパティIDと同じ値を使用することを強く推奨します。これにより、グレード値とランクキャップの正しい同期が保証されます。 | ||
| rateName | string | ✓ | ~ 128文字 | 報酬加算テーブル名 グレードモデル内でこの倍率テーブルを一意に識別する名前です。トランザクションの特定の入手アクションにグレードベースの報酬スケーリングを適用する際に参照されます。 | ||
| acquireActions | List<AcquireAction> | [] | 0 ~ 100 items | 入手アクションリスト | ||
| timeOffsetToken | string | ~ 1024文字 | タイムオフセットトークン |
{
"action": "Gs2Grade:MultiplyAcquireActionsByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"userId": "[string]ユーザーID",
"gradeName": "[string]グレードモデル名",
"propertyId": "[string]プロパティID",
"rateName": "[string]報酬加算テーブル名",
"acquireActions": [
{
"action": "[string]入手アクションで実行するアクションの種類",
"request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
}
],
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}action: Gs2Grade:MultiplyAcquireActionsByUserId
request:
namespaceName: "[string]ネームスペース名"
userId: "[string]ユーザーID"
gradeName: "[string]グレードモデル名"
propertyId: "[string]プロパティID"
rateName: "[string]報酬加算テーブル名"
acquireActions:
- action: "[string]入手アクションで実行するアクションの種類"
request: "[string]アクション実行時に使用されるリクエストのJSON文字列"
timeOffsetToken: "[string]タイムオフセットトークン"transaction.service("grade").acquire.multiply_acquire_actions_by_user_id({
namespaceName="[string]ネームスペース名",
userId="[string]ユーザーID",
gradeName="[string]グレードモデル名",
propertyId="[string]プロパティID",
rateName="[string]報酬加算テーブル名",
acquireActions={
{
action="[string]入手アクションで実行するアクションの種類",
request="[string]アクション実行時に使用されるリクエストのJSON文字列"
}
},
timeOffsetToken="[string]タイムオフセットトークン",
})