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

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

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

GS2-Inbox のトランザクションアクションは、ネームスペース・ユーザー・メッセージの組で決まる 1 通のメッセージを対象にします。送信は常に新しいメッセージを作るので、送信ごとに別の対象になります。

開封と削除は行が違い、境界が同じです。1 通のメッセージを同じトランザクションで開封して削除することはできません。メッセージが違えば別の対象なので、複数のメッセージを開封したり削除したりするのは問題ありません。

トランザクションで送信したメッセージは、そのトランザクションの他のアクションからはまだ存在していないものとして扱われます。すべてのアクションがトランザクション開始時点の状態を基準に動くためです。メッセージを送ってから操作したい場合は、トランザクションを分けてください。

メッセージの開封は、添付されたものを配ります。それらは自身のトランザクションとして発行されるため、配られるものが属するサービスの制限がそのまま当てはまり、下記も当てはまります。同じアイテムを添付した 2 通を開封する場合が注意すべきケースです。

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

内側から開封されたメッセージと、外側から削除された同じメッセージが衝突して、トランザクションが失敗します。開封が配るものは他のアクションと同じトランザクションに集まるので、それらが属するサービスのページを確認してください。

制限を回避したい場合

メッセージの送信は入手アクション、開封と削除はどちらも消費アクションです。そのため acquireActionUseJobQueue では開封と削除を分離できず、解消するには enableAtomicCommit を無効にする必要があります。

同時実行とリトライ

送信は、リクエストが何本重なってもコンフリクトしません。送信するたびに自分のメッセージを作るためです。

開封と削除はメッセージ全体に対して書き込むため、同じメッセージへの同時更新があると後から確定した側がコンフリクト (409) になります。リクエストの内容に問題があるわけではないので、リトライすれば成功します。すでに開封済み・削除済みの場合は、リトライするとその旨のエラーが返ります。

Consume Action

消費アクション

Gs2Inbox:OpenMessageByUserId

ユーザーIDを指定してメッセージを開封済み化

指定されたユーザーの受信箱にある指定されたメッセージを既読（開封済み）としてマークします。
これは入手アクションを実行せずに isRead を true に設定する単純な状態遷移です。
既読にすると同時に関連する報酬を実行するには、代わりに Read API を使用してください。

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

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

• Format:
• JSON
• YAML
• GS2-Script

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

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

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

Gs2Inbox:DeleteMessageByUserId

ユーザーIDを指定してメッセージを削除

指定されたユーザーの受信箱からメッセージを完全に削除します。
既読状態に関係なくメッセージレコードが削除されます。

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

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

• Format:
• JSON
• YAML
• GS2-Script

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

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

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

Acquire Action

入手アクション

Gs2Inbox:SendMessageByUserId

ユーザーIDを指定してメッセージの送信

指定されたユーザーの受信箱に新しいメッセージを作成して配信します。
メッセージにはメタデータ（任意の JSON コンテンツ）と readAcquireActions（メッセージの開封時に付与される報酬）を含めることができます。
メッセージの有効期限は、絶対タイムスタンプ（expiresAt）または配信時点からの相対的な期間（expiresTimeSpan）で設定できます。expiresAt が指定された場合、expiresTimeSpan より優先されます。
メッセージは未読状態（isRead=false）で開始されます。

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

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

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Inbox:SendMessageByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "metadata": "[string]メタデータ",
        "readAcquireActions": [
            {
                "action": "[string]入手アクションで実行するアクションの種類",
                "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
            }
        ],
        "expiresAt": "[long]有効期限日時",
        "expiresTimeSpan": {
            "days": "[int]日数",
            "hours": "[int]時間",
            "minutes": "[int]分"
        },
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}

action: Gs2Inbox:SendMessageByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  metadata: "[string]メタデータ"
  readAcquireActions: 
    - action: "[string]入手アクションで実行するアクションの種類"
      request: "[string]アクション実行時に使用されるリクエストのJSON文字列"
  expiresAt: "[long]有効期限日時"
  expiresTimeSpan: 
    days: "[int]日数"
    hours: "[int]時間"
    minutes: "[int]分"
  timeOffsetToken: "[string]タイムオフセットトークン"

transaction.service("inbox").acquire.send_message_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    metadata="[string]メタデータ",
    readAcquireActions={
        {
            action="[string]入手アクションで実行するアクションの種類",
            request="[string]アクション実行時に使用されるリクエストのJSON文字列"
        }
    },
    expiresAt="[long]有効期限日時",
    expiresTimeSpan={
        days="[int]日数",
        hours="[int]時間",
        minutes="[int]分"
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})