GS2-Ranking2 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.

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.

A score is a state rather than a per-unit amount, so its thresholds are not added up by default. Verifying “at least 100” together with “at least 500” checks both, and the stricter one is what effectively applies.

The threshold is added up only when multiplyValueSpecifyingQuantity is explicitly true, and only where adding it up makes the check stricter. Leaving it unset keeps the behaviour above. When it is explicitly true the verify type does not matter: writing it declares that the threshold is the amount for one unit, so it is added up and scaled for every verify type. Note that less and lessEqual therefore get looser as the quantity grows, so specify it deliberately.

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.

Turning on sequential execution mode (enableSequentialExecution or TransactionSettingV2) does not remove this failure. The record is written only where it does not already exist, and combining the inner and outer records into a single write would lose that guard, so the two are still rejected (400).

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

• Format:
• JSON
• YAML
• GS2-Script

{
    "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

• Format:
• JSON
• YAML
• GS2-Script

{
    "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

• Format:
• JSON
• YAML
• GS2-Script

{
    "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

• Format:
• JSON
• YAML
• GS2-Script

{
    "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

• Format:
• JSON
• YAML
• GS2-Script

{
    "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",
})