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

# GS2-Script 트랜잭션 액션

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




## 액션의 조합과 동시 실행

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

GS2-Script가 트랜잭션에 지정할 수 있는 액션은 1가지입니다. GS2-Script 자체는 사용자별 상태를 갖지 않으므로, 이 액션이 GS2-Script를 이유로 다른 것과 충돌하는 일은 없습니다. 무엇과 충돌할 수 있는지는 스크립트가 무엇을 하는지에 따라 결정됩니다.

조작 | 같은 행을 겹쳤을 때 | 중첩 너머 | 다른 대상이 되는 경계 | 직렬 실행 모드 활성화 시
--- | --- | --- | --- | ---
스크립트의 실행<br>`InvokeScript` | 통합되지 않고 각각 독립적으로 실행된다 | 통합되지 않고 각각 독립적으로 실행된다 | 실행할 때마다 다른 대상 | 변하지 않는다. 각각 독립적으로 실행되는 것은 동일하다

스크립트·사용자·인수·난수 시드가 완전히 같은 실행을 여러 개 지정한 경우에도 각각 독립적으로 실행됩니다. 다만 `acquireActionUseJobQueue`를 활성화하여 작업 큐 경유로 실행하는 경우에는 완전히 같은 실행이 한 번으로 통합될 수 있습니다.

### 제한은 스크립트가 하는 일에서 비롯됩니다

스크립트가 기록한 것은 그것을 호출한 트랜잭션에 들어갑니다. 그 때문에 그 액션을 직접 지정한 경우와 완전히 같은 방식으로, 스크립트가 건드리는 서비스의 제한이 해당됩니다. 두 실행이 모두 같은 지갑에 가산하거나, 모두 같은 도감을 다시 쓰는 경우에는 그러한 액션을 나란히 작성했을 때와 같은 제한에 부딪힙니다.

어떤 리소스를 건드리는 것이 트랜잭션 안에서 그 스크립트뿐이라면, 지금까지의 이야기는 관계없습니다. 주의가 필요한 것은 같은 리소스를 트랜잭션에 직접 지정한 액션이나 다른 스크립트도 건드리는 경우입니다.

스크립트가 자신의 트랜잭션을 발행하는 경우에는 중첩이 되어 아래의 내용이 해당됩니다.

### 중첩된 트랜잭션에 주의

안쪽 트랜잭션에서 도착하는 업데이트는 바깥쪽에 직접 지정한 액션의 대상이 아닙니다. 그 때문에 바깥쪽 트랜잭션도 기록하는 리소스에 스크립트가 기록하면, 그 리소스가 두 개의 기록을 허용하지 않는 경우에 트랜잭션이 실패합니다. 직렬 실행 모드(`enableSequentialExecution` 또는 `TransactionSettingV2`)를 활성화하면 이는 달라집니다. 스크립트의 기록도 직접 지정한 액션과 마찬가지로, 중첩을 넘어서도 같은 직렬 실행 구간을 거치게 됩니다. 이 조합이 성립하는지는 직접 지정한 두 액션의 경우와 완전히 동일하게, 기록되는 리소스의 성질에 따라 결정됩니다. 그 리소스의 액션 조합이 직렬 실행 모드로 해소되는 종류인지는 해당 리소스 자체의 트랜잭션 관련 페이지를 확인해 주십시오.

트랜잭션에 스크립트가 포함되는 경우에는 그 스크립트도 트랜잭션의 일부로서 읽어 주십시오.

### 제한을 회피하고 싶은 경우

스크립트의 실행은 획득 액션이므로, `acquireActionUseJobQueue`를 활성화하면 다른 획득 액션으로부터 분리할 수 있습니다. `enableAtomicCommit`을 비활성화하면 스크립트와 다른 액션이 한 번의 기록에 모이지 않게 됩니다.

### 동시 실행과 재시도

GS2-Script 자체가 충돌을 반환하는 일은 없습니다. 동시 실행 요청과 충돌하는지는 스크립트가 무엇을 기록하는지에 따라 결정되며, 재시도 지침도 그 서비스의 것이 해당됩니다.

---




## Acquire Action

입수 액션

### Gs2Script:InvokeScript

스크립트 실행<br>

지정된 Lua 스크립트를 제공된 JSON 인수로 동기적으로 실행합니다. 스테이터스 코드, 반환값, 트랜잭션 정보, 난수 상태, 실행 시간, 표준 출력을 포함한 실행 결과를 반환합니다. GS2 서비스 간 원자적 처리를 위한 트랜잭션 처리를 지원합니다.

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

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

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| scriptId | string |  | ✓|  |  ~ 1024자 | 스크립트 GRN |
| userId | string |  | |  |  ~ 128자 | 사용자ID<br>`#{userId}`로 설정하면 로그인 중인 사용자ID로 치환됩니다. |
| args | string |  | | "{}" |  ~ 5242880자 | 스크립트에 전달되는 인수 (JSON 형식) |
| randomStatus | [RandomStatus](../sdk/#randomstatus) |  | |  |  | 난수 상태 |
| timeOffsetToken | string |  | |  |  ~ 1024자 | 타임 오프셋 토큰 |




**JSON**
```json
{
    "action": "Gs2Script:InvokeScript",
    "request": {
        "scriptId": "[string]스크립트 GRN",
        "userId": "[string]사용자ID",
        "args": "[string]스크립트에 전달되는 인수 (JSON 형식)",
        "randomStatus": {
            "seed": "[long]난수 시드",
            "used": [
                {
                    "category": "[long]카테고리",
                    "used": "[long]사용 횟수"
                }
            ]
        },
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
```

**YAML**
```yaml

action: Gs2Script:InvokeScript
request:
  scriptId: "[string]스크립트 GRN"
  userId: "[string]사용자ID"
  args: "[string]스크립트에 전달되는 인수 (JSON 형식)"
  randomStatus: 
    seed: "[long]난수 시드"
    used: 
    - category: "[long]카테고리"
      used: "[long]사용 횟수"
  timeOffsetToken: "[string]타임 오프셋 토큰"
```

**GS2-Script**
```lua

transaction.service("script").acquire.invoke_script({
    scriptId="[string]스크립트 GRN",
    userId="[string]사용자ID",
    args="[string]스크립트에 전달되는 인수 (JSON 형식)",
    randomStatus={
        seed="[long]난수 시드",
        used={
                {
                    category="[long]카테고리",
                    used="[long]사용 횟수"
                }
            }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})
```


---