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

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

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

GS2-Quest がトランザクションに指定できるアクションは 2 つで、どちらもネームスペースとユーザーの組で決まる 1 人のユーザーの進行を対象にします。進行は 1 ユーザーにつき 1 つだけ存在し、これがプレイヤーを同時に 1 つのクエストに限る仕組みになっています。

作成と破棄は行が違い、境界が同じです。進行の有無にかかわらず、1 つのトランザクションに入れることはできません。発行時にエラーになります。

進行の作成は、すでに別の進行があると失敗します。この判定はトランザクション開始時点の状態に対して行われるため、enableAtomicCommit が有効な場合は、衝突の問題を別にしても、進行を破棄してから新しいクエストを開始するという流れを 1 つのトランザクションで行うことはできません。トランザクションを分けてください。

進行は 1 ユーザーにつき 1 つしかないため、同じユーザーへの作成を 1 つのトランザクションに 2 つ並べること自体が矛盾した指示です。どちらを実行すべきか決める根拠がないので、questModelId も force も設定もまったく同じであっても、発行時にエラーになります。「まとめ買いで 3 個買ってクエストを 3 回開始する」という指示は表現できないと考えてください。破棄どうしも同じで、何件並べても発行時にエラーになります。

クエストの報酬は別に発行されます

クエストの完了や失敗はトランザクションアクションではありません。クエストが終了すると、GS2-Quest がその報酬を自身のトランザクションとして発行します。そのため報酬が属するサービスの制限がそのまま当てはまり、下記も当てはまります。

このトランザクションには進行の破棄が必ず含まれます。そのため enableAtomicCommit が有効な場合、報酬に同じネームスペースの CreateProgressByUserId を置いて次のクエストを自動的に開始することはできません。作成が 1 つだけであっても、破棄との同居になるため発行時にエラーになります。クエストを連鎖させたい場合はトランザクションを分けてください。

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

内側から作成された進行と、外側から破棄された進行が衝突して、トランザクションが失敗します。作成どうしも同じ進行を二重に書き込むので失敗します。進行の作成は毎回ちがう識別子と乱数の種を書き込むため、指定がまったく同じでも書き込む値は一致せず、値が一致したときの統合には当たりません。破棄どうしだけは同じ進行の削除が冪等なので、入れ子越しでも 1 回にまとまり、失敗しません。

制限を回避したい場合

進行の作成は入手アクション、破棄は消費アクションです。作成どうし・破棄どうしの重複は、検査がトランザクションの発行時、設定が適用されるより前に走るため、acquireActionUseJobQueue を有効にしても enableAtomicCommit を無効にしても解消しません。指定を 1 つに減らすか、トランザクションを分けてください。

作成と破棄の同居は、enableAtomicCommit を無効にすれば解消します。このとき消費アクションが入手アクションより先に実行されるため、破棄してから新しいクエストを開始するという流れも成立するようになります。acquireActionUseJobQueue は入手アクションどうしを分離する設定なので、同居の解消には当てにしないでください。入手アクションが 1 つだけのときはジョブキューに積まれず、破棄と同じトランザクションに残ります。

同時実行とリトライ

同じユーザーの進行を複数のリクエストが同時に作成・破棄した場合、後から確定した側がコンフリクト (409) になります。リトライすると最新の状態で判定し直されるので、進行が期待した状態であれば成功し、すでに別のクエストが始まっていればエラーが返ります。

Consume Action

消費アクション

Gs2Quest:DeleteProgressByUserId

ユーザーIDを指定してクエスト進行状況を削除

指定したユーザーの現在のクエスト進行状況を削除します。進行中のクエストをキャンセルし、新しいクエストを開始できるようにします。

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

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

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Quest:DeleteProgressByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Quest:DeleteProgressByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("quest").consume.delete_progress_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    timeOffsetToken="[string]タイムオフセットトークン",
})

Acquire Action

入手アクション

Gs2Quest:CreateProgressByUserId

ユーザーIDを指定してクエストの進行状況を作成

クエストモデルを参照し、クエストコンテンツの抽選を行ってクエストを開始します。すでに進行中のクエストがある場合、force フラグが設定されていなければエラーを返します。

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

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

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Quest:CreateProgressByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "questModelId": "[string]開始するクエストモデルGRN",
        "force": "[bool]すでに開始しているクエストがある場合にそれを破棄して開始するか",
        "config": [
            {
                "key": "[string]名前",
                "value": "[string]値"
            }
        ],
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Quest:CreateProgressByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  questModelId: "[string]開始するクエストモデルGRN"
  force: "[bool]すでに開始しているクエストがある場合にそれを破棄して開始するか"
  config: 
    - key: "[string]名前"
      value: "[string]値"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("quest").acquire.create_progress_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    questModelId="[string]開始するクエストモデルGRN",
    force="[bool]すでに開始しているクエストがある場合にそれを破棄して開始するか",
    config={
        {
            key="[string]名前",
            value="[string]値"
        }
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})