1. はじめに
Cloud Spanner はフルマネージドで水平スケール可能なグローバルに分散されたリレーショナル データベース サービスで、パフォーマンスと高可用性を損なうことなく ACID トランザクションと SQL セマンティクスを提供します。
これらの機能により、Spanner はグローバルなプレーヤー ベースを有効にしたいゲームや、データの整合性を重視するゲームのアーキテクチャに最適です。
このラボでは、リージョンの Spanner データベースとやり取りする 2 つの Go サービスを作成し、プレーヤーがアイテムとお金（item-service）を取得できるようにします。また、他のプレーヤーが購入できるように取引ポストにアイテムを一覧表示します（tradepost-service）。
このラボでは、Cloud Spanner ゲーム開発のスタートガイド Codelab で profile-service と matchmaking-service を使用してプレーヤーとゲームを生成している必要があります。
次に、Python ロード フレームワーク Locust.io を活用してデータを生成し、「ゲームプレイ」を通じてプレーヤーがお金やアイテムを獲得する様子をシミュレートします。プレーヤーは、取引ポストでアイテムを販売できます。他のプレーヤーは、十分な資金があればそのアイテムを購入できます。
また、Spanner にクエリを実行して、プレーヤーのアカウント残高とアイテム数、未処理または処理済みの取引注文に関する統計情報を取得します。
最後に、このラボで作成したリソースをクリーンアップします。
作成するアプリの概要
このラボでは、次の作業を行います。
- Cloud Spanner: ゲーム開発のスタートガイドで作成した Spanner インスタンスを再利用します。
- Go で記述された Item サービスをデプロイして、プレーヤーがアイテムとお金を取得する処理を行う
- Go で記述された取引ポスト サービスをデプロイして、プレーヤーが販売するアイテムをリストに登録し、他のプレーヤーがそのアイテムを購入するシミュレーションを行います。
学習内容
- 読み取り / 書き込みトランザクションを使用してデータ変更の整合性を確保する方法
- DML と Spanner ミューテーションを活用してデータを変更する方法
必要なもの
- 請求先アカウントに接続されている Google Cloud プロジェクト。
- ウェブブラウザ（Chrome、Firefox など）
- クリーンアップ ステップを除き、Cloud Spanner: ゲーム開発のスタートガイドを完了していること。
2. 設定と要件
Cloud Spanner: ゲーム開発のスタートガイド Codelab を完了する
Cloud Spanner ゲーム開発のスタートガイド Codelab を完了します。選手と試合のデータセットを取得するには、この操作が必要です。プレーヤーとゲームはアイテムとお金を入手するために必要です。アイテムとお金は、取引ポストでアイテムを販売したり、アイテムを購入したりするために使用されます。
Cloud Shell で環境変数を構成する
[Cloud Shell をアクティブにする] 
をクリックして Cloud Shell を開きます（以前に実行したことがあるため、環境のプロビジョニングと接続にはそれほど時間はかかりません）。
Cloud Shell に接続すると、すでに認証は完了しており、プロジェクトに各自の PROJECT_ID が設定されています。
Cloud Shell で SPANNER 環境変数を設定する
export SPANNER_PROJECT_ID=$GOOGLE_CLOUD_PROJECT
export SPANNER_INSTANCE_ID=cloudspanner-gaming
export SPANNER_DATABASE_ID=sample-game
スキーマを作成する
データベースが作成されたので、sample-game データベースでスキーマを定義できます。
このラボでは、game_items、player_items、player_ledger_entries、trade_orders の 4 つの新しいテーブルを作成します。
プレーヤー アイテムの関係
取引注文の関係
ゲームアイテムは game_items テーブルに追加され、プレーヤーが獲得できるようになります。player_items テーブルには、itemUUID と playerUUID の両方に対する外部キーがあり、プレイヤーが有効なアイテムのみを取得できるようにしています。
player_ledger_entries テーブルは、プレーヤーのアカウント残高の金銭的な変更を追跡します。これは、戦利品からお金を獲得したり、取引所でアイテムを販売したりすることで行えます。
最後に、trade_orders テーブルは、販売注文の投稿と、購入者による注文の履行を処理するために使用されます。
スキーマを作成するには、Cloud Console で Write DDL ボタンをクリックします。
ここでは、schema/trading.sql ファイルからスキーマ定義を入力します。
CREATE TABLE game_items
(
itemUUID STRING(36) NOT NULL,
item_name STRING(MAX) NOT NULL,
item_value NUMERIC NOT NULL,
available_time TIMESTAMP NOT NULL,
duration int64
)PRIMARY KEY (itemUUID);
CREATE TABLE player_items
(
playerItemUUID STRING(36) NOT NULL,
playerUUID STRING(36) NOT NULL,
itemUUID STRING(36) NOT NULL,
price NUMERIC NOT NULL,
source STRING(MAX) NOT NULL,
game_session STRING(36) NOT NULL,
acquire_time TIMESTAMP NOT NULL DEFAULT (CURRENT_TIMESTAMP()),
expires_time TIMESTAMP,
visible BOOL NOT NULL DEFAULT(true),
FOREIGN KEY (itemUUID) REFERENCES game_items (itemUUID),
FOREIGN KEY (game_session) REFERENCES games (gameUUID)
) PRIMARY KEY (playerUUID, playerItemUUID),
INTERLEAVE IN PARENT players ON DELETE CASCADE;
CREATE TABLE player_ledger_entries (
playerUUID STRING(36) NOT NULL,
source STRING(MAX) NOT NULL,
game_session STRING(36) NOT NULL,
amount NUMERIC NOT NULL,
entryDate TIMESTAMP NOT NULL OPTIONS (allow_commit_timestamp=true),
FOREIGN KEY (game_session) REFERENCES games (gameUUID)
) PRIMARY KEY (playerUUID, entryDate DESC),
INTERLEAVE IN PARENT players ON DELETE CASCADE;
CREATE TABLE trade_orders
(
orderUUID STRING(36) NOT NULL,
lister STRING(36) NOT NULL,
buyer STRING(36),
playerItemUUID STRING(36) NOT NULL,
trade_type STRING(5) NOT NULL,
list_price NUMERIC NOT NULL,
created TIMESTAMP NOT NULL DEFAULT (CURRENT_TIMESTAMP()),
ended TIMESTAMP,
expires TIMESTAMP NOT NULL DEFAULT (TIMESTAMP_ADD(CURRENT_TIMESTAMP(), interval 24 HOUR)),
active BOOL NOT NULL DEFAULT (true),
cancelled BOOL NOT NULL DEFAULT (false),
filled BOOL NOT NULL DEFAULT (false),
expired BOOL NOT NULL DEFAULT (false),
FOREIGN KEY (playerItemUUID) REFERENCES player_items (playerItemUUID)
) PRIMARY KEY (orderUUID);
CREATE INDEX TradeItem ON trade_orders(playerItemUUID, active);
[Submit] ボタンをクリックしてスキーマを変更し、スキーマの更新が完了するまで待ちます。
次のステップ
次に、アイテム サービスをデプロイします。
3. アイテム サービスをデプロイする
サービスの概要
アイテム サービスは、gin フレームワークを活用する Go で記述された REST API です。この API では、オープン ゲームに参加しているプレーヤーがお金やアイテムを獲得します。
./src/golang/item-service/main.go ファイルは、ゲームアイテムとそれらを取得するプレイヤーを操作するための次のエンドポイントを構成します。また、プレーヤーがお金を獲得するためのエンドポイントもあります。
func main() {
configuration, _ := config.NewConfig()
router := gin.Default()
router.SetTrustedProxies(nil)
router.Use(setSpannerConnection(configuration))
router.GET("/items", getItemUUIDs)
router.POST("/items", createItem)
router.GET("/items/:id", getItem)
router.PUT("/players/balance", updatePlayerBalance)
router.GET("/players", getPlayer)
router.POST("/players/items", addPlayerItem)
router.Run(configuration.Server.URL())
}
Spanner Connections の構成と使用は、前の Codelab の profile-service と matchmaking-service とまったく同じように処理されます。
アイテム サービスは、次の定義を持つ GameItem、Player、PlayerLedger、PlayerItem と連携します。
// models/game_items.go
type GameItem struct {
ItemUUID string `json:"itemUUID"`
Item_name string `json:"item_name"`
Item_value big.Rat `json:"item_value"`
Available_time time.Time `json:"available_time"`
Duration int64 `json:"duration"`
}
// models/players.go
type Player struct {
PlayerUUID string `json:"playerUUID" binding:"required,uuid4"`
Updated time.Time `json:"updated"`
Account_balance big.Rat `json:"account_balance"`
Current_game string `json:"current_game"`
}
type PlayerLedger struct {
PlayerUUID string `json:"playerUUID" binding:"required,uuid4"`
Amount big.Rat `json:"amount"`
Game_session string `json:"game_session"`
Source string `json:"source"`
}
// models/player_items.go
type PlayerItem struct {
PlayerItemUUID string `json:"playerItemUUID" binding:"omitempty,uuid4"`
PlayerUUID string `json:"playerUUID" binding:"required,uuid4"`
ItemUUID string `json:"itemUUID" binding:"required,uuid4"`
Source string `json:"source" binding:"required"`
Game_session string `json:"game_session" binding:"omitempty,uuid4"`
Price big.Rat `json:"price"`
AcquireTime time.Time `json:"acquire_time"`
ExpiresTime spanner.NullTime `json:"expires_time"`
Visible bool `json:"visible"`
}
まず、ゲームにアイテムが作成されている必要があります。これを行うには、/items エンドポイントへの POST リクエストが呼び出されます。これは、game_items テーブルへの非常にシンプルな DML 挿入です。
// main.go
func createItem(c *gin.Context) {
var item models.GameItem
if err := c.BindJSON(&item); err != nil {
c.AbortWithError(http.StatusBadRequest, err)
return
}
ctx, client := getSpannerConnection(c)
err := item.Create(ctx, client)
if err != nil {
c.AbortWithError(http.StatusBadRequest, err)
return
}
c.IndentedJSON(http.StatusCreated, item.ItemUUID)
}
// models/game_items.go
func (i *GameItem) Create(ctx context.Context, client spanner.Client) error {
// Initialize item values
i.ItemUUID = generateUUID()
if i.Available_time.IsZero() {
i.Available_time = time.Now()
}
// insert into spanner
_, err := client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
stmt := spanner.Statement{
SQL: `INSERT game_items (itemUUID, item_name, item_value, available_time, duration)
VALUES (@itemUUID, @itemName, @itemValue, @availableTime, @duration)
`,
Params: map[string]interface{}{
"itemUUID": i.ItemUUID,
"itemName": i.Item_name,
"itemValue": i.Item_value,
"availableTime": i.Available_time,
"duration": i.Duration,
},
}
_, err := txn.Update(ctx, stmt)
return err
})
if err != nil {
return err
}
// return empty error on success
return nil
}
アイテムを取得するには、/players/items エンドポイントへの POST リクエストが呼び出されます。このエンドポイントのロジックは、ゲームアイテムの現在の値とプレーヤーの現在のゲーム セッションを取得することです。次に、アイテムの入手元と入手時刻を示す適切な情報を player_items テーブルに挿入します。
これは、次の関数にマッピングされます。
// main.go
func addPlayerItem(c *gin.Context) {
var playerItem models.PlayerItem
if err := c.BindJSON(&playerItem); err != nil {
c.AbortWithError(http.StatusBadRequest, err)
return
}
ctx, client := getSpannerConnection(c)
err := playerItem.Add(ctx, client)
if err != nil {
c.AbortWithError(http.StatusBadRequest, err)
return
}
c.IndentedJSON(http.StatusCreated, playerItem)
}
// models/player_items.go
func (pi *PlayerItem) Add(ctx context.Context, client spanner.Client) error {
// insert into spanner
_, err := client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
// Get item price at time of transaction
price, err := GetItemPrice(ctx, txn, pi.ItemUUID)
if err != nil {
return err
}
pi.Price = price
// Get Game session
session, err := GetPlayerSession(ctx, txn, pi.PlayerUUID)
if err != nil {
return err
}
pi.Game_session = session
pi.PlayerItemUUID = generateUUID()
// Insert
cols := []string{"playerItemUUID", "playerUUID", "itemUUID", "price", "source", "game_session"}
txn.BufferWrite([]*spanner.Mutation{
spanner.Insert("player_items", cols,
[]interface{}{pi.PlayerItemUUID, pi.PlayerUUID, pi.ItemUUID, pi.Price, pi.Source, pi.Game_session}),
})
return nil
})
if err != nil {
return err
}
// return empty error on success
return nil
}
プレーヤーがお金を獲得するには、/players/updatebalance エンドポイントへの PUT リクエストが呼び出されます。
このエンドポイントのロジックは、amount を適用した後にプレーヤーの残高を更新し、player_ledger_entries テーブルに獲得の記録を更新することです。プレーヤーの account_balance が変更され、呼び出し元に返されます。DML は、players と player_ledger_entries の両方を変更するために使用されます。
これは、次の関数にマッピングされます。
// main.go
func updatePlayerBalance(c *gin.Context) {
var player models.Player
var ledger models.PlayerLedger
if err := c.BindJSON(&ledger); err != nil {
c.AbortWithError(http.StatusBadRequest, err)
return
}
ctx, client := getSpannerConnection(c)
err := ledger.UpdateBalance(ctx, client, &player)
if err != nil {
c.AbortWithError(http.StatusBadRequest, err)
return
}
type PlayerBalance struct {
PlayerUUID, AccountBalance string
}
balance := PlayerBalance{PlayerUUID: player.PlayerUUID, AccountBalance: player.Account_balance.FloatString(2)}
c.IndentedJSON(http.StatusOK, balance)
}
// models/players.go
func (l *PlayerLedger) UpdateBalance(ctx context.Context, client spanner.Client, p *Player) error {
// Update balance with new amount
_, err := client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
p.PlayerUUID = l.PlayerUUID
stmt := spanner.Statement{
SQL: `UPDATE players SET account_balance = (account_balance + @amount) WHERE playerUUID = @playerUUID`,
Params: map[string]interface{}{
"amount": l.Amount,
"playerUUID": p.PlayerUUID,
},
}
numRows, err := txn.Update(ctx, stmt)
if err != nil {
return err
}
// No rows modified. That's an error
if numRows == 0 {
errorMsg := fmt.Sprintf("Account balance for player '%s' could not be updated", p.PlayerUUID)
return errors.New(errorMsg)
}
// Get player's new balance (read after write)
stmt = spanner.Statement{
SQL: `SELECT account_balance, current_game FROM players WHERE playerUUID = @playerUUID`,
Params: map[string]interface{}{
"playerUUID": p.PlayerUUID,
},
}
iter := txn.Query(ctx, stmt)
defer iter.Stop()
for {
row, err := iter.Next()
if err == iterator.Done {
break
}
if err != nil {
return err
}
var accountBalance big.Rat
var gameSession string
if err := row.Columns(&accountBalance, &gameSession); err != nil {
return err
}
p.Account_balance = accountBalance
l.Game_session = gameSession
}
stmt = spanner.Statement{
SQL: `INSERT INTO player_ledger_entries (playerUUID, amount, game_session, source, entryDate)
VALUES (@playerUUID, @amount, @game, @source, PENDING_COMMIT_TIMESTAMP())`,
Params: map[string]interface{}{
"playerUUID": l.PlayerUUID,
"amount": l.Amount,
"game": l.Game_session,
"source": l.Source,
},
}
numRows, err = txn.Update(ctx, stmt)
if err != nil {
return err
}
return nil
})
if err != nil {
return err
}
return nil
}
デフォルトでは、サービスは環境変数を使用して構成されます。./src/golang/item-service/config/config.go ファイルの関連セクションをご覧ください。
func NewConfig() (Config, error) {
*snip*
// Server defaults
viper.SetDefault("server.host", "localhost")
viper.SetDefault("server.port", 8082)
// Bind environment variable override
viper.BindEnv("server.host", "SERVICE_HOST")
viper.BindEnv("server.port", "SERVICE_PORT")
viper.BindEnv("spanner.project_id", "SPANNER_PROJECT_ID")
viper.BindEnv("spanner.instance_id", "SPANNER_INSTANCE_ID")
viper.BindEnv("spanner.database_id", "SPANNER_DATABASE_ID")
*snip*
return c, nil
}
デフォルトの動作では、サービスが localhost:8082 で実行されることがわかります。
この情報を使用して、サービスを実行します。
サービスを実行する
サービスを実行すると、依存関係がダウンロードされ、ポート 8082 で実行されるサービスが確立されます。
cd ~/spanner-gaming-sample/src/golang/item-service
go run . &
コマンド出力:
[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
- using env: export GIN_MODE=release
- using code: gin.SetMode(gin.ReleaseMode)
[GIN-debug] GET /items --> main.getItemUUIDs (4 handlers)
[GIN-debug] POST /items --> main.createItem (4 handlers)
[GIN-debug] GET /items/:id --> main.getItem (4 handlers)
[GIN-debug] PUT /players/balance --> main.updatePlayerBalance (4 handlers)
[GIN-debug] GET /players --> main.getPlayer (4 handlers)
[GIN-debug] POST /players/items --> main.addPlayerItem (4 handlers)
[GIN-debug] Listening and serving HTTP on localhost:8082
curl コマンドを発行してアイテムを作成し、サービスをテストします。
curl http://localhost:8082/items \
--include \
--header "Content-Type: application/json" \
--request "POST" \
--data '{"item_name": "test_item","item_value": "3.14"}'
コマンド出力:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: <Date>
Content-Length: 38
"aecde380-0a79-48c0-ab5d-0da675d3412c"
次に、プレーヤーがこのアイテムを入手できるようにします。これを行うには、ItemUUID と PlayerUUID が必要です。ItemUUID は、前のコマンドの出力です。この例では、aecde380-0a79-48c0-ab5d-0da675d3412c です。
PlayerUUID を取得するには、GET /players エンドポイントを呼び出します。
curl http://localhost:8082/players
コマンド出力:
{
"playerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352",
"updated": "0001-01-01T00:00:00Z",
"account_balance": {},
"current_game": "7b97fa85-5658-4ded-a962-4c09269a0a79"
}
プレーヤーがアイテムを取得するには、POST /players/items エンドポイントにリクエストを送信します。
curl http://localhost:8082/players/items \
--include \
--header "Content-Type: application/json" \
--request "POST" \
--data '{"playerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352","itemUUID": "109ec745-9906-402b-9d03-ca7153a10312", "source": "loot"}'
コマンド出力:
Content-Type: application/json; charset=utf-8
Date: <Date>
Content-Length: 369
{
"playerItemUUID": "a42b1899-4509-4fce-9958-265d2a2838a0",
"playerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352",
"itemUUID": "109ec745-9906-402b-9d03-ca7153a10312",
"source": "loot",
"game_session": "7b97fa85-5658-4ded-a962-4c09269a0a79",
"price": {},
"acquire_time": "0001-01-01T00:00:00Z",
"expires_time": null,
"visible": false
}
概要
このステップでは、ゲーム アイテムの作成を可能にし、オープン ゲームに割り当てられたプレイヤーがゲーム内通貨とゲーム アイテムを獲得できるようにするアイテム サービスをデプロイしました。
次のステップ
次のステップでは、tradepost サービスをデプロイします。
4. トレードポスト サービスをデプロイする
サービスの概要
tradepost サービスは、gin フレームワークを活用する Go で記述された REST API です。この API では、プレーヤー アイテムは sell に投稿されます。ゲームのプレーヤーは、公開されている取引を取得し、十分な資金があればアイテムを購入できます。
tradepost サービスの ./src/golang/tradepost-service/main.go ファイルは、他のサービスと同様の設定とコードに従っているため、ここでは繰り返しません。このサービスは、次のように複数のエンドポイントを公開します。
func main() {
configuration, _ := config.NewConfig()
router := gin.Default()
router.SetTrustedProxies(nil)
router.Use(setSpannerConnection(configuration))
router.GET("/trades/player_items", getPlayerItem)
router.POST("/trades/sell", createOrder)
router.GET("/trades/open", getOpenOrder)
router.PUT("/trades/buy", purchaseOrder)
router.Run(configuration.Server.URL())
}
このサービスは、TradeOrder 構造体と、GameItem、PlayerItem、Player、PlayerLedger 構造体に必要な構造体を提供します。
type TradeOrder struct {
OrderUUID string `json:"orderUUID" binding:"omitempty,uuid4"`
Lister string `json:"lister" binding:"omitempty,uuid4"`
Buyer string `json:"buyer" binding:"omitempty,uuid4"`
PlayerItemUUID string `json:"playerItemUUID" binding:"omitempty,uuid4"`
TradeType string `json:"trade_type"`
ListPrice big.Rat `json:"list_price" spanner:"list_price"`
Created time.Time `json:"created"`
Ended spanner.NullTime `json:"ended"`
Expires time.Time `json:"expires"`
Active bool `json:"active"`
Cancelled bool `json:"cancelled"`
Filled bool `json:"filled"`
Expired bool `json:"expired"`
}
type GameItem struct {
ItemUUID string `json:"itemUUID"`
ItemName string `json:"item_name"`
ItemValue big.Rat `json:"item_value"`
AvailableTime time.Time `json:"available_time"`
Duration int64 `json:"duration"`
}
type PlayerItem struct {
PlayerItemUUID string `json:"playerItemUUID" binding:"omitempty,uuid4"`
PlayerUUID string `json:"playerUUID" binding:"required,uuid4"`
ItemUUID string `json:"itemUUID" binding:"required,uuid4"`
Source string `json:"source"`
GameSession string `json:"game_session" binding:"omitempty,uuid4"`
Price big.Rat `json:"price"`
AcquireTime time.Time `json:"acquire_time" spanner:"acquire_time"`
ExpiresTime spanner.NullTime `json:"expires_time" spanner:"expires_time"`
Visible bool `json:"visible"`
}
type Player struct {
PlayerUUID string `json:"playerUUID" binding:"required,uuid4"`
Updated time.Time `json:"updated"`
AccountBalance big.Rat `json:"account_balance" spanner:"account_balance"`
CurrentGame string `json:"current_game" binding:"omitempty,uuid4" spanner:"current_game"`
}
type PlayerLedger struct {
PlayerUUID string `json:"playerUUID" binding:"required,uuid4"`
Amount big.Rat `json:"amount"`
GameSession string `json:"game_session" spanner:"game_session"`
Source string `json:"source"`
}
取引注文を作成するには、API エンドポイント /trades/sell に POST リクエストを発行します。必要な情報は、販売する player_item の playerItemUUID、lister、list_price です。
Spanner ミューテーションが選択され、トレード注文が作成され、player_item が非表示としてマークされます。これにより、販売者が重複する商品を販売用に投稿することを防ぐことができます。
func (o *TradeOrder) Create(ctx context.Context, client spanner.Client) error {
// insert into spanner
_, err := client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
// get the Item to be listed
pi, err := GetPlayerItem(ctx, txn, o.Lister, o.PlayerItemUUID)
if err != nil {
return err
}
// Set expires to 1 day by default
if o.Expires.IsZero() {
currentTime := time.Now()
o.Expires = currentTime.Add(time.Hour * 24)
}
// Item is not visible or expired, so it can't be listed. That's an error
if !validateSellOrder(pi) {
errorMsg := fmt.Sprintf("Item (%s, %s) cannot be listed.", o.Lister, o.PlayerItemUUID)
return errors.New(errorMsg)
}
// Initialize order values
o.OrderUUID = generateUUID()
o.Active = true // TODO: Have to set this by default since testing with emulator does not support 'DEFAULT' schema option
// Insert the order
var m []*spanner.Mutation
cols := []string{"orderUUID", "playerItemUUID", "lister", "list_price", "trade_type", "expires", "active"}
m = append(m, spanner.Insert("trade_orders", cols, []interface{}{o.OrderUUID, o.PlayerItemUUID, o.Lister, o.ListPrice, "sell", o.Expires, o.Active}))
// Mark the item as invisible
cols = []string{"playerUUID", "playerItemUUID", "visible"}
m = append(m, spanner.Update("player_items", cols, []interface{}{o.Lister, o.PlayerItemUUID, false}))
txn.BufferWrite(m)
return nil
})
if err != nil {
return err
}
// return empty error on success
return nil
}
実際に注文を作成する前に、PlayerItem が検証され、販売対象として登録できることが確認されます。主に、PlayerItem がプレーヤーに表示され、有効期限が切れていないことを意味します。
// Validate that the order can be placed: Item is visible and not expired
func validateSellOrder(pi PlayerItem) bool {
// Item is not visible, can't be listed
if !pi.Visible {
return false
}
// item is expired. can't be listed
if !pi.ExpiresTime.IsNull() && pi.ExpiresTime.Time.Before(time.Now()) {
return false
}
// All validation passed. Item can be listed
return true
}
購入は、/trades/buy エンドポイントへの PUT リクエストによって行われます。必要な情報は orderUUID と buyer です。これは購入を行うプレーヤーの UUID です。
この複雑さと変更の量のため、注文の購入には再びミューテーションが選択されます。次のオペレーションは、単一の読み取り / 書き込みトランザクションで行われます。
- 注文が以前に履行されておらず、期限切れになっていないため、注文を履行できることを検証します。
// Validate that the order can be filled: Order is active and not expired
func validatePurchase(o TradeOrder) bool {
// Order is not active
if !o.Active {
return false
}
// order is expired. can't be filled
if !o.Expires.IsZero() && o.Expires.Before(time.Now()) {
return false
}
// All validation passed. Order can be filled
return true
}
- 購入者の情報を取得し、アイテムを購入できることを検証します。つまり、購入者は出品者と同じではなく、十分な資金があるということです。
// Validate that a buyer can buy this item.
func validateBuyer(b Player, o TradeOrder) bool {
// Lister can't be the same as buyer
if b.PlayerUUID == o.Lister {
return false
}
// Big.rat returns -1 if Account_balance is less than price
if b.AccountBalance.Cmp(&o.ListPrice) == -1 {
return false
}
return true
}
- 注文の list_price を lister のアカウント残高に追加し、対応する台帳エントリを作成します。
// models/trade_order.go
// Buy an order
func (o *TradeOrder) Buy(ctx context.Context, client spanner.Client) error {
*snip*
// Update seller's account balance
lister.UpdateBalance(ctx, txn, o.ListPrice)
*snip*
}
// models/players.go
// Update a player's balance, and add an entry into the player ledger
func (p *Player) UpdateBalance(ctx context.Context, txn *spanner.ReadWriteTransaction, newAmount big.Rat) error {
// This modifies player's AccountBalance, which is used to update the player entry
p.AccountBalance.Add(&p.AccountBalance, &newAmount)
txn.BufferWrite([]*spanner.Mutation{
spanner.Update("players", []string{"playerUUID", "account_balance"}, []interface{}{p.PlayerUUID, p.AccountBalance}),
spanner.Insert("player_ledger_entries", []string{"playerUUID", "amount", "game_session", "source", "entryDate"},
[]interface{}{p.PlayerUUID, newAmount, p.CurrentGame, "tradepost", spanner.CommitTimestamp}),
})
return nil
}
- 注文の list_price を購入者のアカウント残高から差し引き、一致する台帳エントリを作成します。
// Update buyer's account balance
negAmount := o.ListPrice.Neg(&o.ListPrice)
buyer.UpdateBalance(ctx, txn, *negAmount)
- ゲームと購入者の詳細を含むゲームアイテムの新しいインスタンスを PlayerItems テーブルに挿入して player_item を新しいプレーヤーに移動し、出品者のアイテムのインスタンスを削除します。
// models/player_items.go
// Move an item to a new player, removes the item entry from the old player
func (pi *PlayerItem) MoveItem(ctx context.Context, txn *spanner.ReadWriteTransaction, toPlayer string) error {
fmt.Printf("Buyer: %s", toPlayer)
txn.BufferWrite([]*spanner.Mutation{
spanner.Insert("player_items", []string{"playerItemUUID", "playerUUID", "itemUUID", "price", "source", "game_session"},
[]interface{}{pi.PlayerItemUUID, toPlayer, pi.ItemUUID, pi.Price, pi.Source, pi.GameSession}),
spanner.Delete("player_items", spanner.Key{pi.PlayerUUID, pi.PlayerItemUUID}),
})
return nil
}
- Orders エントリを更新して、アイテムが入力され、アクティブではなくなったことを示します。
まとめると、Buy 関数は次のようになります。
// Buy an order
func (o *TradeOrder) Buy(ctx context.Context, client spanner.Client) error {
// Fulfil the order
_, err := client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
// Get Order information
err := o.getOrderDetails(ctx, txn)
if err != nil {
return err
}
// Validate order can be filled
if !validatePurchase(*o) {
errorMsg := fmt.Sprintf("Order (%s) cannot be filled.", o.OrderUUID)
return errors.New(errorMsg)
}
// Validate buyer has the money
buyer := Player{PlayerUUID: o.Buyer}
err = buyer.GetBalance(ctx, txn)
if err != nil {
return err
}
if !validateBuyer(buyer, *o) {
errorMsg := fmt.Sprintf("Buyer (%s) cannot purchase order (%s).", buyer.PlayerUUID, o.OrderUUID)
return errors.New(errorMsg)
}
// Move money from buyer to seller (which includes ledger entries)
var m []*spanner.Mutation
lister := Player{PlayerUUID: o.Lister}
err = lister.GetBalance(ctx, txn)
if err != nil {
return err
}
// Update seller's account balance
lister.UpdateBalance(ctx, txn, o.ListPrice)
// Update buyer's account balance
negAmount := o.ListPrice.Neg(&o.ListPrice)
buyer.UpdateBalance(ctx, txn, *negAmount)
// Move item from seller to buyer, mark item as visible.
pi, err := GetPlayerItem(ctx, txn, o.Lister, o.PlayerItemUUID)
if err != nil {
return err
}
pi.GameSession = buyer.CurrentGame
// Moves the item from lister (current pi.PlayerUUID) to buyer
pi.MoveItem(ctx, txn, o.Buyer)
// Update order information
cols := []string{"orderUUID", "active", "filled", "buyer", "ended"}
m = append(m, spanner.Update("trade_orders", cols, []interface{}{o.OrderUUID, false, true, o.Buyer, time.Now()}))
txn.BufferWrite(m)
return nil
})
if err != nil {
return err
}
// return empty error on success
return nil
}
デフォルトでは、サービスは環境変数を使用して構成されます。./src/golang/tradepost-service/config/config.go ファイルの関連セクションをご覧ください。
func NewConfig() (Config, error) {
*snip*
// Server defaults
viper.SetDefault("server.host", "localhost")
viper.SetDefault("server.port", 8083)
// Bind environment variable override
viper.BindEnv("server.host", "SERVICE_HOST")
viper.BindEnv("server.port", "SERVICE_PORT")
viper.BindEnv("spanner.project_id", "SPANNER_PROJECT_ID")
viper.BindEnv("spanner.instance_id", "SPANNER_INSTANCE_ID")
viper.BindEnv("spanner.database_id", "SPANNER_DATABASE_ID")
*snip*
return c, nil
}
デフォルトの動作では、他のサービスとの競合を避けるために、サービスが localhost:8083 で実行されることがわかります。
この情報を使用して、トレードポスト サービスを実行します。
サービスを実行する
サービスを実行すると、ポート 8083 で実行されるサービスが確立されます。このサービスには item-service と同じ依存関係が多数あるため、新しい依存関係はダウンロードされません。
cd ~/spanner-gaming-sample/src/golang/tradepost-service
go run . &
コマンド出力:
[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
- using env: export GIN_MODE=release
- using code: gin.SetMode(gin.ReleaseMode)
[GIN-debug] GET /trades/player_items --> main.getPlayerItem (4 handlers)
[GIN-debug] POST /trades/sell --> main.createOrder (4 handlers)
[GIN-debug] GET /trades/open --> main.getOpenOrder (4 handlers)
[GIN-debug] PUT /trades/buy --> main.purchaseOrder (4 handlers)
[GIN-debug] Listening and serving HTTP on localhost:8083
アイテムを投稿する
GET リクエストを発行して、販売する PlayerItem を取得し、サービスをテストします。
curl http://localhost:8083/trades/player_items
コマンド出力:
{
"PlayerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352",
"PlayerItemUUID": "a42b1899-4509-4fce-9958-265d2a2838a0",
"Price": "3.14"
}
次に、/trades/sell エンドポイントを呼び出して、販売するアイテムを投稿します。
curl http://localhost:8083/trades/sell \
--include \
--header "Content-Type: application/json" \
--request "POST" \
--data '{"lister": "<PlayerUUID>","playerItemUUID": "<PlayerItemUUID>", "list_price": "<some price higher than item's price>"}'
コマンド出力:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: <Date>
Content-Length: 38
"282ea691-b956-4c4c-95ff-f461d6415651"
概要
このステップでは、販売注文の作成を処理する tradepost-service をデプロイしました。このサービスは、これらの注文を購入する機能も処理します。
次のステップ
サービスが実行されたので、次は取引所でプレイヤーが売買する様子をシミュレートします。
5. 取引を開始する
アイテム サービスとトレードポスト サービスが実行されているので、提供されている locust ジェネレータを使用して負荷を生成できます。
Locust にはジェネレータを実行するためのウェブ インターフェースがありますが、このラボではコマンドライン（–headless オプション）を使用します。
ゲームアイテムを生成する
まず、アイテムを生成します。./generators/item_generator.py ファイルには、名前のランダムな文字列とランダムな価格値を使用してゲームアイテムを作成するタスクが含まれています。
# Generate random items
class ItemLoad(HttpUser):
def generateItemName(self):
return ''.join(random.choices(string.ascii_lowercase + string.digits, k=32))
def generateItemValue(self):
return str(decimal.Decimal(random.randrange(100, 10000))/100)
@task
def createItem(self):
headers = {"Content-Type": "application/json"}
data = {"item_name": self.generateItemName(), "item_value": self.generateItemValue()}
self.client.post("/items", data=json.dumps(data), headers=headers)
次のコマンドは、10 秒間（t=10s）ゲームアイテムを生成する item_generator.py ファイルを呼び出します。
cd ~/spanner-gaming-sample
locust -H http://127.0.0.1:8082 -f ./generators/item_generator.py --headless -u=1 -r=1 -t=10s
コマンド出力:
*snip*
/INFO/locust.main: --run-time limit reached. Stopping Locust
/INFO/locust.main: Shutting down (exit code 0)
Name # reqs # fails | Avg Min Max Median | req/s failures/s
----------------------------------------------------------------------------------------------------------------------------------------------------------------
POST /items 606 0(0.00%) | 16 12 161 15 | 60.61 0.00
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Aggregated 606 0(0.00%) | 16 12 161 15 | 60.61 0.00
Response time percentiles (approximated)
Type Name 50% 66% 75% 80% 90% 95% 98% 99% 99.9% 99.99% 100% # reqs
--------|--------------------------------------------------------------------------------|---------|------|------|------|------|------|------|------|------|------|------|------|
POST /items 15 16 16 17 18 19 21 34 160 160 160 606
--------|--------------------------------------------------------------------------------|---------|------|------|------|------|------|------|------|------|------|------|------|
None Aggregated 15 16 16 17 18 19 21 34 160 160 160 606
プレーヤーがアイテムやお金を獲得する
次に、プレイヤーがアイテムやお金を獲得して、取引所に参加できるようにします。これを行うために、./generators/game_server.py ファイルは、プレーヤーに割り当てるゲームアイテムとランダムな通貨額を取得するタスクを提供します。
# Players generate items and money at 5:2 ratio. We don't want to devalue the currency!
class GameLoad(HttpUser):
def on_start(self):
self.getItems()
def getItems(self):
headers = {"Content-Type": "application/json"}
r = requests.get(f"{self.host}/items", headers=headers)
global itemUUIDs
itemUUIDs = json.loads(r.text)
def generateAmount(self):
return str(round(random.uniform(1.01, 49.99), 2))
@task(2)
def acquireMoney(self):
headers = {"Content-Type": "application/json"}
# Get a random player that's part of a game, and update balance
with self.client.get("/players", headers=headers, catch_response=True) as response:
try:
data = {"playerUUID": response.json()["playerUUID"], "amount": self.generateAmount(), "source": "loot"}
self.client.put("/players/balance", data=json.dumps(data), headers=headers)
except json.JSONDecodeError:
response.failure("Response could not be decoded as JSON")
except KeyError:
response.failure("Response did not contain expected key 'playerUUID'")
@task(5)
def acquireItem(self):
headers = {"Content-Type": "application/json"}
# Get a random player that's part of a game, and add an item
with self.client.get("/players", headers=headers, catch_response=True) as response:
try:
itemUUID = itemUUIDs[random.randint(0, len(itemUUIDs)-1)]
data = {"playerUUID": response.json()["playerUUID"], "itemUUID": itemUUID, "source": "loot"}
self.client.post("/players/items", data=json.dumps(data), headers=headers)
except json.JSONDecodeError:
response.failure("Response could not be decoded as JSON")
except KeyError:
response.failure("Response did not contain expected key 'playerUUID'")
このコマンドを使用すると、プレーヤーは 60 秒間アイテムとお金を入手できます。
locust -H http://127.0.0.1:8082 -f game_server.py --headless -u=1 -r=1 -t=60s
コマンド出力:
*snip*
dev-machine/INFO/locust.main: --run-time limit reached. Stopping Locust
dev-machine/INFO/locust.main: Shutting down (exit code 0)
Name # reqs # fails | Avg Min Max Median | req/s failures/s
----------------------------------------------------------------------------------------------------------------------------------------------------------------
GET /players 231 0(0.00%) | 14 9 30 13 | 23.16 0.00
PUT /players/balance 53 0(0.00%) | 33 30 39 34 | 5.31 0.00
POST /players/items 178 0(0.00%) | 26 22 75 26 | 17.85 0.00
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Aggregated 462 0(0.00%) | 21 9 75 23 | 46.32 0.00
Response time percentiles (approximated)
Type Name 50% 66% 75% 80% 90% 95% 98% 99% 99.9% 99.99% 100% # reqs
--------|--------------------------------------------------------------------------------|---------|------|------|------|------|------|------|------|------|------|------|------|
GET /players 13 16 17 17 19 20 21 23 30 30 30 231
PUT /players/balance 34 34 35 35 36 37 38 40 40 40 40 53
POST /players/items 26 27 27 27 28 29 34 53 76 76 76 178
--------|--------------------------------------------------------------------------------|---------|------|------|------|------|------|------|------|------|------|------|------|
None Aggregated 23 26 27 27 32 34 36 37 76 76 76 462
取引所で売買するプレイヤー
アイテムとアイテムを購入するお金が揃ったら、取引所を利用できるようになります。
./generators/trading_server.py ジェネレータ ファイルは、販売注文を作成して注文を履行するタスクを提供します。
# Players can sell and buy items
class TradeLoad(HttpUser):
def itemMarkup(self, value):
f = float(value)
return str(f*1.5)
@task
def sellItem(self):
headers = {"Content-Type": "application/json"}
# Get a random item
with self.client.get("/trades/player_items", headers=headers, catch_response=True) as response:
try:
playerUUID = response.json()["PlayerUUID"]
playerItemUUID = response.json()["PlayerItemUUID"]
list_price = self.itemMarkup(response.json()["Price"])
# Currently don't have any items that can be sold, retry
if playerItemUUID == "":
raise RescheduleTask()
data = {"lister": playerUUID, "playerItemUUID": playerItemUUID, "list_price": list_price}
self.client.post("/trades/sell", data=json.dumps(data), headers=headers)
except json.JSONDecodeError:
response.failure("Response could not be decoded as JSON")
except KeyError:
response.failure("Response did not contain expected key 'playerUUID'")
@task
def buyItem(self):
headers = {"Content-Type": "application/json"}
# Get a random item
with self.client.get("/trades/open", headers=headers, catch_response=True) as response:
try:
orderUUID = response.json()["OrderUUID"]
buyerUUID = response.json()["BuyerUUID"]
# Currently don't have any buyers that can fill the order, retry
if buyerUUID == "":
raise RescheduleTask()
data = {"orderUUID": orderUUID, "buyer": buyerUUID}
self.client.put("/trades/buy", data=json.dumps(data), headers=headers)
except json.JSONDecodeError:
response.failure("Response could not be decoded as JSON")
except KeyError:
response.failure("Response did not contain expected key 'playerUUID'")
このコマンドを使用すると、プレーヤーは獲得したアイテムを販売用にリストに登録し、他のプレーヤーは 10 秒間そのアイテムを購入できます。
locust -H http://127.0.0.1:8083 -f ./generators/trading_server.py --headless -u=1 -r=1 -t=10s
コマンド出力:
*snip*
Name # reqs # fails | Avg Min Max Median | req/s failures/s
----------------------------------------------------------------------------------------------------------------------------------------------------------------
PUT /trades/buy 20 5(25.00%) | 43 10 78 43 | 2.07 0.52
GET /trades/open 20 0(0.00%) | 358 7 971 350 | 2.07 0.00
GET /trades/player_items 20 0(0.00%) | 49 35 113 41 | 2.07 0.00
POST /trades/sell 20 0(0.00%) | 29 21 110 24 | 2.07 0.00
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Aggregated 80 5(6.25%) | 120 7 971 42 | 8.29 0.52
Response time percentiles (approximated)
Type Name 50% 66% 75% 80% 90% 95% 98% 99% 99.9% 99.99% 100% # reqs
--------|--------------------------------------------------------------------------------|---------|------|------|------|------|------|------|------|------|------|------|------|
PUT /trades/buy 43 45 49 50 71 78 78 78 78 78 78 20
GET /trades/open 360 500 540 550 640 970 970 970 970 970 970 20
GET /trades/player_items 43 55 57 59 72 110 110 110 110 110 110 20
POST /trades/sell 24 25 25 27 50 110 110 110 110 110 110 20
--------|--------------------------------------------------------------------------------|---------|------|------|------|------|------|------|------|------|------|------|------|
None Aggregated 42 50 71 110 440 550 640 970 970 970 970 80
概要
このステップでは、ゲームをプレイするために登録するプレーヤーをシミュレートし、マッチメイキング サービスを使用してゲームをプレイするプレーヤーのシミュレーションを実行しました。これらのシミュレーションでは、Locust Python フレームワークを利用して、サービスの REST API にリクエストを発行しました。
プレーヤーの作成とゲームのプレイに費やす時間や、同時ユーザー数（-u）は適宜変更してください。
次のステップ
シミュレーション後、Spanner にクエリを実行してさまざまな統計情報を確認します。
6. 取引統計情報を取得する
プレイヤーがお金とアイテムを獲得し、そのアイテムを取引所で販売するシミュレーションを行ったので、いくつかの統計情報を確認しましょう。
これを行うには、Cloud Console を使用して Spanner にクエリ リクエストを発行します。
未処理の取引注文と完了済みの取引注文を確認する
取引所で TradeOrder が購入されると、filled メタデータ フィールドが更新されます。
このクエリを使用すると、未処理の注文数と処理済みの注文数を確認できます。
-- Open vs Filled Orders
SELECT Type, NumTrades FROM
(SELECT "Open Trades" as Type, count(*) as NumTrades FROM trade_orders WHERE active=true
UNION ALL
SELECT "Filled Trades" as Type, count(*) as NumTrades FROM trade_orders WHERE filled=true
)
結果:
タイプ | NumTrades |
未決済の取引 | 159 |
約定した取引 | 454 |
プレーヤーのアカウント残高とアイテム数を確認する
current_game 列が設定されている場合、プレーヤーはゲームをプレイしています。それ以外の場合は、現在ゲームをプレイしていません。
現在ゲームをプレイしている上位 10 人のプレーヤーを、アイテムの数と account_balance で取得します。
, 次のクエリを使用します。
SELECT playerUUID, account_balance, (SELECT COUNT(*) FROM player_items WHERE playerUUID=p.PlayerUUID) AS numItems, current_game
FROM players AS p
WHERE current_game IS NOT NULL
ORDER BY numItems DESC
LIMIT 10;
結果:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
概要
このステップでは、Cloud コンソールを使用して Spanner にクエリを実行し、プレーヤーと取引注文のさまざまな統計情報を確認しました。
次のステップ
次に、クリーンアップを行います。
7. クリーンアップ
Spanner の操作を楽しんだ後は、使用した環境をクリーンアップする必要があります。この手順は簡単で、Cloud Console の Cloud Spanner セクションに移動して、この Codelab で作成したインスタンスを削除するだけです。
8. 完了
これで、Spanner にサンプルゲームが正常にデプロイされました。
次のステップ
このラボでは、ゲームアイテムの生成と、取引所で販売されるアイテムをプレイヤーが取得する処理を行う 2 つのサービスの設定を完了しました。
これらのコードサンプルは、DML と Spanner ミューテーションの両方でトランザクション内の Cloud Spanner の整合性がどのように機能するかを理解するのに役立ちます。
提供されているジェネレータを使用して、Spanner のスケーリングを自由に試してください。