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

# GS2-Exchange 트랜잭션 액션

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





## Consume Action

소비 액션

### Gs2Exchange:DeleteAwaitByUserId

사용자 ID를 지정하여 교환 대기 삭제<br>

지정된 사용자의 교환 대기 레코드를 삭제합니다.<br>
보류 중인 교환이 취소되며, 아직 취득하지 않은 보상은 포기됩니다.

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

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

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| awaitName | string |  | ✓| UUID |  ~ 36자 | 교환 대기의 이름<br>교환 대기의 고유한 이름을 보유합니다.<br>이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 교환 대기를 식별하는 데 사용됩니다. |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Exchange:DeleteAwaitByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "awaitName": "[string]교환 대기의 이름",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Exchange:DeleteAwaitByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  awaitName: "[string]교환 대기의 이름"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("exchange").consume.delete_await_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    awaitName="[string]교환 대기의 이름",
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---

## Acquire Action

입수 액션

### Gs2Exchange:ExchangeByUserId

사용자 ID를 지정하여 교환을 실행<br>

지정된 사용자에 대해, 지정된 교환 레이트 모델에 기반하여 리소스 교환을 실행합니다.<br>
레이트 모델의 타이밍 타입을 검증합니다: 'immediate' 타이밍의 경우 네임스페이스에서 직접 교환이 유효해야 하며, 'await' 타이밍의 경우 대기 교환이 유효해야 합니다.<br>
레이트 모델에서 정의된 소비·검증·획득 액션을 지정한 횟수만큼 실행하는 트랜잭션이 발행됩니다.

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

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

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rateName | string |  | ✓|  |  ~ 128자 | 교환 레이트 모델 이름<br>교환 레이트 모델 종류 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| count | int |  | ✓|  | 1 ~ 1073741821 | 교환 횟수 |
| config | List&lt;Config&gt; |  | | [] | 0 ~ 32 items | 트랜잭션 변수에 적용할 설정값 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Exchange:ExchangeByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "rateName": "[string]교환 레이트 모델 이름",
        "userId": "[string]사용자ID",
        "count": "[int]교환 횟수",
        "config": [
            {
                "key": "[string]이름",
                "value": "[string]값"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Exchange:ExchangeByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  rateName: "[string]교환 레이트 모델 이름"
  userId: "[string]사용자ID"
  count: "[int]교환 횟수"
  config: 
    - key: "[string]이름"
      value: "[string]값"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("exchange").acquire.exchange_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    rateName="[string]교환 레이트 모델 이름",
    userId="[string]사용자ID",
    count="[int]교환 횟수",
    config={
        {
            key="[string]이름",
            value="[string]값"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---

### Gs2Exchange:IncrementalExchangeByUserId

사용자 ID를 지정하여 코스트 상승형 교환 실행<br>

지정된 사용자에 대해, 지정된 코스트 상승형 교환 레이트 모델을 기반으로, 실행 횟수에 따라 코스트가 단계적으로 상승하는 리소스 교환을 실행합니다.<br>
소비 코스트는 모델의 계산 타입(선형 계산식 또는 GS2-Script)과 현재 교환 횟수를 기반으로 계산됩니다.<br>
소비·획득 액션을 실행하는 트랜잭션이 발행됩니다.

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

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

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rateName | string |  | ✓|  |  ~ 128자 | 코스트 상승형 교환 레이트 모델의 이름<br>코스트 상승형 교환 레이트 모델 종류 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| count | int |  | ✓|  | 1 ~ 1073741821 | 교환 횟수 |
| config | List&lt;Config&gt; |  | | [] | 0 ~ 32 items | 트랜잭션 변수에 적용할 설정값 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Exchange:IncrementalExchangeByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "rateName": "[string]코스트 상승형 교환 레이트 모델의 이름",
        "userId": "[string]사용자ID",
        "count": "[int]교환 횟수",
        "config": [
            {
                "key": "[string]이름",
                "value": "[string]값"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Exchange:IncrementalExchangeByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  rateName: "[string]코스트 상승형 교환 레이트 모델의 이름"
  userId: "[string]사용자ID"
  count: "[int]교환 횟수"
  config: 
    - key: "[string]이름"
      value: "[string]값"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("exchange").acquire.incremental_exchange_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    rateName="[string]코스트 상승형 교환 레이트 모델의 이름",
    userId="[string]사용자ID",
    count="[int]교환 횟수",
    config={
        {
            key="[string]이름",
            value="[string]값"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---

### Gs2Exchange:CreateAwaitByUserId

사용자 ID를 지정하여 교환 대기를 작성<br>

시간 대기형 교환의 새로운 교환 대기 레코드를 작성합니다.<br>
지정된 레이트 모델의 타이밍 타입은 'await'이어야 하며, 그렇지 않은 경우 요청이 거부됩니다.<br>
대기는 스킵 초수 0으로 시작되며, 레이트 모델에서 정의된 잠금 시간이 보상 획득까지의 사용자 대기 시간을 결정합니다.<br>
작성 시 기본 설정값을 지정할 수 있으며, 획득 시 제공되는 설정값과 병합됩니다.

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

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

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| rateName | string |  | ✓|  |  ~ 128자 | 교환 레이트 모델 이름<br>교환 레이트 모델 종류 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| count | int |  | | 1 | 1 ~ 10000 | 교환 수<br>이 교환을 실행하는 횟수입니다. 여러 번의 교환을 하나의 대기로 묶을 수 있으며, 소비되는 코스트와 받는 보상이 모두 곱해집니다. |
| config | List&lt;Config&gt; |  | | [] | 0 ~ 32 items | 보상 획득 시 적용하는 기본 설정값 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Exchange:CreateAwaitByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "rateName": "[string]교환 레이트 모델 이름",
        "count": "[int]교환 수",
        "config": [
            {
                "key": "[string]이름",
                "value": "[string]값"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Exchange:CreateAwaitByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  rateName: "[string]교환 레이트 모델 이름"
  count: "[int]교환 수"
  config: 
    - key: "[string]이름"
      value: "[string]값"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("exchange").acquire.create_await_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    rateName="[string]교환 레이트 모델 이름",
    count="[int]교환 수",
    config={
        {
            key="[string]이름",
            value="[string]값"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---

### Gs2Exchange:AcquireForceByUserId

교환 대기의 보상을 대기 시간 판정 없이 강제 취득<br>

잠금 시간이 경과했는지 여부와 관계없이 교환 대기의 보상을 강제로 취득합니다.<br>
일반적인 대기 시간 확인을 우회하여 즉시 보상을 취득할 수 있습니다.<br>
제공된 설정값은 대기 작성 시 설정된 기본 설정값과 병합됩니다.<br>
레이트 모델에서 정의된 획득 액션을 실행하는 트랜잭션이 발행됩니다.

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

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

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| awaitName | string |  | ✓| UUID |  ~ 36자 | 교환 대기의 이름<br>교환 대기의 고유한 이름을 보유합니다.<br>이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 교환 대기를 식별하는 데 사용됩니다. |
| config | List&lt;Config&gt; |  | | [] | 0 ~ 32 items | 트랜잭션 변수에 적용할 설정값 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Exchange:AcquireForceByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "awaitName": "[string]교환 대기의 이름",
        "config": [
            {
                "key": "[string]이름",
                "value": "[string]값"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Exchange:AcquireForceByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  awaitName: "[string]교환 대기의 이름"
  config: 
    - key: "[string]이름"
      value: "[string]값"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("exchange").acquire.acquire_force_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    awaitName="[string]교환 대기의 이름",
    config={
        {
            key="[string]이름",
            value="[string]값"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---

### Gs2Exchange:SkipByUserId

사용자 ID를 지정하여 교환 대기를 스킵<br>

교환 대기의 대기 시간을 가속하거나 스킵합니다.<br>
4가지 스킵 타입을 지원합니다: 'complete'는 남은 대기 시간을 전부 스킵하고, 'minutes'는 지정한 분수를 스킵 초수에 더하며, 'totalRate'는 전체 잠금 시간의 비율만큼 스킵하고, 'remainRate'는 남은 대기 시간의 비율만큼 스킵합니다.<br>
스킵 초수는 합계 잠금 시간이 상한이 되며, 이를 초과할 수 없습니다.

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

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

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string |  | ✓|  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| awaitName | string |  | ✓| UUID |  ~ 36자 | 교환 대기의 이름<br>교환 대기의 고유한 이름을 보유합니다.<br>이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 교환 대기를 식별하는 데 사용됩니다. |
| skipType | 문자열 열거형<br>enum {<br>"complete",<br>"minutes",<br>"totalRate",<br>"remainRate"<br>}<br> |  | | "complete" |  | 스킵 방법complete: 완전히 스킵 / minutes: 시간을 지정하여 스킵(분) / totalRate: 전체 대기 시간의 비율을 지정하여 스킵 / remainRate: 남은 대기 시간의 비율을 지정하여 스킵 /  |
| minutes | int | {skipType} == "minutes" | |  | 0 ~ 2147483646 | 스킵할 분수<br>※ skipType이(가) "minutes" 이면 활성화 |
| rate | float | {skipType} == "totalRate" or {skipType} == "remainRate" | |  | 0 ~ 1 | 스킵할 대기 시간의 비율 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Exchange:SkipByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "awaitName": "[string]교환 대기의 이름",
        "skipType": "[string]스킵 방법",
        "minutes": "[int]스킵할 분수",
        "rate": "[float]스킵할 대기 시간의 비율",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Exchange:SkipByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  awaitName: "[string]교환 대기의 이름"
  skipType: "[string]스킵 방법"
  minutes: "[int]스킵할 분수"
  rate: "[float]스킵할 대기 시간의 비율"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("exchange").acquire.skip_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    awaitName="[string]교환 대기의 이름",
    skipType="[string]스킵 방법",
    minutes="[int]스킵할 분수",
    rate="[float]스킵할 대기 시간의 비율",
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---