1. Pengantar
Cloud Spanner adalah layanan database relasional skalabel dan terkelola sepenuhnya secara horizontal yang terdistribusi secara global, yang menyediakan transaksi ACID dan semantik SQL tanpa mengorbankan performa dan ketersediaan tinggi.
Fitur-fitur ini menjadikan Spanner sangat cocok dalam arsitektur game yang ingin mengaktifkan basis pemain global atau mengkhawatirkan konsistensi data
Dalam lab ini, Anda akan membuat dua layanan Go yang berinteraksi dengan database Spanner regional untuk memungkinkan pemain mendapatkan item dan uang (item-service), lalu mencantumkan item di pusat jual beli agar dapat dibeli oleh pemain lain (tradepost-service).
Lab ini bergantung pada codelab Memulai Pengembangan Game dengan Cloud Spanner untuk membuat pemain dan game menggunakan profile-service dan matchmaking-service.
Selanjutnya, Anda akan membuat data menggunakan framework pemuatan Python Locust.io untuk menyimulasikan pemain yang memperoleh uang dan item selama "gameplay". Pemain kemudian dapat mencantumkan item untuk dijual di pos perdagangan, tempat pemain lain dengan uang yang cukup dapat membeli item tersebut.
Anda juga akan membuat kueri Spanner untuk menentukan saldo akun dan jumlah item pemain, serta beberapa statistik tentang pesanan perdagangan yang terbuka atau telah dipenuhi.
Terakhir, Anda akan membersihkan resource yang dibuat di lab ini.
Yang akan Anda build
Sebagai bagian dari lab ini, Anda akan:
- Gunakan kembali instance Spanner dari Memulai Cloud Spanner untuk Pengembangan Game.
- Men-deploy layanan Item yang ditulis dalam Go untuk menangani pemain yang mendapatkan item dan uang
- Deploy layanan Trading Post yang ditulis dalam Go untuk menyimulasikan pemain yang mencantumkan item untuk dijual, dan pemain lain yang membeli item tersebut.
Yang akan Anda pelajari
- Cara menggunakan transaksi baca-tulis untuk memastikan konsistensi perubahan data
- Cara memanfaatkan mutasi DML dan Spanner untuk mengubah data
Yang Anda butuhkan
- Project Google Cloud yang terhubung ke akun penagihan.
- Browser web, seperti Chrome atau Firefox.
- Sebelumnya telah menyelesaikan Cloud Spanner Getting Started with Games Development, tanpa langkah pembersihan.
2. Penyiapan dan Persyaratan
Selesaikan codelab Memulai Cloud Spanner dengan Pengembangan Game
Selesaikan codelab Cloud Spanner: Memulai Pengembangan Game. Hal ini diperlukan untuk mendapatkan set data pemain dan pertandingan. Pemain dan game diperlukan untuk mendapatkan item dan uang, yang selanjutnya digunakan untuk mencantumkan item untuk dijual dan membeli item dari pos perdagangan.
Mengonfigurasi variabel lingkungan di Cloud Shell
Buka Cloud Shell dengan mengklik Activate Cloud Shell 
(hanya perlu waktu beberapa saat untuk melakukan penyediaan dan terhubung ke lingkungan karena Anda telah melakukannya sebelumnya).
Setelah terhubung ke Cloud Shell, Anda akan melihat bahwa Anda sudah diautentikasi dan project sudah ditetapkan ke PROJECT_ID Anda.
Tetapkan variabel lingkungan SPANNER di Cloud Shell
export SPANNER_PROJECT_ID=$GOOGLE_CLOUD_PROJECT
export SPANNER_INSTANCE_ID=cloudspanner-gaming
export SPANNER_DATABASE_ID=sample-game
Buat skema
Setelah database dibuat, Anda dapat menentukan skema di database sample-game.
Lab ini akan membuat empat tabel baru: game_items, player_items, player_ledger_entries, dan trade_orders.
Hubungan item pemain
Hubungan pesanan perdagangan
Item game ditambahkan dalam tabel game_items, lalu dapat diperoleh oleh pemain. Tabel player_items memiliki kunci asing ke itemUUID dan playerUUID untuk memastikan pemain hanya memperoleh item yang valid.
Tabel player_ledger_entries melacak setiap perubahan moneter pada saldo akun pemain. Hal ini dapat dilakukan dengan mendapatkan uang dari jarahan, atau dengan menjual item di pos perdagangan.
Terakhir, tabel trade_orders digunakan untuk menangani postingan pesanan jual, dan bagi pembeli untuk memenuhi pesanan tersebut.
Untuk membuat skema, Anda akan mengklik tombol Write DDL di Konsol Cloud:
Di sini, Anda akan memasukkan definisi skema dari file 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);
Klik tombol 'Submit' untuk mengubah skema, dan tunggu hingga pembaruan skema selesai:
Berikutnya
Selanjutnya, Anda akan men-deploy layanan item.
3. Men-deploy layanan item
Ringkasan layanan
Layanan item adalah REST API yang ditulis dalam Go yang memanfaatkan framework gin. Dalam API ini, pemain yang berpartisipasi dalam game terbuka akan mendapatkan uang dan item.
File ./src/golang/item-service/main.go mengonfigurasi endpoint berikut untuk bekerja dengan item game dan pemain yang mendapatkan item tersebut. Selain itu, ada endpoint bagi pemain untuk mendapatkan uang.
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())
}
Konfigurasi dan penggunaan Spanner Connections ditangani persis seperti profile-service dan matchmaking-service dari codelab sebelumnya.
Layanan item berfungsi dengan GameItem, Player, PlayerLedger, dan PlayerItem dengan definisi berikut:
// 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"`
}
Pertama, game harus memiliki beberapa item yang dibuat. Untuk melakukannya, permintaan POST ke endpoint /items dipanggil. Ini adalah penyisipan DML yang sangat sederhana ke dalam tabel game_items.
// 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
}
Untuk mendapatkan item, permintaan POST ke endpoint /players/items dipanggil. Logika untuk endpoint ini adalah mengambil nilai saat ini item game, dan sesi game pemain saat ini. Kemudian, masukkan informasi yang sesuai ke dalam tabel player_items yang menunjukkan sumber dan waktu perolehan item.
Ini dipetakan ke fungsi berikut:
// 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
}
Agar pemain dapat memperoleh uang, permintaan PUT ke endpoint /players/updatebalance akan dipanggil.
Logika untuk endpoint ini adalah memperbarui saldo pemain setelah menerapkan jumlah, serta memperbarui tabel player_ledger_entries dengan catatan akuisisi. account_balance pemain diubah untuk dikembalikan ke pemanggil. DML digunakan untuk mengubah pemain dan player_ledger_entries.
Ini dipetakan ke fungsi berikut:
// 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
}
Secara default, layanan dikonfigurasi menggunakan variabel lingkungan. Lihat bagian yang relevan dari file ./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
}
Anda dapat melihat bahwa perilaku defaultnya adalah menjalankan layanan di localhost:8082.
Dengan informasi ini, saatnya menjalankan layanan.
Menjalankan layanan
Menjalankan layanan akan mendownload dependensi, dan membuat layanan berjalan di port 8082:
cd ~/spanner-gaming-sample/src/golang/item-service
go run . &
Output perintah:
[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
Uji layanan dengan mengeluarkan perintah curl untuk membuat item:
curl http://localhost:8082/items \
--include \
--header "Content-Type: application/json" \
--request "POST" \
--data '{"item_name": "test_item","item_value": "3.14"}'
Output perintah:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: <Date>
Content-Length: 38
"aecde380-0a79-48c0-ab5d-0da675d3412c"
Selanjutnya, Anda ingin pemain memperoleh item ini. Untuk melakukannya, Anda memerlukan ItemUUID dan PlayerUUID. ItemUUID adalah output dari perintah sebelumnya. Dalam contoh ini, nilainya adalah: aecde380-0a79-48c0-ab5d-0da675d3412c.
Untuk mendapatkan PlayerUUID, lakukan panggilan ke endpoint GET /players:
curl http://localhost:8082/players
Output perintah:
{
"playerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352",
"updated": "0001-01-01T00:00:00Z",
"account_balance": {},
"current_game": "7b97fa85-5658-4ded-a962-4c09269a0a79"
}
Agar pemain dapat memperoleh item, buat permintaan ke endpoint 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"}'
Output perintah:
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
}
Ringkasan
Pada langkah ini, Anda telah men-deploy layanan item yang memungkinkan pembuatan item game, dan pemain yang ditugaskan untuk membuka game dapat memperoleh uang dan item game.
Langkah Berikutnya
Pada langkah berikutnya, Anda akan men-deploy layanan tradepost.
4. Men-deploy layanan tradepost
Ringkasan layanan
Layanan tradepost adalah REST API yang ditulis dalam Go yang memanfaatkan framework gin. Dalam API ini, item pemain diposting untuk dijual. Pemain game kemudian dapat memperoleh penawaran terbuka, dan jika memiliki cukup uang, dapat membeli item tersebut.
File ./src/golang/tradepost-service/main.go untuk layanan tradepost mengikuti penyiapan dan kode yang serupa dengan layanan lainnya, sehingga tidak diulang di sini. Layanan ini mengekspos beberapa endpoint sebagai berikut:
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())
}
Layanan ini menyediakan struct TradeOrder, serta struct yang diperlukan untuk GameItem, PlayerItem, Player, dan 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"`
}
Untuk membuat pesanan perdagangan, permintaan POST dikeluarkan ke endpoint API /trades/sell. Informasi yang diperlukan adalah playerItemUUID dari item_pemain yang akan dijual, lister, dan list_price.
Mutasi Spanner dipilih untuk membuat pesanan jual beli dan menandai player_item sebagai tidak terlihat. Tindakan ini mencegah penjual memposting item duplikat untuk dijual.
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
}
Sebelum benar-benar membuat pesanan, PlayerItem divalidasi untuk memastikan item tersebut dapat dicantumkan untuk dijual. Terutama, ini berarti PlayerItem terlihat oleh pemain, dan belum berakhir.
// 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
}
Pembelian dilakukan dengan permintaan PUT ke endpoint /trades/buy. Informasi yang diperlukan adalah orderUUID dan buyer, yang merupakan UUID pemain yang melakukan pembelian.
Karena kompleksitas ini dan jumlah perubahan, mutasi dipilih lagi untuk membeli pesanan. Operasi berikut dilakukan dalam satu transaksi baca-tulis:
- Validasi bahwa pesanan dapat dipenuhi karena belum pernah dipenuhi sebelumnya dan belum habis masa berlakunya.
// 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
}
- Ambil informasi pembeli, dan validasi bahwa mereka dapat membeli item. Artinya, pembeli tidak boleh sama dengan penjual, dan mereka memiliki cukup uang.
// 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
}
- Tambahkan list_price pesanan ke saldo akun pencatat, dengan entri buku besar yang cocok.
// 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
}
- Kurangi list_price pesanan dari saldo akun pembeli, dengan entri buku besar yang cocok.
// Update buyer's account balance
negAmount := o.ListPrice.Neg(&o.ListPrice)
buyer.UpdateBalance(ctx, txn, *negAmount)
- Pindahkan player_item ke pemain baru dengan menyisipkan instance baru item game dengan detail game dan pembeli ke dalam tabel PlayerItems, dan hapus instance item pencatat.
// 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
}
- Memperbarui entri Pesanan untuk menunjukkan bahwa item telah dipenuhi dan tidak lagi aktif.
Secara keseluruhan, fungsi Buy akan terlihat seperti berikut:
// 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
}
Secara default, layanan dikonfigurasi menggunakan variabel lingkungan. Lihat bagian yang relevan dari file ./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
}
Anda dapat melihat bahwa perilaku defaultnya adalah menjalankan layanan di localhost:8083 untuk menghindari konflik dengan layanan lain*.*
Dengan informasi ini, sekarang saatnya menjalankan layanan pos perdagangan.
Menjalankan layanan
Menjalankan layanan akan membuat layanan berjalan di port 8083. Layanan ini memiliki banyak dependensi yang sama dengan item-service, sehingga dependensi baru tidak akan didownload.
cd ~/spanner-gaming-sample/src/golang/tradepost-service
go run . &
Output perintah:
[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
Memposting item
Uji layanan dengan mengirimkan permintaan GET untuk mengambil PlayerItem yang akan dijual:
curl http://localhost:8083/trades/player_items
Output perintah:
{
"PlayerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352",
"PlayerItemUUID": "a42b1899-4509-4fce-9958-265d2a2838a0",
"Price": "3.14"
}
Sekarang, mari kita posting item untuk dijual dengan memanggil endpoint /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>"}'
Output perintah:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: <Date>
Content-Length: 38
"282ea691-b956-4c4c-95ff-f461d6415651"
Ringkasan
Pada langkah ini, Anda men-deploy tradepost-service untuk menangani pembuatan pesanan jual. Layanan ini juga menangani kemampuan untuk membeli pesanan tersebut.
Langkah Berikutnya
Setelah layanan Anda berjalan, saatnya menyimulasikan pemain yang menjual dan membeli di pos perdagangan.
5. Mulai berdagang
Setelah layanan item dan pos perdagangan berjalan, Anda dapat membuat beban menggunakan generator locust yang disediakan.
Locust menawarkan antarmuka web untuk menjalankan generator, tetapi dalam lab ini Anda akan menggunakan command line (opsi –headless).
Membuat item game
Pertama, Anda harus membuat item. File ./generators/item_generator.py mencakup tugas untuk membuat item game dengan string acak untuk nama, dan nilai harga acak:
# 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)
Perintah berikut memanggil file item_generator.py yang akan membuat item game selama 10 detik (t=10s):
cd ~/spanner-gaming-sample
locust -H http://127.0.0.1:8082 -f ./generators/item_generator.py --headless -u=1 -r=1 -t=10s
Output perintah:
*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
Pemain memperoleh item dan uang
Selanjutnya, mari kita buat pemain memperoleh item dan uang agar mereka dapat berpartisipasi di pos perdagangan. Untuk melakukannya, file ./generators/game_server.py menyediakan tugas untuk mengambil item game yang akan ditetapkan kepada pemain serta jumlah mata uang acak.
# 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'")
Perintah ini akan memungkinkan pemain memperoleh item dan uang selama 60 detik:
locust -H http://127.0.0.1:8082 -f game_server.py --headless -u=1 -r=1 -t=60s
Output perintah:
*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
Pemain membeli dan menjual di pos perdagangan
Setelah memiliki item dan uang untuk membeli item, pemain dapat mulai menggunakan tempat perdagangan.
File generator ./generators/trading_server.py menyediakan tugas untuk membuat pesanan penjualan dan memenuhi pesanan tersebut.
# 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'")
Perintah ini akan memungkinkan pemain mencantumkan item yang telah mereka peroleh untuk dijual, dan pemain lain dapat membeli item tersebut selama 10 detik:
locust -H http://127.0.0.1:8083 -f ./generators/trading_server.py --headless -u=1 -r=1 -t=10s
Output perintah:
*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
Ringkasan
Pada langkah ini, Anda menyimulasikan pemain yang mendaftar untuk bermain game, lalu menjalankan simulasi agar pemain dapat bermain game menggunakan layanan matchmaking. Simulasi ini memanfaatkan framework Locust Python untuk mengirimkan permintaan ke REST API layanan kami.
Anda dapat mengubah waktu yang dihabiskan untuk membuat pemain dan bermain game, serta jumlah pengguna serentak (-u).
Langkah Berikutnya
Setelah simulasi, Anda akan ingin memeriksa berbagai statistik dengan membuat kueri Spanner.
6. Mengambil statistik perdagangan
Setelah kita menyimulasikan pemain yang mendapatkan uang dan item, lalu menjual item tersebut di pusat perdagangan, mari kita periksa beberapa statistik.
Untuk melakukannya, gunakan Konsol Cloud untuk mengirimkan permintaan kueri ke Spanner.
Memeriksa pesanan perdagangan terbuka vs. terpenuhi
Saat TradeOrder dibeli di pos perdagangan, kolom metadata filled akan diperbarui.
Kueri ini akan memungkinkan Anda memeriksa berapa banyak pesanan yang terbuka dan berapa banyak yang telah dipenuhi:
-- 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
)
Hasil:
Jenis | NumTrades |
Buka Perdagangan | 159 |
Transaksi yang Terisi | 454 |
Memeriksa saldo akun pemain dan jumlah item
Pemain sedang bermain game jika kolom current_game miliknya ditetapkan. Jika tidak, mereka tidak sedang bermain game.
Untuk melihat 10 pemain teratas yang saat ini bermain game dengan item terbanyak, dengan account_balance mereka
, gunakan kueri ini :
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;
Hasil:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Ringkasan
Pada langkah ini, Anda meninjau berbagai statistik pemain dan pesanan perdagangan menggunakan Konsol Cloud untuk membuat kueri Spanner.
Langkah Berikutnya
Selanjutnya, saatnya membersihkan!
7. Pembersihan
Setelah asyik bermain dengan Spanner, kita perlu membersihkan tempat bermain kita. Untungnya ini adalah langkah yang mudah. Cukup buka bagian Cloud Spanner dari Cloud Console dan hapus instance yang kita buat untuk codelab ini.
8. Selamat!
Selamat, Anda telah berhasil men-deploy game contoh di Spanner
Apa langkah selanjutnya?
Di lab ini, Anda telah menyelesaikan penyiapan dua layanan untuk menangani pembuatan item game dan pemain yang mendapatkan item untuk dijual di pusat jual beli.
Contoh kode ini akan memberi Anda pemahaman yang lebih baik tentang cara kerja konsistensi Cloud Spanner dalam transaksi untuk mutasi DML dan Spanner.
Anda dapat menggunakan generator yang disediakan untuk mempelajari penskalaan Spanner.