1. Introduzione
Cloud Spanner è un servizio di database relazionale completamente gestito, scalabile orizzontalmente e distribuito a livello globale che fornisce transazioni ACID e semantica SQL senza rinunciare a prestazioni e alta disponibilità.
Queste funzionalità rendono Spanner ideale per l'architettura di giochi che vogliono attivare una base di giocatori globale o sono preoccupati per la coerenza dei dati.
In questo lab, creerai due servizi Go che interagiscono con un database Spanner a livello di regione per consentire ai giocatori di acquisire oggetti e denaro (item-service) e poi elencare gli oggetti nella stazione di scambio affinché altri giocatori possano acquistarli (tradepost-service).
Questo lab dipende dal codelab Cloud Spanner Getting Started with Games Development per aver generato giocatori e partite utilizzando profile-service e matchmaking-service.
Successivamente, genererai dati sfruttando il framework di caricamento Python Locust.io per simulare l'acquisizione di denaro e oggetti da parte dei giocatori nel corso del "gameplay". I giocatori possono quindi mettere in vendita gli oggetti in un avamposto commerciale, dove altri giocatori con abbastanza denaro possono acquistarli.
Eseguirai anche query su Spanner per determinare i saldi degli account e il numero di articoli dei giocatori, nonché alcune statistiche sugli ordini di scambio aperti o completati.
Infine, ripulirai le risorse create in questo lab.
Cosa creerai
Nell'ambito di questo lab, imparerai a:
- Riutilizza l'istanza Spanner da Guida introduttiva a Cloud Spanner per lo sviluppo di giochi.
- Esegui il deployment di un servizio di elementi scritto in Go per gestire l'acquisizione di elementi e denaro da parte dei giocatori
- Implementa un servizio Trading Post scritto in Go per simulare giocatori che mettono in vendita articoli e altri giocatori che li acquistano.
Obiettivi didattici
- Come utilizzare le transazioni di lettura/scrittura per garantire la coerenza delle modifiche ai dati
- Come sfruttare le mutazioni DML e Spanner per modificare i dati
Che cosa ti serve
- Un progetto Google Cloud collegato a un account di fatturazione.
- Un browser web, ad esempio Chrome o Firefox.
- Inizia a utilizzare Cloud Spanner per lo sviluppo di giochi completato in precedenza, senza il passaggio di pulizia.
2. Configurazione e requisiti
Completa il codelab Introduzione a Cloud Spanner per lo sviluppo di giochi
Completa il codelab Cloud Spanner Getting Started with Games Development. È necessario per ottenere un set di dati di giocatori e giochi. I giocatori e le partite sono necessari per acquisire oggetti e denaro, che a loro volta vengono utilizzati per mettere in vendita oggetti e acquistarli dal mercato.
Configura le variabili di ambiente in Cloud Shell
Apri Cloud Shell facendo clic su Attiva Cloud Shell 
(bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente, dato che l'hai già fatto).
Una volta eseguita la connessione a Cloud Shell, dovresti vedere che il tuo account è già autenticato e il progetto è già impostato sul tuo PROJECT_ID.
Imposta le variabili di ambiente SPANNER in Cloud Shell
export SPANNER_PROJECT_ID=$GOOGLE_CLOUD_PROJECT
export SPANNER_INSTANCE_ID=cloudspanner-gaming
export SPANNER_DATABASE_ID=sample-game
Crea lo schema
Ora che il database è stato creato, puoi definire lo schema nel database sample-game.
Questo lab creerà quattro nuove tabelle: game_items, player_items, player_ledger_entries e trade_orders.
Relazioni tra gli elementi del giocatore
Relazioni tra ordini commerciali
Gli articoli di gioco vengono aggiunti nella tabella game_items e possono essere acquisiti dai giocatori. La tabella player_items ha chiavi esterne sia per un itemUUID che per un playerUUID per garantire che i giocatori acquisiscano solo elementi validi.
La tabella player_ledger_entries tiene traccia di eventuali modifiche monetarie al saldo dell'account del giocatore. Puoi ottenere denaro dal bottino o vendendo oggetti nel mercato.
Infine, la tabella trade_orders viene utilizzata per gestire la pubblicazione degli ordini di vendita e per consentire agli acquirenti di evaderli.
Per creare lo schema, fai clic sul pulsante Write DDL in Cloud Console:
Qui inserirai la definizione dello schema dal 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);
Fai clic sul pulsante "Submit" per modificare lo schema e attendi il completamento dell'aggiornamento dello schema:
Prossimo
Ora eseguirai il deployment del servizio articoli.
3. Esegui il deployment del servizio di articoli
Panoramica del servizio
Il servizio di elementi è un'API REST scritta in Go che sfrutta il framework Gin. In questa API, i giocatori che partecipano a partite aperte acquisiscono denaro e oggetti.
Il file ./src/golang/item-service/main.go configura i seguenti endpoint per funzionare con gli elementi di gioco e i giocatori che li acquisiscono. Inoltre, esiste un endpoint per consentire ai giocatori di acquisire denaro.
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())
}
La configurazione e l'utilizzo delle connessioni Spanner vengono gestiti esattamente come profile-service e matchmaking-service del codelab precedente.
Il servizio di articoli funziona con GameItem, Player, PlayerLedger e PlayerItem con le seguenti definizioni:
// 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"`
}
Innanzitutto, devono essere creati alcuni elementi del gioco. Per farlo, viene chiamata una richiesta POST all'endpoint /items. Si tratta di un inserimento DML molto semplice nella tabella 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
}
Per acquisire un elemento, viene chiamata una richiesta POST all'endpoint /players/items. La logica di questo endpoint consiste nel recuperare il valore corrente di un elemento di gioco e la sessione di gioco corrente del giocatore. Poi inserisci le informazioni appropriate nella tabella player_items indicando l'origine e l'ora di acquisizione dell'articolo.
Ciò corrisponde alle seguenti funzioni:
// 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
}
Affinché un giocatore possa acquisire denaro, viene chiamata una richiesta PUT all'endpoint /players/updatebalance.
La logica di questo endpoint consiste nell'aggiornare il saldo del giocatore dopo aver applicato l'importo, nonché nell'aggiornare la tabella player_ledger_entries con un record dell'acquisizione. Il valore di account_balance del giocatore viene modificato per essere restituito al chiamante. DML viene utilizzato per modificare sia i giocatori che le voci del registro dei giocatori.
Ciò corrisponde alle seguenti funzioni:
// 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
}
Per impostazione predefinita, il servizio viene configurato utilizzando le variabili di ambiente. Consulta la sezione pertinente del 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
}
Puoi notare che il comportamento predefinito consiste nell'eseguire il servizio su localhost:8082.
Con queste informazioni è il momento di eseguire il servizio.
Esegui il servizio
L'esecuzione del servizio scaricherà le dipendenze e stabilirà che il servizio viene eseguito sulla porta 8082:
cd ~/spanner-gaming-sample/src/golang/item-service
go run . &
Output comando:
[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
Testa il servizio eseguendo un comando curl per creare un elemento:
curl http://localhost:8082/items \
--include \
--header "Content-Type: application/json" \
--request "POST" \
--data '{"item_name": "test_item","item_value": "3.14"}'
Output comando:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: <Date>
Content-Length: 38
"aecde380-0a79-48c0-ab5d-0da675d3412c"
Successivamente, vuoi che un giocatore acquisisca questo oggetto. Per farlo, hai bisogno di un ItemUUID e di un PlayerUUID. ItemUUID è l'output del comando precedente. In questo esempio, è: aecde380-0a79-48c0-ab5d-0da675d3412c.
Per ottenere un PlayerUUID, effettua una chiamata all'endpoint GET /players:
curl http://localhost:8082/players
Output comando:
{
"playerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352",
"updated": "0001-01-01T00:00:00Z",
"account_balance": {},
"current_game": "7b97fa85-5658-4ded-a962-4c09269a0a79"
}
Affinché il giocatore acquisisca l'elemento, invia una richiesta all'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 comando:
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
}
Riepilogo
In questo passaggio hai eseguito il deployment del servizio di articoli che consente la creazione di articoli di gioco e l'acquisizione di denaro e articoli di gioco da parte dei giocatori assegnati a partite aperte.
Passaggi successivi
Nel passaggio successivo eseguirai il deployment del servizio tradepost.
4. Esegui il deployment del servizio tradepost
Panoramica del servizio
Il servizio tradepost è un'API REST scritta in Go che sfrutta il framework Gin. In questa API, gli articoli del giocatore vengono pubblicati per la vendita. I giocatori possono quindi ottenere scambi aperti e, se hanno abbastanza denaro, possono acquistare l'articolo.
Il file ./src/golang/tradepost-service/main.go per il servizio tradepost segue una configurazione e un codice simili a quelli degli altri servizi, pertanto non viene ripetuto qui. Questo servizio espone diversi endpoint come segue:
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())
}
Questo servizio fornisce una struttura TradeOrder, nonché le strutture richieste per GameItem, PlayerItem, Player e 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"`
}
Per creare un ordine di compravendita, viene inviata una richiesta POST all'endpoint API /trades/sell. Le informazioni richieste sono playerItemUUID di player_item da vendere, lister e list_price.
Le mutazioni di Spanner vengono scelte per creare l'ordine di scambio e contrassegnare player_item come non visibile. In questo modo, il venditore non può pubblicare articoli duplicati in vendita.
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
}
Prima di creare l'ordine, l'PlayerItem viene convalidato per assicurarsi che possa essere messo in vendita. Ciò significa principalmente che PlayerItem è visibile al player e che non è scaduto.
// 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
}
L'acquisto viene effettuato tramite una richiesta PUT all'endpoint /trades/buy. Le informazioni richieste sono orderUUID e buyer, ovvero l'UUID del giocatore che effettua l'acquisto.
A causa di questa complessità e della quantità di modifiche, le mutazioni vengono nuovamente scelte per l'acquisto dell'ordine. Le seguenti operazioni vengono eseguite in un'unica transazione di lettura/scrittura:
- Verifica che l'ordine possa essere completato perché non è stato completato in precedenza e non è scaduto.
// 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
}
- Recupera i dati dell'acquirente e verifica che possa acquistare l'articolo. Ciò significa che l'acquirente non può essere la stessa persona che ha pubblicato l'annuncio e che ha fondi sufficienti.
// 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
}
- Aggiungi il list_price dell'ordine al saldo dell'account del lister, con una voce di registro corrispondente.
// 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
}
- Sottrai il list_price dell'ordine dal saldo dell'account dell'acquirente, con una voce di registro corrispondente.
// Update buyer's account balance
negAmount := o.ListPrice.Neg(&o.ListPrice)
buyer.UpdateBalance(ctx, txn, *negAmount)
- Sposta l'elemento player nel nuovo giocatore inserendo una nuova istanza dell'elemento di gioco con i dettagli del gioco e dell'acquirente nella tabella PlayerItems e rimuovi l'istanza dell'elemento dell'inserzionista.
// 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
}
- Aggiorna la voce Ordini per indicare che l'articolo è stato compilato e non è più attivo.
Nel complesso, la funzione Acquista ha il seguente aspetto:
// 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
}
Per impostazione predefinita, il servizio viene configurato utilizzando le variabili di ambiente. Consulta la sezione pertinente del 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
}
Puoi notare che il comportamento predefinito è eseguire il servizio su localhost:8083 per evitare conflitti con altri servizi.*.*
Con queste informazioni, è ora di eseguire il servizio di scambio.
Esegui il servizio
L'esecuzione del servizio stabilirà l'esecuzione del servizio sulla porta 8083. Questo servizio ha molte delle stesse dipendenze del servizio di elementi, quindi non verranno scaricate nuove dipendenze.
cd ~/spanner-gaming-sample/src/golang/tradepost-service
go run . &
Output comando:
[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
Pubblicare un elemento
Testa il servizio inviando una richiesta GET per recuperare un PlayerItem da vendere:
curl http://localhost:8083/trades/player_items
Output comando:
{
"PlayerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352",
"PlayerItemUUID": "a42b1899-4509-4fce-9958-265d2a2838a0",
"Price": "3.14"
}
Ora, pubblichiamo un articolo in vendita chiamando l'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 comando:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: <Date>
Content-Length: 38
"282ea691-b956-4c4c-95ff-f461d6415651"
Riepilogo
In questo passaggio hai eseguito il deployment di tradepost-service per gestire la creazione di ordini di vendita. Questo servizio gestisce anche la possibilità di acquistare questi ordini.
Passaggi successivi
Ora che i tuoi servizi sono in esecuzione, è il momento di simulare la vendita e l'acquisto di giocatori nel mercato!
5. Inizia a fare trading
Ora che i servizi di articoli e avamposto commerciale sono in esecuzione, puoi generare carico utilizzando i generatori di locust forniti.
Locust offre un'interfaccia web per l'esecuzione dei generatori, ma in questo lab utilizzerai la riga di comando (opzione –headless).
Generare elementi di gioco
Innanzitutto, devi generare gli elementi. Il file ./generators/item_generator.py include un'attività per creare elementi di gioco con stringhe casuali per i nomi e valori di prezzo casuali:
# 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)
Il seguente comando chiama il file item_generator.py che genererà elementi di gioco per 10 secondi (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 comando:
*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
I giocatori acquisiscono oggetti e denaro
Poi, facciamo in modo che i giocatori acquisiscano oggetti e denaro per poter partecipare al mercato. A questo scopo, il file ./generators/game_server.py fornisce attività per recuperare gli articoli di gioco da assegnare ai giocatori, nonché importi casuali di valuta.
# 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'")
Questo comando consentirà ai giocatori di acquisire oggetti e denaro per 60 secondi:
locust -H http://127.0.0.1:8082 -f game_server.py --headless -u=1 -r=1 -t=60s
Output comando:
*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
Giocatori che acquistano e vendono nel mercato
Ora che i giocatori hanno articoli e denaro per acquistarli, possono iniziare a utilizzare il mercato.
Il file del generatore ./generators/trading_server.py fornisce attività per creare ordini di vendita ed eseguirli.
# 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'")
Questo comando consente ai giocatori di elencare gli articoli che hanno acquisito per la vendita e ad altri giocatori di acquistare questi articoli per 10 secondi:
locust -H http://127.0.0.1:8083 -f ./generators/trading_server.py --headless -u=1 -r=1 -t=10s
Output comando:
*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
Riepilogo
In questo passaggio, hai simulato la registrazione di giocatori per giocare e poi hai eseguito simulazioni per far giocare i giocatori utilizzando il servizio di matchmaking. Queste simulazioni hanno sfruttato il framework Python Locust per inviare richieste all'API REST dei nostri servizi.
Puoi modificare il tempo dedicato alla creazione di giocatori e alla riproduzione di giochi, nonché il numero di utenti simultanei (-u).
Passaggi successivi
Dopo la simulazione, ti consigliamo di controllare varie statistiche eseguendo query su Spanner.
6. Recuperare le statistiche commerciali
Ora che abbiamo simulato l'acquisizione di denaro e oggetti da parte dei giocatori e la loro vendita nel mercato, controlliamo alcune statistiche.
Per farlo, utilizza la console Cloud per inviare richieste di query a Spanner.
Controllare gli ordini di scambio aperti e completati
Quando un TradeOrder viene acquistato sul trading post, il campo dei metadati filled viene aggiornato.
Questa query ti consente di controllare quanti ordini sono aperti e quanti sono stati completati:
-- 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
)
Risultato:
Tipo | NumTrades |
Open Trades | 159 |
Scambi eseguiti | 454 |
Controllare il saldo dell'account giocatore e il numero di elementi
Un giocatore sta giocando a un gioco se la colonna current_game è impostata. In caso contrario, al momento non sta giocando.
Per visualizzare i primi 10 giocatori che attualmente giocano con il maggior numero di articoli, con il loro account_balance
, utilizza questa query :
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;
Risultato:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Riepilogo
In questo passaggio, hai esaminato varie statistiche sugli ordini di giocatori e scambi utilizzando la console Cloud per eseguire query su Spanner.
Passaggi successivi
A questo punto, è il momento di fare pulizia.
7. Pulizia
Dopo tutto il divertimento con Spanner, dobbiamo pulire il nostro parco giochi. Fortunatamente questo è un passaggio semplice: basta andare alla sezione Cloud Spanner di Cloud Console ed eliminare l'istanza che abbiamo creato per questo codelab.
8. Complimenti!
Congratulazioni, hai eseguito correttamente il deployment di un gioco di esempio su Spanner.
Passaggi successivi
In questo lab hai completato la configurazione di due servizi per gestire la generazione di articoli di gioco e l'acquisizione di articoli da parte dei giocatori da vendere nella stazione di scambio.
Questi esempi di codice dovrebbero aiutarti a comprendere meglio il funzionamento della coerenza di Cloud Spanner all'interno delle transazioni sia per DML che per le mutazioni di Spanner.
Puoi utilizzare i generatori forniti per esplorare la scalabilità di Spanner.