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

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

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

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

GS2-Distributor のトランザクションアクションは、データではなくロジックを扱います。他のアクションを内側に持ち、それらを実行するかどうかを決めます。GS2-Distributor は自身のデータを持たないため、これらのアクションが GS2-Distributor を理由に衝突することはありません。

操作	同じ行を重ねたとき	入れ子越し	別の対象になる境界
`and` 式の評価 `AndExpressionByUserId`	それぞれ独立に評価される	読み取りだけなので衝突しない	式のたびに別の対象
`or` 式の評価 `OrExpressionByUserId`	それぞれ独立に評価される	読み取りだけなので衝突しない	式のたびに別の対象
`if` 式の評価 `IfExpressionByUserId`	それぞれ独立に評価される	成立した分岐が何を書き込むかによる	式のたびに別の対象

and と or の式が内側に持つのは検証アクションで、読み取りしか行いません。if の式は 2 つの分岐に消費アクションを持ち、こちらは書き込みます。

1 つの式の内側にあるアクションどうしは、通常どおり統合されます。1 つの and 式の中に同じ対象への同じアクションが 2 つあれば 1 つになります。ただし、外側のトランザクションのアクションとも、別の式の内側のアクションとも統合されることはありません。

注意すべきなのはここです。if の分岐がトランザクションに直接書かれたアクションと同じ通貨を消費したり、同じ図鑑を書き換えたりする場合、2 つの書き込みが別々に届くため、そのサービスに書かれている制限にそのまま当たります。

すべてトランザクション開始時点の状態に対して評価されます

式は、他の検証アクションと同じく、トランザクション開始時点の状態を読みます。同じトランザクションが変えたものは見えません。同じトランザクションの別の式が変えたものも同様です。そのため、条件が互いに依存する 2 つの if 式を連鎖させることはできません。どちらも同じ開始時点の状態に対して評価されます。

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

内側のトランザクションから届く書き込みは、外側に直接指定したアクションの対象外です。そのため、分岐が配るアイテムを外側のトランザクションも配る場合、そのアイテムが 2 つの書き込みを許さないならトランザクションが失敗します。

式の分岐もトランザクションの一部として読んでください。

制限を回避したい場合

enableAtomicCommit を無効にすると、分岐と外側のアクションが 1 回の書き込みに集まらなくなります。acquireActionUseJobQueue で分離できるのは式の周りにある入手アクションだけです。if の分岐が持つのは消費アクションなので、分岐そのものが分離されるわけではありません。

同時実行とリトライ

GS2-Distributor 自身がコンフリクトを返すことはありません。式が同時実行のリクエストと衝突するかどうかは、内側のアクションが何を書き込むかによって決まり、リトライの指針もそのサービスのものが当てはまります。

式は単に条件が満たされなかったために失敗することもあります。これは結果であって、リトライすべきエラーではありません。

Verify Action

検証アクション

Gs2Distributor:IfExpressionByUserId

条件を検証し、消費アクションの内容を切り替える

検証アクションを条件として評価し、結果に基づいて trueActions または falseActions の消費アクションリストを実行します。
これによりトランザクション内で条件分岐が可能になり、検証結果に応じて異なる消費アクションを実行できます。
multiplyValueSpecifyingQuantity が有効な場合、検証に使用される値も指定された数量で乗算されます。

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

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userId	string	✓		~ 128文字	ユーザーID `#{userId}` と設定することでログイン中のユーザーIDに置換されます。
condition	VerifyAction	✓			条件
trueActions	List<ConsumeAction>			0 ~ 10 items	条件が真のときに実行される消費アクションリスト
falseActions	List<ConsumeAction>			0 ~ 10 items	条件が偽のときに実行される消費アクションリスト
multiplyValueSpecifyingQuantity	bool		true		数量指定した際に、検証に使用する値も乗算するか
timeOffsetToken	string			~ 1024文字	タイムオフセットトークン

{
    "action": "Gs2Distributor:IfExpressionByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "condition": {
            "action": "[string]検証アクションで実行するアクションの種類",
            "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
        },
        "trueActions": [
            {
                "action": "[string]消費アクションで実行するアクションの種類",
                "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
            }
        ],
        "falseActions": [
            {
                "action": "[string]消費アクションで実行するアクションの種類",
                "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
            }
        ],
        "multiplyValueSpecifyingQuantity": "[bool]数量指定した際に、検証に使用する値も乗算するか",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Distributor:IfExpressionByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  condition: 
    action: "[string]検証アクションで実行するアクションの種類"
    request: "[string]アクション実行時に使用されるリクエストのJSON文字列"
  trueActions: 
    - action: "[string]消費アクションで実行するアクションの種類"
      request: "[string]アクション実行時に使用されるリクエストのJSON文字列"
  falseActions: 
    - action: "[string]消費アクションで実行するアクションの種類"
      request: "[string]アクション実行時に使用されるリクエストのJSON文字列"
  multiplyValueSpecifyingQuantity: "[bool]数量指定した際に、検証に使用する値も乗算するか"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("distributor").verify.if_expression_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    condition={
        action="[string]検証アクションで実行するアクションの種類",
        request="[string]アクション実行時に使用されるリクエストのJSON文字列"
    },
    trueActions={
        {
            action="[string]消費アクションで実行するアクションの種類",
            request="[string]アクション実行時に使用されるリクエストのJSON文字列"
        }
    },
    falseActions={
        {
            action="[string]消費アクションで実行するアクションの種類",
            request="[string]アクション実行時に使用されるリクエストのJSON文字列"
        }
    },
    multiplyValueSpecifyingQuantity="[bool]数量指定した際に、検証に使用する値も乗算するか",
    timeOffsetToken="[string]タイムオフセットトークン",
})

Gs2Distributor:AndExpressionByUserId

複数の検証アクションを実行し、全てが真かどうかを判定する

複数の検証アクションを実行し、すべてが真と評価された場合にのみ成功します（AND論理）。
いずれかの検証アクションが失敗すると、式全体が失敗します。
トランザクションの実行前にすべて満たす必要がある複数の前提条件を組み合わせる場合に便利です。

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

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userId	string	✓	~ 128文字	ユーザーID `#{userId}` と設定することでログイン中のユーザーIDに置換されます。
actions	List<VerifyAction>		0 ~ 10 items	検証アクションリスト
timeOffsetToken	string		~ 1024文字	タイムオフセットトークン

{
    "action": "Gs2Distributor:AndExpressionByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "actions": [
            {
                "action": "[string]検証アクションで実行するアクションの種類",
                "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
            }
        ],
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Distributor:AndExpressionByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  actions: 
    - action: "[string]検証アクションで実行するアクションの種類"
      request: "[string]アクション実行時に使用されるリクエストのJSON文字列"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("distributor").verify.and_expression_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    actions={
        {
            action="[string]検証アクションで実行するアクションの種類",
            request="[string]アクション実行時に使用されるリクエストのJSON文字列"
        }
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})

Gs2Distributor:OrExpressionByUserId

複数の検証アクションを実行し、いずれかが真かどうかを判定する

複数の検証アクションを実行し、少なくとも1つが真と評価された場合に成功します（OR論理）。
すべての検証アクションが失敗した場合にのみ式が失敗します。
いずれか1つを満たせば十分な代替条件を定義する場合に便利です。

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

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
userId	string	✓	~ 128文字	ユーザーID `#{userId}` と設定することでログイン中のユーザーIDに置換されます。
actions	List<VerifyAction>		0 ~ 10 items	検証アクションリスト
timeOffsetToken	string		~ 1024文字	タイムオフセットトークン

{
    "action": "Gs2Distributor:OrExpressionByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "actions": [
            {
                "action": "[string]検証アクションで実行するアクションの種類",
                "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
            }
        ],
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Distributor:OrExpressionByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  actions: 
    - action: "[string]検証アクションで実行するアクションの種類"
      request: "[string]アクション実行時に使用されるリクエストのJSON文字列"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("distributor").verify.or_expression_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    actions={
        {
            action="[string]検証アクションで実行するアクションの種類",
            request="[string]アクション実行時に使用されるリクエストのJSON文字列"
        }
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})