GS2-Guild トランザクションアクション
アクションの組み合わせと同時実行
すべてのサービスに共通する前提は トランザクションアクションの組み合わせ にまとめています。先にそちらを読んでください。この節の残りは GS2-Guild 固有の内容です。
GS2-Guild のトランザクションアクションは、ネームスペース・ギルドモデル・ギルド名の組で決まる 1 つのギルドを対象にします。対象がユーザーではなくギルドである点に注意してください。あるユーザーに対して発行したトランザクションが、多数のユーザーで共有しているものを更新することになります。ギルドは更新のたびに全体が書き換わります。
| 操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界 |
|---|---|---|---|
最大メンバー数の加算IncreaseMaximumCurrentMaximumMemberCountByGuildName | 統合され、値が合算される | 失敗する | ネームスペース・ギルドモデル・ギルド名 |
最大メンバー数の減算DecreaseMaximumCurrentMaximumMemberCountByGuildName | 統合され、値が合算される | 失敗する | ネームスペース・ギルドモデル・ギルド名 |
最大メンバー数の設定SetMaximumCurrentMaximumMemberCountByGuildName | 同値なら統合。値が違えば発行時にエラー | 失敗する | ネームスペース・ギルドモデル・ギルド名 |
最大メンバー数の検証VerifyCurrentMaximumMemberCountByGuildName | 先勝ち | 読み取りだけなので衝突しない | ギルド・検証タイプ・人数 |
メンバーであることの検証VerifyIncludeMemberByUserId | 先勝ち | 読み取りだけなので衝突しない | ギルド・検証タイプ・対象ユーザー |
更新する 3 つの行は境界が同じです。1 つのギルドに対して加算・減算・設定を混ぜることはできません。
最大メンバー数はギルドモデルで許された範囲に収まる必要があり、統合後の合計に対して判定されるので、単独なら収まる加算でも他の加算と合わさると弾かれることがあります。
検証アクションはトランザクション開始時点のギルドを見ます。同じトランザクションで到達するメンバー数や、同じトランザクションで成立する加入を検証することはできません。
入れ子になったトランザクションに注意
並べて書けば 1 件に統合されたはずの同じギルドへの加算どうしでも、片方が内側から届く場合はトランザクションが失敗します。
ギルドは多数のユーザーで共有されますが、これは「同じギルドに所属する 2 人が同時に何かをした」ときではなく、「1 つのトランザクションが報酬や抽選を通じて同じギルドに二度触れた」ときに起こります。報酬や抽選の中身まで含めて、1 つのトランザクションの中で 1 つのギルドを更新する箇所が 1 つだけになるように設計してください。
制限を回避したい場合
最大メンバー数の加算と設定は入手アクション、減算は消費アクションです。入手アクションどうしの衝突は acquireActionUseJobQueue を有効にすれば解消できますが、減算との同居は enableAtomicCommit を無効にしないと解消しません。
同時実行とリトライ
ギルドはリビジョンの照合を伴って全体が書き換わるため、加算どうしであっても、GS2-Experience の経験値のように「一定範囲なら衝突しない」という緩和はありません。しかもギルドはメンバーで共有されるものなので、1 人のユーザーが所有するものに比べて更新が重なりやすくなります。加入・脱退、ギルドの変更、メンバーのメタデータ更新はいずれも同じギルドを触るため、これらと最大メンバー数の変更が重なるとコンフリクト (409) が返ることがあります。リクエストの内容に問題があるわけではないので、リトライすれば成功します。
メンバーの出入りが激しい時間帯に最大メンバー数を引き上げるトランザクションを実行する場合は、リトライを前提にしてください。
Verify Action
検証アクション
Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName
ギルド名を指定して最大参加可能人数を検証
選択された比較演算子を使用して、指定されたギルドの currentMaximumMemberCount を指定された値と比較検証します（サーバーサイド操作）。
サポートされる演算子：less、lessEqual、greater、greaterEqual、equal、notEqual。
数量指定可能なアクション：いいえ
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||||||||||
| guildModelName | string | ✓ | ~ 128文字 | ギルドモデル名 ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||||||||||
| guildName | string | ✓ | ~ 128文字 | ギルド名 | ||||||||||||||||
| verifyType | 文字列列挙型 enum { “less”, “lessEqual”, “greater”, “greaterEqual”, “equal”, “notEqual” } | ✓ | 検証の種類
| |||||||||||||||||
| value | int | 1 ~ 2147483646 | 最大参加可能人数 | |||||||||||||||||
| multiplyValueSpecifyingQuantity | bool | false | 数量指定した際に、検証に使用する値も乗算するか |
{
"action": "Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName",
"request": {
"namespaceName": "[string]ネームスペース名",
"guildModelName": "[string]ギルドモデル名",
"guildName": "[string]ギルド名",
"verifyType": "[string]検証の種類",
"value": "[int]最大参加可能人数",
"multiplyValueSpecifyingQuantity": "[bool]数量指定した際に、検証に使用する値も乗算するか"
}
}action: Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName
request:
namespaceName: "[string]ネームスペース名"
guildModelName: "[string]ギルドモデル名"
guildName: "[string]ギルド名"
verifyType: "[string]検証の種類"
value: "[int]最大参加可能人数"
multiplyValueSpecifyingQuantity: "[bool]数量指定した際に、検証に使用する値も乗算するか"transaction.service("guild").verify.verify_current_maximum_member_count_by_guild_name({
namespaceName="[string]ネームスペース名",
guildModelName="[string]ギルドモデル名",
guildName="[string]ギルド名",
verifyType="[string]検証の種類",
value="[int]最大参加可能人数",
multiplyValueSpecifyingQuantity="[bool]数量指定した際に、検証に使用する値も乗算するか",
})Gs2Guild:VerifyIncludeMemberByUserId
ユーザーIDを指定してギルドメンバーにユーザーIDが含まれているかを検証
指定されたユーザーがギルドのメンバーであるかどうかを検証します（サーバーサイド操作）。
2つの検証タイプをサポートします：‘include’ と ’notInclude’。
数量指定可能なアクション：いいえ
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||
| guildModelName | string | ✓ | ~ 128文字 | ギルドモデル名 ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||
| guildName | string | ✓ | UUID | ~ 36文字 | ギルド名 ギルドの一意な名前を保持します。 名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ギルドを識別するために使用されます。 | |||||||
| userId | string | ✓ | ~ 128文字 | ユーザーID#{userId} と設定することでログイン中のユーザーIDに置換されます。 | ||||||||
| verifyType | 文字列列挙型 enum { “include”, “notInclude” } | ✓ | 検証の種類
| |||||||||
| timeOffsetToken | string | ~ 1024文字 | タイムオフセットトークン |
{
"action": "Gs2Guild:VerifyIncludeMemberByUserId",
"request": {
"namespaceName": "[string]ネームスペース名",
"guildModelName": "[string]ギルドモデル名",
"guildName": "[string]ギルド名",
"userId": "[string]ユーザーID",
"verifyType": "[string]検証の種類",
"timeOffsetToken": "[string]タイムオフセットトークン"
}
}action: Gs2Guild:VerifyIncludeMemberByUserId
request:
namespaceName: "[string]ネームスペース名"
guildModelName: "[string]ギルドモデル名"
guildName: "[string]ギルド名"
userId: "[string]ユーザーID"
verifyType: "[string]検証の種類"
timeOffsetToken: "[string]タイムオフセットトークン"transaction.service("guild").verify.verify_include_member_by_user_id({
namespaceName="[string]ネームスペース名",
guildModelName="[string]ギルドモデル名",
guildName="[string]ギルド名",
userId="[string]ユーザーID",
verifyType="[string]検証の種類",
timeOffsetToken="[string]タイムオフセットトークン",
})Consume Action
消費アクション
Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName
ギルド名を指定して最大参加可能人数を減算
指定されたギルドの currentMaximumMemberCount を指定された値だけ減少させます（サーバーサイド操作）。
結果の値はゼロ未満にはなりません。
数量指定可能なアクション：はい
反転可能なアクション：はい
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| guildModelName | string | ✓ | ~ 128文字 | ギルドモデル名 ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| guildName | string | ✓ | ~ 128文字 | ギルド名 | ||
| value | int | 1 ~ 2147483646 | 最大人数の減少量 |
{
"action": "Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName",
"request": {
"namespaceName": "[string]ネームスペース名",
"guildModelName": "[string]ギルドモデル名",
"guildName": "[string]ギルド名",
"value": "[int]最大人数の減少量"
}
}action: Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName
request:
namespaceName: "[string]ネームスペース名"
guildModelName: "[string]ギルドモデル名"
guildName: "[string]ギルド名"
value: "[int]最大人数の減少量"transaction.service("guild").consume.decrease_maximum_current_maximum_member_count_by_guild_name({
namespaceName="[string]ネームスペース名",
guildModelName="[string]ギルドモデル名",
guildName="[string]ギルド名",
value="[int]最大人数の減少量",
})Acquire Action
入手アクション
Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName
ギルド名を指定して最大参加可能人数を加算
ギルドの currentMaximumMemberCount を指定された値だけ増加させます。
結果の値はギルドモデルで定義された maximumMemberCount を超えてはなりません。
数量指定可能なアクション：はい
反転可能なアクション：はい
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| guildModelName | string | ✓ | ~ 128文字 | ギルドモデル名 ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| guildName | string | ✓ | ~ 128文字 | ギルド名 | ||
| value | int | 1 ~ 2147483646 | 最大人数の増加量 |
{
"action": "Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName",
"request": {
"namespaceName": "[string]ネームスペース名",
"guildModelName": "[string]ギルドモデル名",
"guildName": "[string]ギルド名",
"value": "[int]最大人数の増加量"
}
}action: Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName
request:
namespaceName: "[string]ネームスペース名"
guildModelName: "[string]ギルドモデル名"
guildName: "[string]ギルド名"
value: "[int]最大人数の増加量"transaction.service("guild").acquire.increase_maximum_current_maximum_member_count_by_guild_name({
namespaceName="[string]ネームスペース名",
guildModelName="[string]ギルドモデル名",
guildName="[string]ギルド名",
value="[int]最大人数の増加量",
})Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName
ギルド名を指定して最大参加可能人数を設定
ギルドの currentMaximumMemberCount を指定された絶対値に設定します。
増減操作とは異なり、差分を適用するのではなく値を直接設定します。
更新後のギルドと更新前のギルド状態の両方を返し、呼び出し元が変更を追跡できるようにします。
数量指定可能なアクション：いいえ
反転可能なアクション：いいえ
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| guildName | string | ✓ | ~ 128文字 | ギルド名 | ||
| guildModelName | string | ✓ | ~ 128文字 | ギルドモデル名 ギルドモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| value | int | 1 ~ 2147483646 | 設定する最大人数 |
{
"action": "Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName",
"request": {
"namespaceName": "[string]ネームスペース名",
"guildName": "[string]ギルド名",
"guildModelName": "[string]ギルドモデル名",
"value": "[int]設定する最大人数"
}
}action: Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName
request:
namespaceName: "[string]ネームスペース名"
guildName: "[string]ギルド名"
guildModelName: "[string]ギルドモデル名"
value: "[int]設定する最大人数"transaction.service("guild").acquire.set_maximum_current_maximum_member_count_by_guild_name({
namespaceName="[string]ネームスペース名",
guildName="[string]ギルド名",
guildModelName="[string]ギルドモデル名",
value="[int]設定する最大人数",
})