GS2-Formation トランザクションアクション

検証/消費/入手の各トランザクションアクションの仕様

アクションの組み合わせと同時実行

すべてのサービスに共通する前提は トランザクションアクションの組み合わせ にまとめています。先にそちらを読んでください。この節の残りは GS2-Formation 固有の内容です。

GS2-Formation のトランザクションアクションは 2 種類の対象を扱います。

  • モールド : ネームスペース・ユーザー・モールドモデルの組で決まります。フォームをいくつ持てるかという容量を保持します。
  • フォーム : ネームスペース・ユーザー・モールドモデル・インデックスの組で決まります。1 つの枠に設定されたプロパティを保持します。
操作 同じ行を重ねたとき 入れ子越し 別の対象になる境界 直列実行モード有効時
容量の加算・減算
AddMoldCapacityByUserId SubMoldCapacityByUserId
混在してよい。統合され、値が合算される 合算される ネームスペース・ユーザー・モールドモデル 変わらない。もともと合算されて成立する
容量の設定
SetMoldCapacityByUserId
同値なら統合。値が違えば発行時にエラー 同値ならその値が設定される。値が違うと実行時に失敗する ネームスペース・ユーザー・モールドモデル 値が違っても成立する。後から実行された方の値になる
フォームの設定
SetFormByUserId
同値なら統合。値が違えば発行時にエラー 同値ならその値が設定される。値が違うと実行時に失敗する ネームスペース・ユーザー・モールドモデル・インデックス 値が違っても成立する。後から実行された方の値になる
他のアクションへの展開
AcquireActionsToFormProperties AcquireActionsToPropertyFormProperties
渡す入手アクションが同じなら統合される。違えばそれぞれ実行される フォーム自体は触らない ネームスペース・ユーザー・モールドモデル・インデックス・渡す入手アクション 変わらない。フォーム自体は触らない

容量は 1 以上で、モールドモデルの最大容量を超えられません。統合後の合計に対して判定されるので、単独なら収まる加算でも他の加算と合わさると弾かれることがあります。

モールドとフォームは別の対象なので、容量の更新とフォームの設定を同じトランザクションに入れるのは問題ありません。

AcquireActionsTo...Properties はフォーム自体を書き換えず、渡された入手アクションを自身のトランザクションとして発行します。同じフォームに対して違う入手アクションを 2 つ指定した場合はどちらも実行されます。ただし発行されるものは同じトランザクションに集まるので、それらが属するサービスの制限を確認してください。

入れ子になったトランザクションに注意

容量は入れ子越しでも安全です。加算・減算はどちらの経路から届いても 1 回の更新にまとまります。

容量の設定とフォームの設定は違います。同じモールドやフォームに対して、片方が内側から届き、もう片方が外側に指定されている場合は、トランザクションが失敗します。直列実行モード(enableSequentialExecution または TransactionSettingV2)を有効にすると、この失敗は起こらなくなります。内側のトランザクションは外側と同じ直列実行の区間で実行されるようになるため、トランザクションが失敗する代わりに、実際に後から実行された方の値になります。

制限を回避したい場合

容量の加算と設定、フォームの設定は入手アクション、容量の減算は消費アクションです。入手アクションどうしの衝突は acquireActionUseJobQueue を有効にすれば解消できますが、容量の設定と減算の同居は enableAtomicCommit を無効にしないと解消しません。

同時実行とリトライ

容量の加算・減算は、結果が範囲に収まるかぎり、同時実行のリクエストが何本重なってもコンフリクトしません。

容量の設定、フォームの設定、管理コンソールやサーバー API からの変更は、リビジョンの照合を伴う書き込みなので、同じ対象への別の更新と重なるとコンフリクト (409) が返ることがあります。リクエストの内容に問題があるわけではないので、リトライすれば成功します。


Consume Action

消費アクション

Gs2Formation:SubMoldCapacityByUserId

ユーザーIDを指定してキャパシティサイズを減算

指定されたユーザーのフォームの保存領域(モールド)のキャパシティを減算します。キャパシティは0を下回りません。

数量指定可能なアクション:はい

反転可能なアクション:はい

型 有効化条件 必須 デフォルト 値の制限 説明
namespaceName string
✓
~ 128文字 ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userId string
✓
~ 128文字 ユーザーID
#{userId} と設定することでログイン中のユーザーIDに置換されます。
moldModelName string
✓
~ 128文字 フォームの保存領域モデルの名前
フォームの保存領域モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
capacity int
✓
0 ~ 2147483646 現在のキャパシティ
この保存領域でこのプレイヤーが現在利用できるフォーム保存スロット数です。初期値は保存領域モデルの initialMaxCapacity に設定され、キャパシティ増加操作により maxCapacity まで拡張できます。
timeOffsetToken string ~ 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 を超えることはできません。

数量指定可能なアクション:はい

反転可能なアクション:はい

型 有効化条件 必須 デフォルト 値の制限 説明
namespaceName string
✓
~ 128文字 ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userId string
✓
~ 128文字 ユーザーID
#{userId} と設定することでログイン中のユーザーIDに置換されます。
moldModelName string
✓
~ 128文字 フォームの保存領域モデルの名前
フォームの保存領域モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
capacity int
✓
0 ~ 2147483646 現在のキャパシティ
この保存領域でこのプレイヤーが現在利用できるフォーム保存スロット数です。初期値は保存領域モデルの initialMaxCapacity に設定され、キャパシティ増加操作により maxCapacity まで拡張できます。
timeOffsetToken string ~ 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 で上限が制限されます。

数量指定可能なアクション:はい

反転可能なアクション:いいえ

型 有効化条件 必須 デフォルト 値の制限 説明
namespaceName string
✓
~ 128文字 ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userId string
✓
~ 128文字 ユーザーID
#{userId} と設定することでログイン中のユーザーIDに置換されます。
moldModelName string
✓
~ 128文字 フォームの保存領域モデルの名前
フォームの保存領域モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
capacity int
✓
0 ~ 2147483646 現在のキャパシティ
この保存領域でこのプレイヤーが現在利用できるフォーム保存スロット数です。初期値は保存領域モデルの initialMaxCapacity に設定され、キャパシティ増加操作により maxCapacity まで拡張できます。
timeOffsetToken string ~ 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を指定してフォームのプロパティに入手アクションを適用

フォームのスロットプロパティに入手アクションを適用し、実行するトランザクションを開始します。
フォームのスロットにアイテムやリソースを付与するために使用され、カスタマイズ用のオプションのコンフィグパラメータが利用できます。
トランザクションを返します。

数量指定可能なアクション:いいえ

反転可能なアクション:いいえ

型 有効化条件 必須 デフォルト 値の制限 説明
namespaceName string
✓
~ 128文字 ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userId string
✓
~ 128文字 ユーザーID
#{userId} と設定することでログイン中のユーザーIDに置換されます。
moldModelName string
✓
~ 128文字 フォームの保存領域モデルの名前
index int
✓
0 ~ 2147483646 フォームのインデックス
保存領域内でこのフォームが占める保存スロットを識別するゼロベースのインデックスです。最大インデックスは保存領域の現在のキャパシティによって制限されます。例えば、インデックス 0 が「パーティ1」、インデックス 1 が「パーティ2」のように使用できます。
acquireAction AcquireAction
✓
フォームのプロパティに適用する入手アクション
config List<Config> [] 0 ~ 1000 items 入手アクションに適用するコンフィグ
timeOffsetToken string ~ 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を指定してフォームを設定

指定されたユーザーのフォームのスロット値を更新します。

数量指定可能なアクション:いいえ

反転可能なアクション:いいえ

型 有効化条件 必須 デフォルト 値の制限 説明
namespaceName string
✓
~ 128文字 ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userId string
✓
~ 128文字 ユーザーID
#{userId} と設定することでログイン中のユーザーIDに置換されます。
moldModelName string
✓
~ 128文字 フォームの保存領域モデルの名前
index int
✓
0 ~ 2147483646 フォームのインデックス
保存領域内でこのフォームが占める保存スロットを識別するゼロベースのインデックスです。最大インデックスは保存領域の現在のキャパシティによって制限されます。例えば、インデックス 0 が「パーティ1」、インデックス 1 が「パーティ2」のように使用できます。
slots List<Slot>
✓
1 ~ 10 items スロットリスト
timeOffsetToken string ~ 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

プロパティフォームのプロパティに入手アクションを適用

プロパティフォームのプロパティに入手アクションを適用し、トランザクションを開始します。
プロパティフォームのスロット値として設定されるアイテムやリソースを付与するために使用されます。
入手アクションはトランザクションとして実行され、結果のアイテムがフォームのスロットプロパティに適用されます。
入手アクションの動作をカスタマイズするためのコンフィグ値を渡すことができます。

数量指定可能なアクション:いいえ

反転可能なアクション:いいえ

型 有効化条件 必須 デフォルト 値の制限 説明
namespaceName string
✓
~ 128文字 ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userId string
✓
~ 128文字 ユーザーID
#{userId} と設定することでログイン中のユーザーIDに置換されます。
propertyFormModelName string
✓
~ 128文字 プロパティフォームモデル名
propertyId string
✓
~ 1024文字 プロパティID
このプロパティフォームインスタンスを一意に識別する開発者定義の識別子です。通常、このフォームが設定する所有リソース(例: GS2-Inventory のアイテムセット)の GRN を設定します。特定の装備にスキルを設定するような用途で使用されます。
acquireAction AcquireAction
✓
プロパティフォームのプロパティに適用する入手アクション
config List<Config> [] 0 ~ 1000 items 入手アクションに適用するコンフィグ
timeOffsetToken string ~ 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]タイムオフセットトークン",
})