GS2-Realtime Deploy/CDK リファレンス
エンティティ
Deploy処理で操作の対象となるリソース
Namespace
ネームスペース
ネームスペースは、一つのプロジェクト内で同じサービスを異なる用途で複数利用するためのエンティティです。
GS2 の各サービスはネームスペース単位で管理されます。ネームスペースが異なれば、同じサービスでも完全に独立したデータ空間として扱われます。
そのため、各サービスの利用を開始するにあたってネームスペースを作成する必要があります。
Request
リソースの生成・更新リクエスト
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||||
| description | string | ~ 1024文字 | 説明文 | |||||||||||
| transactionSettingV2 | TransactionSettingV2 | トランザクション設定(V2) このネームスペースが発行するトランザクションをどのように実行するかを決める設定です。設定する項目は、実行に使用する GS2-Distributor のネームスペースと、トランザクションに含まれるアクションを 1 件ずつ実行して先に実行されたアクションの結果を後続のアクションから使えるようにするか、まとめて同時に実行してレスポンスタイムを短くするか、の 2 つだけです。 新しく作成するネームスペースではこちらを設定してください。これに置き換えられて非推奨となった transactionSetting は、こちらが設定されていない間だけ使用されます。 | ||||||||||||
| serverType | 文字列列挙型 enum { “relay”, “sync”, “stateMachine” } | ✓ | サーバの種類 リアルタイム通信のためにプロビジョニングするゲームサーバーのタイプ。 relay は、接続されたゲームクライアント間でメッセージを転送します。sync は、それに加えて、オブジェクトのカタログに従って共有オブジェクトの状態と、誰が更新できるかを管理します。stateMachine は、それに加えて、GS2-StateMachine に登録したルームのルールをサーバーで実行し、共有オブジェクトを生成・更新します。
| |||||||||||
| serverSpec | 文字列列挙型 enum { “realtime1.nano” } | ✓ | サーバのスペック プロビジョニングされるゲームサーバーのハードウェアスペックティア。 各ルームのサーバーインスタンスに割り当てられるコンピューティングリソース(CPU、メモリ)を決定します。現在 “realtime1.nano” をサポートしています。
| |||||||||||
| syncSetting | SyncSetting | {serverType} in [“sync”, “stateMachine”] | オブジェクト同期の設定sync と stateMachine のルームの設定です。ルームにオブジェクトや RPC を検査させたい場合は、オブジェクトのカタログを設定します。※ serverType が “sync”,“stateMachine"であれば 有効 | |||||||||||
| stateMachineSetting | StateMachineSetting | {serverType} == “stateMachine” | ✓※ | サーバーサイドステートマシンの設定 ※ serverType が “stateMachine” であれば必須 | ||||||||||
| participantSetting | ParticipantSetting | {serverType} == “stateMachine” | 参加者の設定 ルームのルールが読む参加者ごとのデータを作る GS2-Script と、その実行に使う GS2-Identifier ユーザーです。 省略すると、ルームは参加者のデータを持たず、 Room.Participant はエラーになります。※ serverType が “stateMachine” であれば有効 | |||||||||||
| createNotification | NotificationSetting | ルームの作成が完了したときのプッシュ通知 ルームのプロビジョニングが完了し、接続可能になったときにトリガーされるプッシュ通知設定。 ルーム作成は非同期で行われ(IPアドレス、ポート、暗号鍵は少し遅れて割り当てられる)、この通知によりクライアントにルームが接続受付可能になったことを通知します。 | ||||||||||||
| logSetting | LogSetting | ログ出力設定 リアルタイム関連の操作ログを GS2-Log に出力するための設定。 設定すると、ルーム作成、接続イベント、メッセージリレーのアクティビティなどが分析やデバッグのために記録されます。 |
GetAttr
!GetAttrタグで取得可能なリソースの生成結果
| 型 | 説明 | |
|---|---|---|
| Item | Namespace | 作成したネームスペース |
実装例
Type: GS2::Realtime::Namespace
Properties:
Name: namespace-0001
Description: null
TransactionSettingV2: null
ServerType: relay
ServerSpec: realtime1.nano
SyncSetting: null
StateMachineSetting: null
ParticipantSetting: null
CreateNotification: null
LogSetting:
LoggingNamespaceId: grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001import (
"github.com/gs2io/gs2-golang-cdk/core"
"github.com/gs2io/gs2-golang-cdk/realtime"
)
SampleStack := core.NewStack()
realtime.NewNamespace(
&SampleStack,
"namespace-0001",
realtime.NamespaceServerTypeRelay,
realtime.NamespaceServerSpecRealtime1Nano,
realtime.NamespaceOptions{
LogSetting: &core.LogSetting{
LoggingNamespaceId: "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001",
},
},
)
println(SampleStack.Yaml()) // Generate Templateclass SampleStack extends \Gs2Cdk\Core\Model\Stack
{
function __construct() {
parent::__construct();
new \Gs2Cdk\Realtime\Model\Namespace_(
stack: $this,
name: "namespace-0001",
serverType: \Gs2Cdk\Realtime\Model\Enums\NamespaceServerType::RELAY,
serverSpec: \Gs2Cdk\Realtime\Model\Enums\NamespaceServerSpec::REALTIME1_NANO,
options: new \Gs2Cdk\Realtime\Model\Options\NamespaceOptions(
logSetting: new \Gs2Cdk\Core\Model\LogSetting(
loggingNamespaceId: "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
)
)
);
}
}
print((new SampleStack())->yaml()); // Generate Template
class SampleStack extends io.gs2.cdk.core.model.Stack
{
public SampleStack() {
super();
new io.gs2.cdk.realtime.model.Namespace(
this,
"namespace-0001",
io.gs2.cdk.realtime.model.enums.NamespaceServerType.RELAY,
io.gs2.cdk.realtime.model.enums.NamespaceServerSpec.REALTIME1_NANO,
new io.gs2.cdk.realtime.model.options.NamespaceOptions()
.withLogSetting(new io.gs2.cdk.core.model.LogSetting(
"grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
))
);
}
}
System.out.println(new SampleStack().yaml()); // Generate Templatepublic class SampleStack : Gs2Cdk.Core.Model.Stack
{
public SampleStack() {
new Gs2Cdk.Gs2Realtime.Model.Namespace(
stack: this,
name: "namespace-0001",
serverType: Gs2Cdk.Gs2Realtime.Model.Enums.NamespaceServerType.Relay,
serverSpec: Gs2Cdk.Gs2Realtime.Model.Enums.NamespaceServerSpec.Realtime1Nano,
options: new Gs2Cdk.Gs2Realtime.Model.Options.NamespaceOptions
{
logSetting = new Gs2Cdk.Core.Model.LogSetting(
loggingNamespaceId: "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
)
}
);
}
}
Debug.Log(new SampleStack().Yaml()); // Generate Templateimport core from "@/gs2cdk/core";
import realtime from "@/gs2cdk/realtime";
class SampleStack extends core.Stack
{
public constructor() {
super();
new realtime.model.Namespace(
this,
"namespace-0001",
realtime.model.NamespaceServerType.RELAY,
realtime.model.NamespaceServerSpec.REALTIME1_NANO,
{
logSetting: new core.LogSetting(
"grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
)
}
);
}
}
console.log(new SampleStack().yaml()); // Generate Template
from gs2_cdk import Stack, core, realtime
class SampleStack(Stack):
def __init__(self):
super().__init__()
realtime.Namespace(
stack=self,
name='namespace-0001',
server_type=realtime.NamespaceServerType.RELAY,
server_spec=realtime.NamespaceServerSpec.REALTIME1_NANO,
options=realtime.NamespaceOptions(
log_setting=core.LogSetting(
logging_namespace_id='grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001',
),
),
)
print(SampleStack().yaml()) # Generate TemplateTransactionSettingV2
トランザクション設定(V2)
トランザクション設定(V2)は、ネームスペースが発行するトランザクションをどのように実行するかを決める設定です。
設定する項目は次の 2 つだけです。
distributorNamespaceId: トランザクションの実行に使用する GS2-Distributor のネームスペースenableParallelExecution: トランザクションに含まれるアクションを 1 件ずつ実行するか、まとめて同時に実行するか
どちらを選んでも、トランザクションは発行された時点でサーバーが実行し、成否はトランザクション全体でひとつになります。あるアクションが失敗した場合は、それまでに実行されたアクションもろとも取り消され、1 つも反映されません。トランザクションの実行方法に関するそれ以外の項目は推奨構成に固定されているため、設定する必要はありません。
1 件ずつ実行する場合(既定 / enableParallelExecution が false)、各アクションは先に実行されたアクションの書き込みを踏まえて動作します。アクションは verify・consume・acquire の順に実行され、次のことができます。
- 1 つのトランザクションの中で、同じ行を複数のアクションから更新する(まとめて同時に実行する場合は失敗します)
- 先に実行されたアクションの書き込みを読む。List や Query の結果でも、入れ子になったトランザクションの内側でも読めます
%{Gs2Xxx:ActionName.path[0].field}を使って、先に実行された verify や consume アクションの結果を、後続の verify・consume・acquire アクションの引数として渡す
代わりに、レスポンスタイムは各アクションの実行時間の合計になり、1 つのトランザクションに含められるアクションは最大 20 件になります。また、各フェーズの中での実行順はアクション名、次に対象リソースの順で決まるため、リクエストに並べた順序で実行順を指定することはできません。実行は最初に失敗したアクションで停止します。
まとめて同時に実行する場合(enableParallelExecution が true)、アクションは同一のデータスナップショットに対して並列に実行されるため、レスポンスタイムは最も遅いアクション 1 件分で済み、アクション数の上限もありません。
代わりに、あるアクションから他のアクションの書き込みを読むことはできず、同じ行を 2 つのアクションが書き換えるとトランザクションは database:transaction:same.resource(400)で失敗します。同一トランザクション内で同じデータを 2 つ以上のアクションが書き換えないことを保証できる場合にだけ選択してください。%{...} は先行するフェーズ(verify → consume → acquire の順)の結果だけを参照でき、同じフェーズ内のアクションへの参照は解決されずにそのまま残ります。%{...} を含むフェーズは先行するフェーズの完了を待ってから実行されるため、その分だけレスポンスタイムが伸びます。
トランザクション設定は、トランザクション設定(V2)に置き換えられた非推奨の設定で、トランザクション設定(V2)が存在しなかった頃に作成されたネームスペースのために残されています。トランザクション設定(V2)が設定されていない間だけ適用され、トランザクション設定(V2)を設定するとそちらが優先されます。トランザクション設定で可能だった、トランザクションをクライアント実行のスタンプシートとして実行する・GS2-Distributor による AutoRun の非同期実行を行う・入手アクションを GS2-JobQueue に畳み込む、という 3 つの挙動は、こちらではあえて提供していません。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| distributorNamespaceId | string | “grn:gs2:{region}:{ownerId}:distributor:default” | ~ 1024文字 | トランザクションの実行に使用する GS2-Distributor ネームスペース GRN | ||
| enableParallelExecution | bool | false | アクションを直列ではなく並列に実行するか |
NotificationSetting
プッシュ通知に関する設定
GS2 のマイクロサービス内で何らかのイベントが発生した際に、プッシュ通知を送信するための設定です。
ここでいうプッシュ通知は GS2-Gateway の提供する WebSocket インターフェースを経由した処理であり、スマートフォンのプッシュ通知とは性質が異なります。
たとえば、マッチメイキングが完了した時やフレンドリクエストが届いた時など、ゲームクライアントの操作とは関係なく状態が変化した際に GS2-Gateway を経由してプッシュ通知をすることで、ゲームクライアントは状態の変化を検知することができます。
GS2-Gateway のプッシュ通知は通知先のデバイスがオフラインだった時に追加の処理としてモバイルプッシュ通知を送信できます。
モバイルプッシュ通知をうまく利用すれば、マッチメイキング中にゲームを終了しても、モバイルプッシュ通知を使用してプレイヤーに通知し、ゲームに戻ってくるフローを実現できる可能性があります。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| gatewayNamespaceId | string | “grn:gs2:{region}:{ownerId}:gateway:default” | ~ 1024文字 | プッシュ通知に使用する GS2-Gateway のネームスペース 「grn:gs2:」から始まる GRN 形式で GS2-Gateway のネームスペースIDを指定します。 | ||||||||
| enableTransferMobileNotification | bool? | false | モバイルプッシュ通知へ転送するか この通知を送信しようとした時、通知先のデバイスがオフラインだった場合、モバイルプッシュ通知へ転送するかどうかを指定します。 | |||||||||
| sound | string | {enableTransferMobileNotification} == true | ~ 1024文字 | モバイルプッシュ通知で使用するサウンドファイル名 ここで指定したサウンドファイル名は、モバイルプッシュ通知を送信する際に使用され、特別なサウンドで通知を出すことができます。 ※ enableTransferMobileNotification が true であれば 有効 | ||||||||
| mobileNotificationMessages | List<MobileNotificationMessage> | {enableTransferMobileNotification} == true | 0 ~ 100 items | モバイルプッシュ通知へ転送するときの言語別のタイトルと本文 オフラインのプレイヤーへモバイルプッシュ通知として転送するときの、言語別のタイトルと本文です。 デバイストークンに登録された locale に一致するエントリ → default → 先頭 の順に採用します。未設定なら通知の payload の mobile 配列、それも無ければ payload をそのまま本文にします。※ enableTransferMobileNotification が true であれば 有効 | ||||||||
| enable | 文字列列挙型 enum { “Enabled”, “Disabled” } | “Enabled” | プッシュ通知を有効にするか
|
LogSetting
ログの出力設定
ログデータの出力設定を管理します。この型は、ログデータを書き出すために使用される GS2-Log ネームスペースの識別子(Namespace ID)を保持します。
ログネームスペースID(loggingNamespaceId)には、ログデータを収集し保存する GS2-Log のネームスペースを、GRNの形式で指定します。
この設定をすることで、設定されたネームスペース内で発生したAPIリクエスト・レスポンスのログデータが、対象の GS2-Log ネームスペース側へ出力されるようになります。
GS2-Log ではリアルタイムでログが提供され、システムの監視や分析、デバッグなどに利用できます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| loggingNamespaceId | string | ✓ | ~ 1024文字 | ログを出力する GS2-Log のネームスペース
GRN
「grn:gs2:」ではじまる GRN 形式のIDで指定する必要があります。 |
TransactionSetting
トランザクション設定
トランザクション設定は非推奨です。トランザクション設定(V2)がこれに置き換わります。トランザクション設定(V2)が存在しなかった頃に作成されたネームスペースのために残されており、トランザクション設定(V2)が設定されていない間だけ適用されます。新しく作成するネームスペースでは使用しないでください。
この設定は、トランザクションの実行に関わる要素――自動実行(AutoRun)、アトミック実行(AtomicCommit)、GS2-Distributor を利用した非同期実行、スクリプト結果の一括適用、GS2-JobQueue による入手アクションの非同期化、直列実行――をそれぞれ個別の項目として公開しているため、推奨構成以外の組み合わせも作れます。その推奨構成を 1 つの設定としてまとめたものがトランザクション設定(V2)です。トランザクション設定を使い続けるのは、トランザクション設定(V2)が提供しない挙動――トランザクションをクライアント実行のスタンプシートとして実行する、GS2-Distributor による AutoRun の非同期実行を行う、入手アクションを GS2-JobQueue に畳み込む――にすでに依存しているネームスペースに限ってください。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| enableAutoRun | bool | false | 発行したトランザクションをサーバーサイドで自動的に実行するか | |||
| enableAtomicCommit | bool | {enableAutoRun} == true | false | トランザクションの実行をアトミックにコミットするか ※ enableAutoRun が true であれば 有効 | ||
| transactionUseDistributor | bool | {enableAtomicCommit} == true | false | トランザクションを非同期処理で実行する ※ enableAtomicCommit が true であれば 有効 | ||
| commitScriptResultInUseDistributor | bool | {transactionUseDistributor} == true | false | スクリプトの結果コミット処理を非同期処理で実行するか ※ transactionUseDistributor が true であれば 有効 | ||
| acquireActionUseJobQueue | bool | {enableAtomicCommit} == true | false | 入手アクションを実行する際に GS2-JobQueue を使用するか ※ enableAtomicCommit が true であれば 有効 | ||
| enableSequentialExecution | bool | {enableAtomicCommit} == true | false | アトミックコミットのアクションを直列に実行し、同じ行を複数のアクションで更新できるようにするか ※ enableAtomicCommit が true であれば 有効 | ||
| distributorNamespaceId | string | “grn:gs2:{region}:{ownerId}:distributor:default” | ~ 1024文字 | トランザクションの実行に使用する GS2-Distributor ネームスペース GRN | ||
| queueNamespaceId | string | “grn:gs2:{region}:{ownerId}:queue:default” | ~ 1024文字 | トランザクションの実行に使用する GS2-JobQueue のネームスペース GRN |
SyncSetting
オブジェクト同期の設定
sync と stateMachine のルームが、割り当てられたときに受け取る設定です。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| objectCatalog | string | ~ 65536文字 | オブジェクトのカタログ ルームにオブジェクトの種類・フィールド・RPC・所有権の要求を検査させたい場合に設定します。 設定しない場合、ルームはこれらを検査しません。Prefab ID をキーにした JSON オブジェクトで指定します。 各項目には、同期するフィールドのビットマスク( fields)、更新できる主体(mode: player・lease・server)、lease の貸し出し期間(leaseMilliseconds)を指定します。player のオブジェクトには、所有者だけが呼べる RPC メソッド ID(methods)、参加者の誰でもほかのプレイヤーのオブジェクトに対して呼べる RPC メソッド ID( publicMethods)、誰でも所有権を取得できるか( ownership: fixed・takeover)、所有者の退出時に削除せずマスタークライアントへ引き継ぐか( keepOnLeave)も指定できます。プレイヤーオブジェクトの項目は、Unity SDK の Prefab Catalog から生成できます(Copy Object Catalog JSON)。 |
StateMachineSetting
サーバーサイドステートマシンの設定
stateMachine のルームで実行するルールです。ルールを StateMachineMaster として保存している
GS2-StateMachine のネームスペースと、実行するバージョンを指定します。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceId | string | ✓ | ~ 1024文字 | ルームのルールを保存している GS2-StateMachine ネームスペース GRN | ||
| version | long | 1 ~ 32503680000000 | ルームのルールのバージョンstateMachine のルームで実行する StateMachineMaster のバージョンです。省略すると、ルームが割り当てられた時点で登録されている最新のバージョンを使います。動いているルームは読み込んだバージョンを使い続けます。 |
ParticipantSetting
参加者の設定
キャラクターのランクや装備など、ルームのルールが参加者ごとに読むデータの設定です。プレイヤーが stateMachine のルームに
参加すると、ルームはそのプレイヤーのユーザーIDで GS2-Script を実行し、スクリプトが返した record をルームが続くあいだ
そのプレイヤーの分として保持します。ルールは Room.Participant で読みます。スクリプトはここで指定する GS2-Identifier
ユーザーの権限で実行され、プレイヤーがデータを書き換えることはできません。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| userId | string | ✓ | ~ 1024文字 | ルームが権限を引き受ける GS2-Identifier ユーザー
GRN
ルームが割り当てられたとき、GS2 はこのユーザーのプロジェクトトークンを発行してルームに渡し、ルームはそれで参加者の スクリプトを実行します。ユーザーには、スクリプトの実行など必要な権限だけを与えてください。 | ||
| scriptId | string | ✓ | ~ 1024文字 | 参加者のデータを作る GS2-Script GRN
プレイヤーが参加するとき、 args.userId を受け取って実行されます。データは result = { participant = { ... } } で返します。成功すると参加が確定し、失敗すると参加を拒否します。再接続したプレイヤーは最初の参加のときのデータを 使い続けます。 |
MobileNotificationMessage
モバイルプッシュ通知の言語別メッセージ
通知をモバイルプッシュ通知へ転送する際に使用する、言語別メッセージリストの 1 要素です。1 つの要素が 1 つのロケールに対するタイトルと本文を保持します。
採用される要素は、Firebase デバイストークンに登録されたロケールと locale が一致する要素 → locale が default の要素 → リストの先頭の要素、の順で選択されます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| locale | string | ~ 32文字 | メッセージの言語 この要素がどの言語に対するものかを表します。Firebase デバイストークンに登録されたロケールと照合されます。 ja や en のような任意の文字列を指定できます。default は特別な値で、端末のロケールに一致する要素がなかったときに使われるフォールバックの要素であることを表します。 | |||
| title | string | ~ 256文字 | プッシュ通知のタイトル この要素が採用されたときに、モバイルプッシュ通知のタイトルとして表示されるテキストです。省略した場合は、通知の件名が使用されます。 | |||
| message | string | ~ 1024文字 | プッシュ通知の本文 この要素が採用されたときに、モバイルプッシュ通知の本文として表示されるテキストです。 |