1. はじめに
Cloud Spanner は、水平スケーリングが可能なフルマネージドでグローバルに分散されたリレーショナル データベース サービスで、パフォーマンスと高可用性を犠牲にすることなく ACID トランザクションと SQL セマンティクスを提供します。
このような機能により、Spanner はグローバルなプレーヤー ベースを実現したいと考えているゲームのアーキテクチャや、データの整合性が問題となるゲームのアーキテクチャに非常に適しています。
このラボでは、リージョンの Spanner データベースとやり取りしてアイテムとお金（item-service)を取得できるようにする 2 つの Go サービスを作成し、他のプレーヤーが購入できるアイテムを取引ポストにリストできるようにします（tradepost-service）。
このラボでは、Cloud Spanner のゲーム開発を始める Codelab を利用して、profile-service と matchmaking-service を使用してプレーヤーとゲームを生成しています。
次に、Python の読み込みフレームワーク Locust.io を使用してデータを生成し、プレーヤーが「ゲームプレイ」の過程でお金やアイテムを獲得するをシミュレートします。プレーヤーは販売されているアイテムをトレードポストにリストでき、そこで十分なお金を持つ他のプレーヤーがそれらのアイテムを購入できます。
また、Spanner に対してクエリを実行して、口座の残高と商品数、処理中の注文や処理済みの注文に関する統計情報などがあります。
最後に、このラボで作成したリソースをクリーンアップします。
作成するアプリの概要
このラボでは、次の作業を行います。
- Cloud Spanner のゲーム開発の開始の Spanner インスタンスを再利用します。
- Go で記述されたアイテム サービスをデプロイして、プレーヤーがアイテムとお金を獲得できるようにする
- Go で記述されたトレーディング ポスト サービスをデプロイして、販売されているアイテムをリストするプレーヤーや、それらのアイテムを購入する他のプレーヤーをシミュレートします。
学習内容
- 読み取り / 書き込みトランザクションを使用してデータ変更時の整合性を確保する方法
- DML と Spanner のミューテーションを利用してデータを変更する方法
必要なもの
- 請求先アカウントに接続されている Google Cloud プロジェクト。
- ウェブブラウザ（Chrome、Firefox など）
- 以前に「Cloud Spanner Getting Started with Games Development」を完了し、クリーンアップ手順を実施していません。
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 データベースでスキーマを定義できます。
このラボでは、4 つの新しいテーブル（game_items、player_items、player_ledger_entries、trade_orders）を作成します。
プレーヤー アイテムの関係
取引注文の関係
ゲームアイテムは game_items テーブルに追加され、プレーヤーが獲得できるようになります。player_items テーブルには itemUUID と PlayerUUID の両方の外部キーがあるため、プレーヤーが有効なアイテムのみを取得できるようにします。
player_ledger_entries テーブルは、プレーヤーのアカウント残高の金銭的な変化を追跡します。たとえば、戦利品からお金を獲得したり、トレーディング ポストでアイテムを販売したりできます。
最後に、trade_orders テーブルは、販売注文の送信を処理し、購入者が注文を処理するために使用されます。
スキーマを作成するには、Cloud コンソールで 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 接続の構成と使用は、前の Codelab の profile-service や matchmake-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 では、プレーヤーのアイテムが送信されて販売されます。ゲームのプレーヤーはオープン トレードを受け取れます。十分なお金がある場合は、そのアイテムを購入できます。
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"`
}
取引注文を作成するには、POST リクエストが API エンドポイント /trades/sell に対して発行されます。必要な情報は、販売する 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)
- ゲームと buyer の詳細情報を含むゲーム アイテムの新しいインスタンスを 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 でサービスが実行されることがわかります**。
この情報をもとに、Tradepost サービスを実行します。
サービスを実行する
このサービスを実行すると、ポート 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
アイテムを投稿する
サービスをテストするために、販売する PlayerItem を取得する GET リクエストを発行します。
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 コンソールを使用して 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 コンソールの Cloud Spanner セクションに移動し、この Codelab 用に作成したインスタンスを削除するだけです。
8. 完了
これで、Spanner にサンプルゲームが正常にデプロイされました。
次のステップ
このラボでは、ゲーム アイテムの生成を処理する 2 つのサービスと、プレーヤーが取引ポストで販売するアイテムを取得するサービスを 2 つ設定しました。
これらのコードサンプルは、トランザクション内の Cloud Spanner の整合性が DML と Spanner の両方のミューテーションに対してどのように機能するかをより深く理解するのに役立ちます。
提供されているジェネレータを使用して、Spanner のスケーリングを試してみてください。