> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Grade 트랜잭션 액션

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




## Verify Action

검증 액션

### Gs2Grade:VerifyGradeByUserId

사용자 ID를 지정하여 그레이드 검증<br>

지정된 사용자의 그레이드 값이 지정된 조건을 만족하는지 검증합니다(서버 사이드 작업).<br>
6가지 비교 연산자를 지원합니다: less(미만), lessEqual(이하), greater(초과), greaterEqual(이상), equal(일치), notEqual(불일치).<br>
조건이 충족되지 않은 경우, 기대값과 실제 값을 포함한 설명적인 오류 메시지가 반환됩니다.<br>
multiplyValueSpecifyingQuantity가 true인 경우, 검증 임계값은 지정된 수량으로 곱해집니다.

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

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| gradeName | string |  | ✓|  |  ~ 128자 | 그레이드 모델 이름<br>이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다. |
| verifyType | 문자열 열거형<br>enum {<br>"less",<br>"lessEqual",<br>"greater",<br>"greaterEqual",<br>"equal",<br>"notEqual"<br>}<br> |  | ✓|  |  | 검증 종류less: 그레이드가 지정한 값 미만일 것 / lessEqual: 그레이드가 지정한 값 이하일 것 / greater: 그레이드가 지정한 값을 초과할 것 / greaterEqual: 그레이드가 지정한 값 이상일 것 / equal: 그레이드가 지정한 값과 일치할 것 / notEqual: 그레이드가 지정한 값과 일치하지 않을 것 /  |
| propertyId | string |  | ✓|  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |
| gradeValue | long |  | | 1 | 1 ~ 9223372036854775805 | 현재 그레이드<br>이 스테이터스의 현재 그레이드 값입니다. 연동되는 GS2-Experience 모델의 랭크 캡을 결정하기 위해 그레이드 모델의 그레이드 엔트리 배열의 인덱스로 사용됩니다. 이 값이 변경되면 관련된 경험치 스테이터스의 랭크 캡이 해당 그레이드 엔트리에서 정의된 값으로 자동 갱신됩니다. |
| multiplyValueSpecifyingQuantity | bool |  | | false |  | 수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Grade:VerifyGradeByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "gradeName": "[string]그레이드 모델 이름",
        "verifyType": "[string]검증 종류",
        "propertyId": "[string]프로퍼티 ID",
        "gradeValue": "[long]현재 그레이드",
        "multiplyValueSpecifyingQuantity": "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:VerifyGradeByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  gradeName: "[string]그레이드 모델 이름"
  verifyType: "[string]검증 종류"
  propertyId: "[string]프로퍼티 ID"
  gradeValue: "[long]현재 그레이드"
  multiplyValueSpecifyingQuantity: "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

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를 지정하여 그레이드업에 사용하는 소재 검증<br>

지정된 사용자의 지정된 프로퍼티의 그레이드업에 소재의 프로퍼티 ID가 유효한지 검증합니다(서버 사이드 작업).<br>
검증은 그레이드 엔트리의 PropertyIdRegex와 GradeUpPropertyIdRegex로부터 정규표현식 패턴을 생성하고, 소재의 프로퍼티 ID가 이에 일치하는지 확인합니다.<br>
2가지 검증 유형을 지원합니다: 'match'(소재가 패턴에 일치해야 함)와 'notMatch'(소재가 패턴에 일치하지 않아야 함).

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

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| gradeName | string |  | ✓|  |  ~ 128자 | 그레이드 모델 이름<br>이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다. |
| verifyType | 문자열 열거형<br>enum {<br>"match",<br>"notMatch"<br>}<br> |  | ✓|  |  | 검증 종류match: 조건과 일치할 것 / notMatch: 조건과 일치하지 않을 것 /  |
| propertyId | string |  | ✓|  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |
| materialPropertyId | string |  | ✓|  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Grade:VerifyGradeUpMaterialByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "gradeName": "[string]그레이드 모델 이름",
        "verifyType": "[string]검증 종류",
        "propertyId": "[string]프로퍼티 ID",
        "materialPropertyId": "[string]프로퍼티 ID",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:VerifyGradeUpMaterialByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  gradeName: "[string]그레이드 모델 이름"
  verifyType: "[string]검증 종류"
  propertyId: "[string]프로퍼티 ID"
  materialPropertyId: "[string]프로퍼티 ID"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

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를 지정하여 그레이드 감산<br>

지정된 그레이드 모델과 프로퍼티에 대해, 지정된 사용자의 현재 그레이드에서 지정된 값을 감산합니다(서버 사이드 작업).<br>
그레이드 값 갱신 후, 연결된 GS2-Experience 스테이터스에 랭크 캡이 자동으로 적용됩니다.<br>
랭크 캡 값은 새로운 그레이드 레벨에 일치하는 그레이드 엔트리에 의해 결정됩니다.<br>
갱신된 그레이드 스테이터스와 함께 Experience 네임스페이스명과 갱신된 Experience 스테이터스를 반환합니다.

**수량 지정 가능한 액션: 예**

**반전 가능한 액션: 예**

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| gradeName | string |  | ✓|  |  ~ 128자 | 그레이드 모델 이름<br>이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다. |
| propertyId | string |  | ✓|  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |
| gradeValue | long |  | | 0 | 0 ~ 9223372036854775805 | 잃는 그레이드 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Grade:SubGradeByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "gradeName": "[string]그레이드 모델 이름",
        "propertyId": "[string]프로퍼티 ID",
        "gradeValue": "[long]잃는 그레이드",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:SubGradeByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  gradeName: "[string]그레이드 모델 이름"
  propertyId: "[string]프로퍼티 ID"
  gradeValue: "[long]잃는 그레이드"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

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를 지정하여 그레이드 가산<br>

지정된 그레이드 모델과 프로퍼티에 대해, 사용자의 현재 그레이드에 지정된 값을 가산합니다.<br>
그레이드 값 갱신 후, 연결된 GS2-Experience 스테이터스에 랭크 캡이 자동으로 적용됩니다.<br>
랭크 캡 값은 새로운 그레이드 레벨에 일치하는 그레이드 엔트리에 의해 결정됩니다.<br>
갱신된 그레이드 스테이터스와 함께 Experience 네임스페이스명과 갱신된 Experience 스테이터스를 반환합니다.

**수량 지정 가능한 액션: 예**

**반전 가능한 액션: 예**

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| gradeName | string |  | ✓|  |  ~ 128자 | 그레이드 모델 이름<br>이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다. |
| propertyId | string |  | ✓|  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |
| gradeValue | long |  | | 0 | 0 ~ 9223372036854775805 | 획득 그레이드 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Grade:AddGradeByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "gradeName": "[string]그레이드 모델 이름",
        "propertyId": "[string]프로퍼티 ID",
        "gradeValue": "[long]획득 그레이드",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:AddGradeByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  gradeName: "[string]그레이드 모델 이름"
  propertyId: "[string]프로퍼티 ID"
  gradeValue: "[long]획득 그레이드"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

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 스테이터스에 랭크 캡 적용<br>

지정된 사용자의 현재 그레이드에 대응하는 랭크 캡을, 연결된 GS2-Experience 스테이터스에 적용합니다(서버 사이드 작업).<br>
현재 그레이드 값에 일치하는 그레이드 엔트리를 참조하여 랭크 캡 값을 결정합니다.<br>
그레이드가 외부에서 변경되어 Experience의 랭크 캡을 동기화해야 할 경우에 유용합니다.<br>
갱신된 그레이드 스테이터스와 함께 Experience 네임스페이스명과 갱신된 Experience 스테이터스를 반환합니다.

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

**반전 가능한 액션: 아니오**

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| gradeName | string |  | ✓|  |  ~ 128자 | 그레이드 모델 이름<br>이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다. |
| propertyId | string |  | ✓|  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Grade:ApplyRankCapByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "gradeName": "[string]그레이드 모델 이름",
        "propertyId": "[string]프로퍼티 ID",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:ApplyRankCapByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  gradeName: "[string]그레이드 모델 이름"
  propertyId: "[string]프로퍼티 ID"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("grade").acquire.apply_rank_cap_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    gradeName="[string]그레이드 모델 이름",
    propertyId="[string]프로퍼티 ID",
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---

### Gs2Grade:MultiplyAcquireActionsByUserId

그레이드에 기반한 레이트로 입수 액션을 곱셈<br>

지정된 입수 액션의 수량을 사용자의 현재 그레이드에 기반한 레이트 승수로 곱합니다.<br>
레이트 승수는 지정된 rateName과 현재 그레이드 값을 사용하여 그레이드 모델의 acquireActionRates에서 조회됩니다.<br>
곱해진 입수 액션은 트랜잭션으로 실행되며, 그레이드에 기반한 보상 스케일링(예: 그레이드가 높을수록 더 많은 리소스를 획득)을 실현합니다.

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

**반전 가능한 액션: 아니오**

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| gradeName | string |  | ✓|  |  ~ 128자 | 그레이드 모델 이름<br>이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다. |
| propertyId | string |  | ✓|  |  ~ 1024자 | 프로퍼티 ID<br>이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다. |
| rateName | string |  | ✓|  |  ~ 128자 | 보상 가산 테이블 이름<br>그레이드 모델 내에서 이 배율 테이블을 고유하게 식별하는 이름입니다. 트랜잭션의 특정 입수 액션에 그레이드 기반 보상 스케일링을 적용할 때 참조됩니다. |
| acquireActions | List&lt;AcquireAction&gt; |  | | [] | 0 ~ 100 items | 입수 액션 목록 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Grade:MultiplyAcquireActionsByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "gradeName": "[string]그레이드 모델 이름",
        "propertyId": "[string]프로퍼티 ID",
        "rateName": "[string]보상 가산 테이블 이름",
        "acquireActions": [
            {
                "action": "[string]입수 액션에서 실행할 액션의 종류",
                "request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:MultiplyAcquireActionsByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  gradeName: "[string]그레이드 모델 이름"
  propertyId: "[string]프로퍼티 ID"
  rateName: "[string]보상 가산 테이블 이름"
  acquireActions: 
    - action: "[string]입수 액션에서 실행할 액션의 종류"
      request: "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

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


---