Documentation index for AI agents

GS2-AdReward 트랜잭션 액션

검증/소비/입수 각 트랜잭션 액션의 사양
Tags:

액션의 조합과 동시 실행

모든 서비스에 공통되는 전제는 트랜잭션 액션의 조합에 정리되어 있습니다. 먼저 그쪽을 읽어 주십시오. 이 절의 나머지는 GS2-AdReward 고유의 내용입니다.

GS2-AdReward의 트랜잭션 액션은 네임스페이스와 사용자별로 하나만 존재하는 포인트 잔액을 대상으로 합니다.

조작같은 행을 겹쳤을 때중첩 너머다른 대상이 되는 경계
포인트의 획득
AcquirePointByUserId		통합되어 포인트가 합산된다합산된다네임스페이스·사용자
포인트의 소비
ConsumePointByUserId		통합되어 합계액으로 잔액이 판정된다합산된다. 다만 합계가 잔액을 초과한 경우에는 충돌(409)이 되며, 잔액이 늘지 않는 한 재시도해도 해소되지 않는다네임스페이스·사용자

두 행 모두 같은 잔액에 대한 순수한 증분으로 기록되므로, 획득과 소비를 함께 두어도 각각이 적용됩니다. 획득 100과 획득 50을 지정하면 포인트 150의 획득 1건으로 취급됩니다. 잔액 100에 대해 소비 60과 소비 30을 지정하면 잔액은 10이 되고, 소비 60과 획득 200을 지정하면 잔액은 240이 됩니다.

소비의 합계가 시작 시점의 잔액을 초과하는 경우에는 포인트 부족 오류(400)가 되며, 한쪽만 적용되는 일은 없습니다.

트랜잭션 안에서 획득한 포인트는 같은 트랜잭션의 소비에 사용할 수 없습니다. 소비 액션은 반드시 획득 액션보다 먼저 실행되므로, 사용할 수 있는 것은 시작 시점의 잔액뿐입니다. 필요한 경우에는 트랜잭션을 나누어 주십시오.

중첩된 트랜잭션에 주의

GS2-AdReward는 이 상황을 견딜 수 있습니다. 서로 다른 트랜잭션에서 도착한 증감도 최종적으로는 잔액에 대한 한 번의 업데이트로 묶여 적용되므로 충돌하지 않습니다. 예외는 이 경로로 나뉘어 도착한 소비의 합계가 잔액을 초과한 경우로, 그때는 포인트 부족 오류(400)가 아니라 충돌(409)로 트랜잭션이 거부되며 잔액은 변하지 않습니다. 잔액이 늘지 않는 한 재시도해도 성공하지 않습니다.

제한을 회피하고 싶은 경우

위의 제한은 실행 순서에서 비롯되므로, enableAtomicCommit이나 acquireActionUseJobQueue를 바꾸어도 해소되지 않습니다. 획득한 포인트를 소비에 사용하고 싶은 경우에는 트랜잭션을 나누어 주십시오.

동시 실행과 재시도

획득 액션끼리, 그리고 획득 액션과 소비 액션의 동시 실행은 증감이 각각 확실히 반영되므로 원칙적으로 충돌하지 않습니다.

같은 포인트 잔액에 대한 업데이트가 짧은 시간에 집중된 경우에는 일시적인 충돌(409)이 반환될 수 있습니다. 잔액이 원인이 아니므로 조금 간격을 두고 재시도하면 성공합니다.

서로 다른 트랜잭션의 소비 액션이 동시에 실행되어 합계가 잔액을 초과한 경우에는 충돌(409)이 될 수 있습니다. 재시도하면 최신 잔액으로 다시 판정되므로, 그 시점에 잔액이 충분하면 성공하고 부족하면 포인트 부족 오류(400)가 반환됩니다.

Consume Action

소비 액션

Gs2AdReward:ConsumePointByUserId

사용자 ID를 지정하여 포인트 소비

지정된 사용자 ID로부터 지정된 수의 포인트를 차감하고, 갱신된 포인트 정보를 반환합니다.
요청된 소비량에 대해 포인트가 부족한 경우 오류가 반환됩니다.
네임스페이스의 소비 스크립트 설정에 GS2-Script가 설정되어 있는 경우, 포인트 차감 전에 스크립트가 실행되어 커스텀 검증이나 소비량 변경이 가능합니다.
포인트 차감 후, 네임스페이스 설정에서 변경 알림이 구성되어 있으면 알림이 전송됩니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
✓
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
✓
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
pointlong
✓
1 ~ 9223372036854775805소비할 포인트
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2AdReward:ConsumePointByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "point": "[long]소비할 포인트",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2AdReward:ConsumePointByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  point: "[long]소비할 포인트"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("adReward").consume.consume_point_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    point="[long]소비할 포인트",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Acquire Action

입수 액션

Gs2AdReward:AcquirePointByUserId

사용자 ID를 지정하여 포인트 획득

지정된 사용자 ID에 지정된 수의 포인트를 추가하고, 갱신된 포인트 정보를 반환합니다.
사용자의 포인트 레코드가 존재하지 않는 경우, 포인트 추가 전에 새로운 레코드가 자동으로 생성됩니다.
네임스페이스의 획득 스크립트 설정에 GS2-Script가 설정되어 있는 경우, 포인트 추가 전에 스크립트가 실행되어 커스텀 검증이나 획득량 변경이 가능합니다.
포인트 추가 후, 네임스페이스 설정에서 변경 알림이 구성되어 있으면 알림이 전송됩니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
✓
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
✓
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
pointlong
✓
1 ~ 9223372036854775805획득할 포인트
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2AdReward:AcquirePointByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "point": "[long]획득할 포인트",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2AdReward:AcquirePointByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  point: "[long]획득할 포인트"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("adReward").acquire.acquire_point_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    point="[long]획득할 포인트",
    timeOffsetToken="[string]타임 오프셋 토큰",
})