GS2-Gateway Deploy/CDK リファレンス
エンティティ
Deploy処理で操作の対象となるリソース
Namespace
ネームスペース
ネームスペースは、一つのプロジェクト内で同じサービスを異なる用途で複数利用するためのエンティティです。
GS2 の各サービスはネームスペース単位で管理されます。ネームスペースが異なれば、同じサービスでも完全に独立したデータ空間として扱われます。
そのため、各サービスの利用を開始するにあたってネームスペースを作成する必要があります。
Request
リソースの生成・更新リクエスト
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| description | string | ~ 1024文字 | 説明文 | |||
| transactionSettingV2 | TransactionSettingV2 | トランザクション設定(V2) このネームスペースが発行するトランザクションをどのように実行するかを決める設定です。設定する項目は、実行に使用する GS2-Distributor のネームスペースと、トランザクションに含まれるアクションを 1 件ずつ実行して先に実行されたアクションの結果を後続のアクションから使えるようにするか、まとめて同時に実行してレスポンスタイムを短くするか、の 2 つだけです。 新しく作成するネームスペースではこちらを設定してください。これに置き換えられて非推奨となった transactionSetting は、こちらが設定されていない間だけ使用されます。 | ||||
| firebaseSecret | string | ~ 1024文字 | Firebase の通知送信に使用するシークレットトークン Firebase Cloud Messaging (FCM) のサーバーキーまたはシークレットトークンです。対象プレイヤーがオフラインでゲーム内の WebSocket 通知を受信できない場合に、モバイルプッシュ通知への転送を有効にするために必要です。 | |||
| logSetting | LogSetting | ログの出力設定 ゲートウェイ操作のログデータを GS2-Log に出力するための設定です。GS2-Log のネームスペースを指定することで、WebSocket セッション管理、通知配信、Firebase トークン操作の API リクエスト・レスポンスログを収集できます。 |
GetAttr
!GetAttrタグで取得可能なリソースの生成結果
| 型 | 説明 | |
|---|---|---|
| Item | Namespace | 作成したネームスペース |
実装例
Type: GS2::Gateway::Namespace
Properties:
Name: namespace-0001
Description: null
TransactionSettingV2: null
FirebaseSecret: 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/gateway"
)
SampleStack := core.NewStack()
gateway.NewNamespace(
&SampleStack,
"namespace-0001",
gateway.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\Gateway\Model\Namespace_(
stack: $this,
name: "namespace-0001",
options: new \Gs2Cdk\Gateway\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.gateway.model.Namespace(
this,
"namespace-0001",
new io.gs2.cdk.gateway.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.Gs2Gateway.Model.Namespace(
stack: this,
name: "namespace-0001",
options: new Gs2Cdk.Gs2Gateway.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 gateway from "@/gs2cdk/gateway";
class SampleStack extends core.Stack
{
public constructor() {
super();
new gateway.model.Namespace(
this,
"namespace-0001",
{
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, gateway
class SampleStack(Stack):
def __init__(self):
super().__init__()
gateway.Namespace(
stack=self,
name='namespace-0001',
options=gateway.NamespaceOptions(
log_setting=core.LogSetting(
logging_namespace_id='grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001',
),
),
)
print(SampleStack().yaml()) # Generate TemplateTransactionSetting
トランザクション設定
トランザクション設定は非推奨です。トランザクション設定(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 |
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で指定する必要があります。 |
TransactionSettingV2
トランザクション設定(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 | アクションを直列ではなく並列に実行するか |