GS2-Ranking2 Transaction Actions

Specification of verify/consume/acquire transaction actions

Combining actions, and concurrency

The background common to every service is collected in Combining Transaction Actions. Read that first; the rest of this section is what GS2-Ranking2 adds to it.

The transaction actions of GS2-Ranking2 address two kinds of target: the record that a season reward has been taken, and the score read by a verify action. Records are split per ranking and per season, so actions of GS2-Ranking2 rarely collide with each other.

Operation	Repeated in one transaction	Across a nested transaction	Boundary that separates targets
Recording a receipt `CreateGlobalRankingReceivedRewardByUserId` `CreateClusterRankingReceivedRewardByUserId`	Combined into one	Fails	namespace, user, ranking, season, cluster
Verifying a score `VerifyGlobalRankingScoreByUserId` `VerifyClusterRankingScoreByUserId` `VerifySubscribeRankingScoreByUserId`	Ones with the same threshold are gathered into one; ones with differing thresholds are each judged	No collision, because they only read	ranking, season, verify type

A record is written only if it does not already exist, which is what stops a season reward from being taken twice. Recording the same receipt a second time fails, whether from the same transaction or a later one.

Unlike a consumable amount, a score threshold is not a quantity to be summed, so the thresholds are not added up: verifying “at least 100” together with “at least 500” checks both, and the stricter one is what effectively applies.

Verify actions look at the score as of the start of the transaction. Registering a score is an API rather than a transaction action, so a transaction cannot register a score and then verify it.

Recording a receipt is only a mark. The season reward itself is issued as a transaction of its own, so the restrictions of whichever services it belongs to apply, and so does “Take care with nested transactions” below.

Take care with nested transactions

Recording the same receipt both from the inside and from the outside makes the transaction fail. Because the reward is issued as an inner transaction, what it grants gathers into the same transaction as everything else: check the pages of the services those belong to.

If you want to avoid these restrictions

Recording a receipt is a consume action, so acquireActionUseJobQueue cannot separate them. Turning enableAtomicCommit off clears a collision between the inside and the outside, but weigh that decision carefully: once a receipt is recorded, it is not undone if granting the reward fails afterwards.

Concurrency and retries

Records are split per season, so concurrent requests rarely conflict. The one case that fails is recording a receipt that has already been recorded, and that is the guard against taking a season reward twice; retrying does not change it.

Verify Action

Gs2Ranking2:VerifyGlobalRankingScoreByUserId

Verify the score of the global ranking specifying User ID

Verifies the global ranking score of the specified user against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual).

Quantity specification supported: YES

Type Condition Required Default Value Limits Description

namespaceName

string

✓

~ 128 chars

Namespace name

Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

userId

string

✓

~ 128 chars

User ID
Specify #{userId} to substitute the currently logged-in user’s ID.

rankingName

string

✓

~ 128 chars

Global Ranking Model name

Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

verifyType

string (enum)
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}

✓

Type of verification

Definition	Description
less	Score is less than the specified value
lessEqual	Score is less than or equal to the specified value
greater	Score is greater than the specified value
greaterEqual	Score is greater than or equal to the specified value
equal	Score is equal to the specified value
notEqual	Score is not equal to the specified value

season long 0 ~ 9223372036854775805 Season

score

long

✓

0 ~ 9223372036854775805

Score

The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings.

multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity

timeOffsetToken string ~ 1024 chars Time offset token

{
    "action": "Gs2Ranking2:VerifyGlobalRankingScoreByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "rankingName": "[string]Global Ranking Model name",
        "verifyType": "[string]Type of verification",
        "season": "[long]Season",
        "score": "[long]Score",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Ranking2:VerifyGlobalRankingScoreByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  rankingName: "[string]Global Ranking Model name"
  verifyType: "[string]Type of verification"
  season: "[long]Season"
  score: "[long]Score"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"

transaction.service("ranking2").verify.verify_global_ranking_score_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    rankingName="[string]Global Ranking Model name",
    verifyType="[string]Type of verification",
    season="[long]Season",
    score="[long]Score",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Gs2Ranking2:VerifyClusterRankingScoreByUserId

Verify the score of the cluster ranking specifying User ID

Verifies the cluster ranking score of the specified user against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual).

Quantity specification supported: YES

Type Condition Required Default Value Limits Description

namespaceName

string

✓

~ 128 chars

Namespace name

Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

userId

string

✓

~ 128 chars

User ID
Specify #{userId} to substitute the currently logged-in user’s ID.

rankingName

string

✓

~ 128 chars

Cluster Ranking Model name

Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

clusterName

string

✓

~ 1024 chars

Cluster Name

The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member.

verifyType

string (enum)
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}

✓

Type of verification

Definition	Description
less	Score is less than the specified value
lessEqual	Score is less than or equal to the specified value
greater	Score is greater than the specified value
greaterEqual	Score is greater than or equal to the specified value
equal	Score is equal to the specified value
notEqual	Score is not equal to the specified value

season long 0 ~ 9223372036854775805 Season

score

long

✓

0 ~ 9223372036854775805

Score

The score value submitted by the user within this cluster.

multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity

timeOffsetToken string ~ 1024 chars Time offset token

{
    "action": "Gs2Ranking2:VerifyClusterRankingScoreByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "rankingName": "[string]Cluster Ranking Model name",
        "clusterName": "[string]Cluster Name",
        "verifyType": "[string]Type of verification",
        "season": "[long]Season",
        "score": "[long]Score",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Ranking2:VerifyClusterRankingScoreByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  rankingName: "[string]Cluster Ranking Model name"
  clusterName: "[string]Cluster Name"
  verifyType: "[string]Type of verification"
  season: "[long]Season"
  score: "[long]Score"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"

transaction.service("ranking2").verify.verify_cluster_ranking_score_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    rankingName="[string]Cluster Ranking Model name",
    clusterName="[string]Cluster Name",
    verifyType="[string]Type of verification",
    season="[long]Season",
    score="[long]Score",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Gs2Ranking2:VerifySubscribeRankingScoreByUserId

Verify the score of the subscribe ranking specifying User ID

Verifies the subscribe ranking score of the specified user against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual).

Quantity specification supported: YES

Type Condition Required Default Value Limits Description

namespaceName

string

✓

~ 128 chars

Namespace name

Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

userId

string

✓

~ 128 chars

User ID
Specify #{userId} to substitute the currently logged-in user’s ID.

rankingName

string

✓

~ 128 chars

Subscribe Ranking Model name

Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

verifyType

string (enum)
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}

✓

Type of verification

Definition	Description
less	Score is less than the specified value
lessEqual	Score is less than or equal to the specified value
greater	Score is greater than the specified value
greaterEqual	Score is greater than or equal to the specified value
equal	Score is equal to the specified value
notEqual	Score is not equal to the specified value

season long 0 ~ 9223372036854775805 Season

score

long

✓

0 ~ 9223372036854775805

Score

multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity

timeOffsetToken string ~ 1024 chars Time offset token

{
    "action": "Gs2Ranking2:VerifySubscribeRankingScoreByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "rankingName": "[string]Subscribe Ranking Model name",
        "verifyType": "[string]Type of verification",
        "season": "[long]Season",
        "score": "[long]Score",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Ranking2:VerifySubscribeRankingScoreByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  rankingName: "[string]Subscribe Ranking Model name"
  verifyType: "[string]Type of verification"
  season: "[long]Season"
  score: "[long]Score"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"

transaction.service("ranking2").verify.verify_subscribe_ranking_score_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    rankingName="[string]Subscribe Ranking Model name",
    verifyType="[string]Type of verification",
    season="[long]Season",
    score="[long]Score",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Consume Action

Gs2Ranking2:CreateGlobalRankingReceivedRewardByUserId

Record global ranking reward receipt history specifying User ID

Records a reward receipt history for the specified global ranking on behalf of the specified user.

Quantity specification supported: NO

Reversible action: NO

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
rankingName	string	✓	~ 128 chars	Global Ranking Model name Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓	~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
season	long		0 ~ 9223372036854775805	Season
timeOffsetToken	string		~ 1024 chars	Time offset token

{
    "action": "Gs2Ranking2:CreateGlobalRankingReceivedRewardByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "rankingName": "[string]Global Ranking Model name",
        "userId": "[string]User ID",
        "season": "[long]Season",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Ranking2:CreateGlobalRankingReceivedRewardByUserId
request:
  namespaceName: "[string]Namespace name"
  rankingName: "[string]Global Ranking Model name"
  userId: "[string]User ID"
  season: "[long]Season"
  timeOffsetToken: "[string]Time offset token"

transaction.service("ranking2").consume.create_global_ranking_received_reward_by_user_id({
    namespaceName="[string]Namespace name",
    rankingName="[string]Global Ranking Model name",
    userId="[string]User ID",
    season="[long]Season",
    timeOffsetToken="[string]Time offset token",
})

Gs2Ranking2:CreateClusterRankingReceivedRewardByUserId

Record Cluster Ranking Reward Received History by User ID

Records a reward receipt history for the specified cluster ranking and cluster on behalf of the specified user.

Quantity specification supported: NO

Reversible action: NO

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
rankingName	string	✓	~ 128 chars	Cluster Ranking Model name Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
clusterName	string	✓	~ 1024 chars	Cluster Name The name of the cluster for which the ranking reward was received.
userId	string	✓	~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
season	long		0 ~ 9223372036854775805	Season
timeOffsetToken	string		~ 1024 chars	Time offset token

{
    "action": "Gs2Ranking2:CreateClusterRankingReceivedRewardByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "rankingName": "[string]Cluster Ranking Model name",
        "clusterName": "[string]Cluster Name",
        "userId": "[string]User ID",
        "season": "[long]Season",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Ranking2:CreateClusterRankingReceivedRewardByUserId
request:
  namespaceName: "[string]Namespace name"
  rankingName: "[string]Cluster Ranking Model name"
  clusterName: "[string]Cluster Name"
  userId: "[string]User ID"
  season: "[long]Season"
  timeOffsetToken: "[string]Time offset token"

transaction.service("ranking2").consume.create_cluster_ranking_received_reward_by_user_id({
    namespaceName="[string]Namespace name",
    rankingName="[string]Cluster Ranking Model name",
    clusterName="[string]Cluster Name",
    userId="[string]User ID",
    season="[long]Season",
    timeOffsetToken="[string]Time offset token",
})