GS2-Limit 트랜잭션 액션

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

액션의 조합과 동시 실행

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

GS2-Limit의 트랜잭션 액션은 네임스페이스·사용자·횟수 제한 종류·카운터 이름의 조합으로 결정되는 하나의 카운터를 대상으로 합니다.

조작	같은 행을 겹쳤을 때	중첩 너머	다른 대상이 되는 경계
카운트업·카운트다운 `CountUpByUserId` `CountDownByUserId`	혼재해도 된다. 통합되어 값이 합산된다. 다만 `maxValue`가 다른 카운트업을 나열하면 발행 시에 오류	합산된다	네임스페이스·사용자·횟수 제한 종류·카운터 이름
카운터의 삭제 `DeleteCounterByUserId`	통합된다	실패한다	네임스페이스·사용자·횟수 제한 종류·카운터 이름
검증 `VerifyCounterByUserId`	임계값이 합산되므로 완전히 같은 검증을 두 번 작성하면 2배가 된다. 횟수가 다른 검증은 각각 판정된다	읽기만 하므로 충돌하지 않는다	카운터·검증 타입·횟수

카운트업과 카운트다운이 같은 행인 것은, 둘 다 같은 값에 대한 순수한 증분으로 기록되기 때문입니다. 혼재시켜도 됩니다. 결과는 통합 후의 합계에 대해 판정됩니다. 카운트는 0을 밑돌 수 없고 횟수 제한 종류에 설정된 상한도 넘을 수 없으므로, 단독으로는 들어가는 카운트업이라도 다른 카운트업과 합쳐지면 거부될 수 있습니다.

상한이 다른 카운트업은 같은 카운터에 나열할 수 없습니다. 상한이 어긋난 채 합산하면 엄격한 상한이 사라지거나 느슨한 가산이 엄격한 상한으로 거부되므로, maxValue가 다른 카운트업을 같은 카운터에 지정하면 발행 시에 오류가 됩니다. 나누어 지정해 주십시오.

카운터의 삭제는 값을 바꾸는 것이 아니라 카운터 자체를 지우므로, 같은 카운터를 건드리는 다른 액션과 함께 둘 수 없습니다. 카운터를 리셋한 뒤 다시 세고 싶은 경우에는 트랜잭션을 나누어 주십시오.

검증 액션은 트랜잭션 시작 시점의 카운터를 봅니다. 같은 트랜잭션에서 도달하는 카운트를 검증할 수는 없습니다.

중첩된 트랜잭션에 주의

카운트업·카운트다운은 중첩 너머에서도 안전합니다. 어느 경로로 도착하든 한 번의 업데이트로 묶입니다.

카운터의 삭제는 다릅니다. 삭제가 안쪽에서 도착하고 같은 카운터를 바깥쪽에서 세고 있는 경우에는 트랜잭션이 실패합니다.

제한을 회피하고 싶은 경우

카운트다운과 카운터의 삭제는 획득 액션, 카운트업은 소비 액션입니다. 삭제와 카운트다운의 충돌은 acquireActionUseJobQueue를 활성화하면 해소되지만, 삭제와 카운트업의 공존은 enableAtomicCommit을 비활성화하지 않으면 해소되지 않습니다.

동시 실행과 재시도

카운트업·카운트다운은 결과가 범위에 들어가는 한, 동시 실행 요청이 몇 개 겹쳐도 충돌하지 않습니다. 동시에 실행된 카운트업의 합계가 상한을 넘은 경우나, 카운트다운의 합계가 0을 밑도는 경우에 충돌(409)이 됩니다. 재시도하면 최신 카운트로 다시 판정됩니다.

카운터는 설정에 따라 정기적으로 리셋됩니다. 리셋 경계에 정확히 겹친 요청은 충돌(409)이 될 수 있습니다. 리셋이 안정된 뒤에 재시도하면 성공합니다.

Verify Action

검증 액션

Gs2Limit:VerifyCounterByUserId

사용자 ID를 지정하여 카운터 값 검증

지정된 사용자의 카운터 값이 지정된 조건을 충족하는지 검증합니다.
less, lessEqual, greater, greaterEqual, equal, notEqual의 6가지 비교 연산자를 지원합니다.

수량 지정 가능한 액션: 아니오

타입 활성화 조건 필수 기본값 값 제한 설명

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 조작으로 증가하며, 이때 지정된 최대값과 비교됩니다. 사용 횟수 제한 모델의 리셋 시점에 도달하면 자동으로 0으로 리셋됩니다.

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]타임 오프셋 토큰",
})