Documentation index for AI agents

GS2-Formation 트랜잭션 액션

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

액션의 조합과 동시 실행

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

GS2-Formation의 트랜잭션 액션은 2종류의 대상을 다룹니다.

  • 몰드 : 네임스페이스·사용자·몰드 모델의 조합으로 결정됩니다. 폼을 몇 개 가질 수 있는지라는 용량을 보관합니다.
  • 폼 : 네임스페이스·사용자·몰드 모델·인덱스의 조합으로 결정됩니다. 하나의 슬롯에 설정된 프로퍼티를 보관합니다.
조작같은 행을 겹쳤을 때중첩 너머다른 대상이 되는 경계
용량의 가산·감산
AddMoldCapacityByUserId SubMoldCapacityByUserId
혼재해도 된다. 통합되어 값이 합산된다합산된다네임스페이스·사용자·몰드 모델
용량의 설정
SetMoldCapacityByUserId
같은 값이면 통합. 값이 다르면 발행 시에 오류같은 값이면 그 값이 설정된다. 값이 다르면 실행 시에 실패한다네임스페이스·사용자·몰드 모델
폼의 설정
SetFormByUserId
같은 값이면 통합. 값이 다르면 발행 시에 오류같은 값이면 그 값이 설정된다. 값이 다르면 실행 시에 실패한다네임스페이스·사용자·몰드 모델·인덱스
다른 액션으로의 전개
AcquireActionsToFormProperties AcquireActionsToPropertyFormProperties
전달하는 획득 액션이 같으면 통합된다. 다르면 각각 실행된다폼 자체는 건드리지 않는다네임스페이스·사용자·몰드 모델·인덱스·전달하는 획득 액션

용량은 1 이상이어야 하고 몰드 모델의 최대 용량을 넘을 수 없습니다. 통합 후의 합계에 대해 판정되므로, 단독으로는 들어가는 가산이라도 다른 가산과 합쳐지면 거부될 수 있습니다.

몰드와 폼은 다른 대상이므로, 용량의 업데이트와 폼의 설정을 같은 트랜잭션에 넣는 것은 문제없습니다.

AcquireActionsTo...Properties는 폼 자체를 다시 쓰지 않고, 전달받은 획득 액션을 자신의 트랜잭션으로 발행합니다. 같은 폼에 대해 다른 획득 액션을 두 개 지정한 경우에는 양쪽 다 실행됩니다. 다만 발행되는 것은 같은 트랜잭션에 모이므로, 그것들이 속한 서비스의 제한을 확인해 주십시오.

중첩된 트랜잭션에 주의

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

용량의 설정과 폼의 설정은 다릅니다. 같은 몰드나 폼에 대해 한쪽이 안쪽에서 도착하고 다른 한쪽이 바깥쪽에 지정되어 있는 경우에는 트랜잭션이 실패합니다.

제한을 회피하고 싶은 경우

용량의 가산과 설정, 폼의 설정은 획득 액션, 용량의 감산은 소비 액션입니다. 획득 액션끼리의 충돌은 acquireActionUseJobQueue를 활성화하면 해소되지만, 용량의 설정과 감산의 공존은 enableAtomicCommit을 비활성화하지 않으면 해소되지 않습니다.

동시 실행과 재시도

용량의 가산·감산은 결과가 범위에 들어가는 한, 동시 실행 요청이 몇 개 겹쳐도 충돌하지 않습니다.

용량의 설정, 폼의 설정, 관리 콘솔이나 서버 API에서의 변경은 리비전 대조를 수반하는 기록이므로, 같은 대상에 대한 다른 업데이트와 겹치면 충돌(409)이 반환될 수 있습니다. 요청 내용에 문제가 있는 것은 아니므로, 재시도하면 성공합니다.


Consume Action

소비 액션

Gs2Formation:SubMoldCapacityByUserId

사용자 ID를 지정하여 용량 크기 감산

지정된 사용자의 폼 저장 영역(몰드)의 용량을 감산합니다. 용량은 0 미만으로 내려가지 않습니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
moldModelNamestring
~ 128자폼 저장 영역 모델의 이름
폼 저장 영역 모델 고유의 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
capacityint
0 ~ 2147483646현재 캐파시티
이 저장 영역에서 이 플레이어가 현재 이용할 수 있는 폼 저장 슬롯 수입니다. 초기값은 저장 영역 모델의 initialMaxCapacity로 설정되며, 캐파시티 증가 조작을 통해 maxCapacity까지 확장할 수 있습니다.
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Formation:SubMoldCapacityByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "moldModelName": "[string]폼 저장 영역 모델의 이름",
        "capacity": "[int]현재 캐파시티",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Formation:SubMoldCapacityByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  moldModelName: "[string]폼 저장 영역 모델의 이름"
  capacity: "[int]현재 캐파시티"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("formation").consume.sub_mold_capacity_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    moldModelName="[string]폼 저장 영역 모델의 이름",
    capacity="[int]현재 캐파시티",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Acquire Action

입수 액션

Gs2Formation:AddMoldCapacityByUserId

사용자 ID를 지정하여 용량 크기 가산

지정된 사용자의 폼 저장 영역(몰드)의 용량을 가산합니다.
용량은 몰드 모델에 정의된 maxCapacity를 초과할 수 없습니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
moldModelNamestring
~ 128자폼 저장 영역 모델의 이름
폼 저장 영역 모델 고유의 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
capacityint
0 ~ 2147483646현재 캐파시티
이 저장 영역에서 이 플레이어가 현재 이용할 수 있는 폼 저장 슬롯 수입니다. 초기값은 저장 영역 모델의 initialMaxCapacity로 설정되며, 캐파시티 증가 조작을 통해 maxCapacity까지 확장할 수 있습니다.
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Formation:AddMoldCapacityByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "moldModelName": "[string]폼 저장 영역 모델의 이름",
        "capacity": "[int]현재 캐파시티",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Formation:AddMoldCapacityByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  moldModelName: "[string]폼 저장 영역 모델의 이름"
  capacity: "[int]현재 캐파시티"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("formation").acquire.add_mold_capacity_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    moldModelName="[string]폼 저장 영역 모델의 이름",
    capacity="[int]현재 캐파시티",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Formation:SetMoldCapacityByUserId

사용자 ID를 지정하여 용량 크기 설정

지정된 사용자의 폼 저장 영역(몰드)의 용량을 지정한 값으로 직접 설정합니다.
갱신 전의 몰드를 ‘old’로, 갱신 후의 몰드와 함께 반환합니다.
용량은 몰드 모델에 정의된 maxCapacity로 상한이 제한됩니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
moldModelNamestring
~ 128자폼 저장 영역 모델의 이름
폼 저장 영역 모델 고유의 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
capacityint
0 ~ 2147483646현재 캐파시티
이 저장 영역에서 이 플레이어가 현재 이용할 수 있는 폼 저장 슬롯 수입니다. 초기값은 저장 영역 모델의 initialMaxCapacity로 설정되며, 캐파시티 증가 조작을 통해 maxCapacity까지 확장할 수 있습니다.
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Formation:SetMoldCapacityByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "moldModelName": "[string]폼 저장 영역 모델의 이름",
        "capacity": "[int]현재 캐파시티",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Formation:SetMoldCapacityByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  moldModelName: "[string]폼 저장 영역 모델의 이름"
  capacity: "[int]현재 캐파시티"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("formation").acquire.set_mold_capacity_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    moldModelName="[string]폼 저장 영역 모델의 이름",
    capacity="[int]현재 캐파시티",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Formation:AcquireActionsToFormProperties

사용자 ID를 지정하여 폼의 프로퍼티에 획득 액션을 적용

폼의 슬롯 프로퍼티에 획득 액션을 적용하고, 실행할 트랜잭션을 시작합니다.
폼의 슬롯에 아이템이나 리소스를 부여하기 위해 사용되며, 커스터마이즈용 선택적 설정 파라미터를 이용할 수 있습니다.
트랜잭션을 반환합니다.

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

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
moldModelNamestring
~ 128자폼 저장 영역 모델 이름
indexint
0 ~ 2147483646폼의 인덱스
저장 영역 내에서 이 폼이 차지하는 저장 슬롯을 식별하는 0부터 시작하는 인덱스입니다. 최대 인덱스는 저장 영역의 현재 캐파시티에 의해 제한됩니다. 예를 들어 인덱스 0을 「파티 1」, 인덱스 1을 「파티 2」와 같은 식으로 사용할 수 있습니다.
acquireActionAcquireAction
폼의 프로퍼티에 적용할 획득 액션
configList<Config>[]0 ~ 1000 items획득 액션에 적용하는 설정
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Formation:AcquireActionsToFormProperties",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "moldModelName": "[string]폼 저장 영역 모델 이름",
        "index": "[int]폼의 인덱스",
        "acquireAction": {
            "action": "[string]입수 액션에서 실행할 액션의 종류",
            "request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
        },
        "config": [
            {
                "key": "[string]이름",
                "value": "[string]값"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Formation:AcquireActionsToFormProperties
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  moldModelName: "[string]폼 저장 영역 모델 이름"
  index: "[int]폼의 인덱스"
  acquireAction: 
    action: "[string]입수 액션에서 실행할 액션의 종류"
    request: "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
  config: 
    - key: "[string]이름"
      value: "[string]값"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("formation").acquire.acquire_actions_to_form_properties({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    moldModelName="[string]폼 저장 영역 모델 이름",
    index="[int]폼의 인덱스",
    acquireAction={
        action="[string]입수 액션에서 실행할 액션의 종류",
        request="[string]액션 실행 시 사용되는 요청의 JSON 문자열"
    },
    config={
        {
            key="[string]이름",
            value="[string]값"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Formation:SetFormByUserId

사용자 ID를 지정하여 폼 설정

지정된 사용자의 폼의 슬롯 값을 업데이트합니다.

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

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
moldModelNamestring
~ 128자폼 저장 영역 모델 이름
indexint
0 ~ 2147483646폼의 인덱스
저장 영역 내에서 이 폼이 차지하는 저장 슬롯을 식별하는 0부터 시작하는 인덱스입니다. 최대 인덱스는 저장 영역의 현재 캐파시티에 의해 제한됩니다. 예를 들어 인덱스 0을 「파티 1」, 인덱스 1을 「파티 2」와 같은 식으로 사용할 수 있습니다.
slotsList<Slot>
1 ~ 10 items슬롯 목록
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Formation:SetFormByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "moldModelName": "[string]폼 저장 영역 모델 이름",
        "index": "[int]폼의 인덱스",
        "slots": [
            {
                "name": "[string]슬롯 모델명",
                "propertyId": "[string]프로퍼티 ID",
                "metadata": "[string]메타데이터"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Formation:SetFormByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  moldModelName: "[string]폼 저장 영역 모델 이름"
  index: "[int]폼의 인덱스"
  slots: 
    - name: "[string]슬롯 모델명"
      propertyId: "[string]프로퍼티 ID"
      metadata: "[string]메타데이터"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("formation").acquire.set_form_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    moldModelName="[string]폼 저장 영역 모델 이름",
    index="[int]폼의 인덱스",
    slots={
        {
            name="[string]슬롯 모델명",
            propertyId="[string]프로퍼티 ID",
            metadata="[string]메타데이터"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Formation:AcquireActionsToPropertyFormProperties

프로퍼티 폼의 프로퍼티에 획득 액션을 적용

프로퍼티 폼의 프로퍼티에 획득 액션을 적용하고 트랜잭션을 시작합니다.
프로퍼티 폼의 슬롯 값으로 설정되는 아이템이나 리소스를 부여하기 위해 사용됩니다.
획득 액션은 트랜잭션으로 실행되며, 그 결과 아이템이 폼의 슬롯 프로퍼티에 적용됩니다.
획득 액션의 동작을 커스터마이즈하기 위한 설정값을 전달할 수 있습니다.

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

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
propertyFormModelNamestring
~ 128자프로퍼티 폼 모델 이름
propertyIdstring
~ 1024자프로퍼티 ID
이 프로퍼티 폼 인스턴스를 고유하게 식별하는 개발자 정의 식별자입니다. 일반적으로 이 폼이 설정하는 소유 리소스(예: GS2-Inventory의 아이템 세트)의 GRN을 설정합니다. 특정 장비에 스킬을 설정하는 등의 용도로 사용됩니다.
acquireActionAcquireAction
프로퍼티 폼의 프로퍼티에 적용할 획득 액션
configList<Config>[]0 ~ 1000 items획득 액션에 적용하는 설정
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Formation:AcquireActionsToPropertyFormProperties",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "propertyFormModelName": "[string]프로퍼티 폼 모델 이름",
        "propertyId": "[string]프로퍼티 ID",
        "acquireAction": {
            "action": "[string]입수 액션에서 실행할 액션의 종류",
            "request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
        },
        "config": [
            {
                "key": "[string]이름",
                "value": "[string]값"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Formation:AcquireActionsToPropertyFormProperties
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  propertyFormModelName: "[string]프로퍼티 폼 모델 이름"
  propertyId: "[string]프로퍼티 ID"
  acquireAction: 
    action: "[string]입수 액션에서 실행할 액션의 종류"
    request: "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
  config: 
    - key: "[string]이름"
      value: "[string]값"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("formation").acquire.acquire_actions_to_property_form_properties({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    propertyFormModelName="[string]프로퍼티 폼 모델 이름",
    propertyId="[string]프로퍼티 ID",
    acquireAction={
        action="[string]입수 액션에서 실행할 액션의 종류",
        request="[string]액션 실행 시 사용되는 요청의 JSON 문자열"
    },
    config={
        {
            key="[string]이름",
            value="[string]값"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})