1. Introduction
Cloud Spanner est un service de base de données relationnelle entièrement géré, évolutif horizontalement et distribué à l'échelle mondiale. Il fournit des transactions ACID et une sémantique SQL sans faire de compromis sur les performances et la haute disponibilité.
Grâce à ces fonctionnalités, Spanner est parfaitement adapté à l'architecture des jeux qui souhaitent toucher une base de joueurs mondiale ou qui sont soucieux de la cohérence des données.
Dans cet atelier, vous allez créer deux services Go qui interagissent avec une base de données Spanner régionale pour permettre aux joueurs d'acquérir des objets et de l'argent (item-service), puis de lister les objets du comptoir pour que d'autres joueurs puissent les acheter (tradepost-service).
Cet atelier dépend de l'atelier de programmation Premiers pas avec le développement de jeux Cloud Spanner, qui permet de générer des joueurs et des jeux à l'aide de profile-service et de matchmaking-service.
Vous allez ensuite générer des données à l'aide du framework de chargement Python Locust.io afin de simuler l'acquisition d'argent et d'objets par les joueurs au cours d'une partie. Les joueurs peuvent ensuite lister les objets à vendre dans un post, où d'autres joueurs disposant d'une somme d'argent suffisante peuvent les acheter.
Vous interrogerez aussi Spanner pour déterminer les soldes des comptes et le nombre d'articles, ainsi que des statistiques sur les commandes en cours ou honorées.
Enfin, vous allez nettoyer les ressources que vous avez créées dans cet atelier.
Ce que vous allez faire
Au cours de cet atelier, vous allez:
- Réutilisez l'instance Spanner du guide Premiers pas avec le développement de jeux de Cloud Spanner.
- Déployez un service d'articles écrit en Go pour gérer l'acquisition d'articles et d'argent par les joueurs
- Déployez un service de Trading Post écrit en Go pour simuler la liste des articles proposés par des joueurs, et d'autres joueurs qui achètent ces articles.
Points abordés
- Utiliser les transactions en lecture/écriture pour assurer la cohérence des modifications de données
- Comment exploiter les mutations LMD et Spanner pour modifier des données
Prérequis
- Un projet Google Cloud associé à un compte de facturation
- Un navigateur (Chrome ou Firefox, par exemple).
- Vous avez déjà suivi le cours Premiers pas avec le développement de jeux avec Cloud Spanner, sans étape de nettoyage.
2. Préparation
Terminer l'atelier de programmation "Premiers pas avec le développement de jeux" de Cloud Spanner
Vous avez suivi l'atelier de programmation Premiers pas avec le développement de jeux avec Cloud Spanner. Cette opération est nécessaire pour obtenir un ensemble de données sur les joueurs et les jeux. Les joueurs et les jeux sont nécessaires pour acquérir des objets et de l'argent, qui sont ensuite utilisés pour lister les objets à vendre et acheter des objets au comptoir.
Configurer des variables d'environnement dans Cloud Shell
Ouvrez Cloud Shell en cliquant sur Activer Cloud Shell 
(le provisionnement et la connexion à l'environnement ne devraient prendre que quelques instants, puisque vous avez effectué cette opération précédemment).
Une fois connecté à Cloud Shell, vous êtes en principe authentifié, et le projet est déjà défini sur votre ID_PROJET.
Définir les variables d'environnement SPANNER dans Cloud Shell
export SPANNER_PROJECT_ID=$GOOGLE_CLOUD_PROJECT
export SPANNER_INSTANCE_ID=cloudspanner-gaming
export SPANNER_DATABASE_ID=sample-game
Créer le schéma
Maintenant que votre base de données est créée, vous pouvez définir le schéma dans la base de données sample-game.
Dans cet atelier, vous allez créer quatre tables: game_items, player_items, player_ledger_entries et trade_orders.
Relations entre les éléments du lecteur
Relations entre les commandes
Les éléments de jeu sont ajoutés dans la table game_items, puis peuvent être obtenus par les joueurs. La table player_items contient des clés étrangères pour un UUID d'élément et un UUID afin de s'assurer que les joueurs n'acquièrent que des éléments valides.
Le tableau player_ledger_entries permet de suivre les variations monétaires du solde du compte du joueur. Il peut s'agir d'acquérir de l'argent grâce au butin ou de vendre des objets au comptoir.
Enfin, la table trade_orders permet de gérer l'intégration des commandes de vente et de permettre aux acheteurs de les traiter.
Pour créer le schéma, cliquez sur le bouton Write DDL dans la console Cloud:
Ici, vous allez saisir la définition du schéma à partir du fichier 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);
Cliquez sur le bouton "Submit". pour modifier le schéma, puis attendez la fin de la mise à jour:
Étape suivante
Vous allez maintenant déployer le service des articles.
3. Déployer le service d'articles
Présentation générale du service
Le service d'articles est une API REST écrite en Go qui exploite le framework gin. Dans cette API, les joueurs qui participent à des jeux ouverts obtiennent de l'argent et des objets.
Le fichier ./src/golang/item-service/main.go configure les points de terminaison suivants afin qu'ils fonctionnent avec les éléments du jeu et les joueurs qui acquièrent ces objets. Par ailleurs, un point de terminaison permet aux joueurs d'acquérir de l'argent.
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 configuration et l'utilisation des connexions Spanner sont gérées exactement comme le service profile-service et le service de mise en correspondance de l'atelier de programmation précédent.
Le service d'éléments fonctionne avec GameItem, Player, PlayerLedger et PlayerItem avec les définitions suivantes:
// 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"`
}
Tout d'abord, vous devez créer des éléments dans le jeu. Pour ce faire, une requête POST est envoyée au point de terminaison /items. Il s'agit d'une insertion LMD très simple dans la table 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
}
Pour acquérir un élément, une requête POST est appelée sur le point de terminaison /players/items. La logique de ce point de terminaison consiste à récupérer la valeur actuelle d'un élément de jeu, ainsi que la session de jeu en cours du joueur. Insérez ensuite les informations appropriées dans la table player_items, en indiquant la source et l'heure d'acquisition de l'élément.
Cela correspond aux fonctions suivantes:
// 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
}
Pour qu'un joueur acquière de l'argent, une requête PUT est appelée sur le point de terminaison /players/updatebalance.
La logique de ce point de terminaison consiste à mettre à jour le solde du joueur après avoir appliqué le amount et à mettre à jour la table player_ledger_entries avec un enregistrement des acquisitions. Le paramètre "account_balance" du joueur est modifié afin d'être renvoyé à l'appelant. Le LMD permet de modifier les paramètres "players" et "player_ledger_entries".
Cela correspond aux fonctions suivantes:
// 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
}
Par défaut, le service est configuré à l'aide de variables d'environnement. Consultez la section appropriée dans le fichier ./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
}
Vous pouvez constater que le comportement par défaut consiste à exécuter le service sur localhost:8082.
Avec ces informations, il est temps d'exécuter le service.
Exécuter le service
L'exécution du service entraîne le téléchargement des dépendances et l'établissement du service sur le port 8082:
cd ~/spanner-gaming-sample/src/golang/item-service
go run . &
Résultat de la commande :
[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
Testez le service en émettant une commande curl pour créer un élément:
curl http://localhost:8082/items \
--include \
--header "Content-Type: application/json" \
--request "POST" \
--data '{"item_name": "test_item","item_value": "3.14"}'
Résultat de la commande :
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: <Date>
Content-Length: 38
"aecde380-0a79-48c0-ab5d-0da675d3412c"
Vous souhaitez ensuite qu'un joueur acquière cet objet. Pour ce faire, vous avez besoin des éléments ItemUUID et PlayerUUID. ItemUUID est le résultat de la commande précédente. Dans cet exemple, il s'agit de aecde380-0a79-48c0-ab5d-0da675d3412c.
Pour obtenir un PlayerUUID, appelez le point de terminaison GET /players:
curl http://localhost:8082/players
Résultat de la commande :
{
"playerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352",
"updated": "0001-01-01T00:00:00Z",
"account_balance": {},
"current_game": "7b97fa85-5658-4ded-a962-4c09269a0a79"
}
Pour que le joueur acquière l'élément, envoyez une requête au point de terminaison 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"}'
Résultat de la commande :
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
}
Résumé
Au cours de cette étape, vous avez déployé le service des éléments qui permet de créer des objets dans le jeu. Vous avez ainsi pu acquérir de l'argent et des objets dans le jeu pour les joueurs associés à des jeux ouverts.
Étapes suivantes
À l'étape suivante, vous allez déployer le service TradePost.
4. Déployer le service Tradepost
Présentation générale du service
Le service Tradepost est une API REST écrite en Go qui exploite le framework gin. Dans cette API, les articles du joueur sont publiés sur la page vendre. Les joueurs peuvent alors obtenir des échanges et, s'ils ont suffisamment d'argent, peuvent acheter l'article.
Le fichier ./src/golang/tradepost-service/main.go du service Tradepost suit une configuration et un code semblables à ceux des autres services. Il n'est donc pas répété ici. Ce service expose plusieurs points de terminaison comme suit:
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())
}
Ce service fournit une structure TradeOrder, ainsi que les structures requises pour les structures GameItem, PlayerItem, Player et 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"`
}
Pour créer une commande, une requête POST est envoyée au point de terminaison de l'API /trades/sell. Les informations requises sont les éléments playerItemUUID de l'élément player à vendre, lister et list_price.
Les mutations Spanner sont choisies pour créer la commande et marquer l'élément player_item comme non visible. Cela empêche le vendeur de mettre en vente des articles en double.
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
}
Avant la création effective de la commande, l'élément PlayerItem est validé pour vérifier qu'il peut être mis en vente. Cela signifie principalement que l'élément PlayerItem est visible par le joueur et qu'il n'a pas expiré.
// 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
}
Un achat est effectué par une requête PUT au point de terminaison /trades/buy. Les informations requises sont l'UUID de commande (orderUUID) et l'acheteur (UUID), qui correspond à l'UUID du joueur effectuant l'achat.
En raison de cette complexité et du nombre de modifications, des mutations sont à nouveau choisies pour acheter la commande. Les opérations suivantes sont effectuées en une seule transaction en lecture/écriture:
- Vérifier que la commande peut être honorée, car elle n'a pas déjà été honorée et n'a pas expiré.
// 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
}
- Récupérez les informations de l'acheteur et confirmez qu'il peut acheter l'article. Cela signifie que l'acheteur ne peut pas être identique à l'utilisateur et qu'il dispose de suffisamment d'argent.
// 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
}
- Ajoutez le prix list_price de la commande au solde du compte lister's, avec une entrée de registre correspondante.
// 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
}
- Retirez la valeur list_price de la commande du solde du compte acheteur, en lui attribuant une entrée de registre correspondante.
// Update buyer's account balance
negAmount := o.ListPrice.Neg(&o.ListPrice)
buyer.UpdateBalance(ctx, txn, *negAmount)
- Déplacez "player_item" vers le nouveau joueur en insérant une nouvelle instance de l'élément de jeu avec les informations sur le jeu et l'acheteur dans la table PlayerItems, puis en supprimant l'instance lister de l'élément.
// 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
}
- Met à jour l'entrée Orders (Commandes) pour indiquer que l'article a été livré et qu'il n'est plus actif.
La fonction Buy se présente comme suit:
// 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
}
Par défaut, le service est configuré à l'aide de variables d'environnement. Consultez la section appropriée dans le fichier ./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
}
Vous pouvez constater que le comportement par défaut consiste à exécuter le service sur localhost:8083 pour éviter les conflits avec d'autres services*.*
Avec ces informations, il est maintenant temps d'exécuter le service TradePost.
Exécuter le service
L'exécution du service permet d'établir le service qui s'exécute sur le port 8083. Ce service possède un grand nombre des mêmes dépendances que le service item-service. Les nouvelles dépendances ne seront donc pas téléchargées.
cd ~/spanner-gaming-sample/src/golang/tradepost-service
go run . &
Résultat de la commande :
[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
Publier un élément
Testez le service en émettant une requête GET pour récupérer un élément PlayerItem à vendre:
curl http://localhost:8083/trades/player_items
Résultat de la commande :
{
"PlayerUUID": "b74cc194-87b0-4a55-a67f-0f0742ef6352",
"PlayerItemUUID": "a42b1899-4509-4fce-9958-265d2a2838a0",
"Price": "3.14"
}
Nous allons maintenant publier un article en vente en appelant le point de terminaison /trades/sel
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>"}'
Résultat de la commande :
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: <Date>
Content-Length: 38
"282ea691-b956-4c4c-95ff-f461d6415651"
Résumé
Au cours de cette étape, vous avez déployé le tradepost-service pour gérer la création des ordres de vente. Ce service gère également la possibilité d'acheter ces commandes.
Étapes suivantes
Maintenant que vos services sont opérationnels, il est temps de simuler les ventes et les achats de joueurs au comptoir.
5. Commencer l'échange
Maintenant que les services item et tradepost sont en cours d'exécution, vous pouvez générer une charge à l'aide des générateurs de sauteilles fournis.
Locust propose une interface Web pour exécuter les générateurs, mais dans cet atelier, vous utiliserez la ligne de commande (option –headless).
Générer des éléments de jeu
Tout d'abord, vous devez générer des éléments. Le fichier ./generators/item_generator.py inclut une tâche permettant de créer des éléments de jeu avec des chaînes aléatoires pour les noms et des valeurs de prix aléatoires:
# 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)
La commande suivante appelle le fichier item_generator.py, qui génère des éléments de jeu pendant 10 secondes (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
Résultat de la commande :
*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
Les joueurs acquièrent des objets et de l'argent
Maintenant, faisons en sorte que les joueurs acquièrent des objets et de l'argent pour pouvoir participer au comptoir. Pour ce faire, le fichier ./generators/game_server.py fournit des tâches permettant de récupérer des éléments de jeu à attribuer aux joueurs, ainsi que des quantités aléatoires de monnaie.
# 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'")
La commande suivante permet aux joueurs d'acquérir des objets et de l'argent pendant 60 secondes:
locust -H http://127.0.0.1:8082 -f game_server.py --headless -u=1 -r=1 -t=60s
Résultat de la commande :
*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
Joueurs effectuant des achats et des ventes au comptoir
Maintenant que les joueurs ont des objets et l'argent nécessaire pour les acheter, ils peuvent commencer à utiliser le comptoir d'échange.
Le fichier de générateur ./generators/trading_server.py fournit des tâches permettant de créer des commandes de vente et de les traiter.
# 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'")
La commande suivante permet aux joueurs de lister les articles qu'ils ont achetés, et aux autres joueurs d'acheter ces articles pendant 10 secondes:
locust -H http://127.0.0.1:8083 -f ./generators/trading_server.py --headless -u=1 -r=1 -t=10s
Résultat de la commande :
*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
Résumé
Au cours de cette étape, vous avez simulé l'inscription de joueurs pour jouer, puis vous avez exécuté des simulations pour que les joueurs jouent à l'aide du service de mise en correspondance. Ces simulations utilisaient le framework Python Locust pour envoyer des requêtes aux ressources API REST.
N'hésitez pas à modifier le temps passé à créer des joueurs et à jouer, ainsi que le nombre d'utilisateurs simultanés (-u).
Étapes suivantes
Après la simulation, vous devrez vérifier différentes statistiques en interrogeant Spanner.
6. Récupérer des statistiques de transactions
Maintenant que nous avons simulé l'acquisition d'argent et d'objets par les joueurs, puis que nous les vendons au comptoir, examinons quelques statistiques.
Pour ce faire, envoyez des requêtes de requête à Spanner à l'aide de la console Cloud.
Comparer les commandes en cours et traitées
Lorsqu'un article TradeOrder est acheté au bureau d'échange, le champ de métadonnées TradeOrder est mis à jour.
Cette requête vous permettra de vérifier le nombre de commandes en cours et traitées:
-- 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
)
Résultat:
Type | NumTrades |
Négociations ouvertes | 159 |
Transactions remplies | 454 |
Vérification du solde du compte de joueur et du nombre d'éléments...
Un joueur joue à un jeu si sa colonne current_game est définie. Dans le cas contraire, il n'est pas en train de jouer à un jeu.
Pour accéder aux 10 joueurs qui jouent actuellement au jeu avec le plus d'articles, avec leur account_balance
,,utilisez la requête suivante :
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;
Résultat:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Résumé
Au cours de cette étape, vous avez examiné différentes statistiques sur les commandes de joueurs et d'opérations en utilisant la console Cloud pour interroger Spanner.
Étapes suivantes
Il est maintenant temps de faire le ménage !
7. Nettoyer
Après tout ce temps passé avec Spanner, nous devons nettoyer notre terrain de jeu. Heureusement, cette étape est simple. Il vous suffit d'accéder à la section Cloud Spanner de la console Cloud et de supprimer l'instance que nous avons créée pour cet atelier de programmation.
8. Félicitations !
Félicitations, vous avez déployé un exemple de jeu sur Spanner
Étape suivante
Dans cet atelier, vous avez configuré deux services pour gérer la génération d'objets de jeu et l'acquisition par les joueurs d'objets à vendre au comptoir.
Ces exemples de code devraient vous permettre de mieux comprendre le fonctionnement de la cohérence de Cloud Spanner dans les transactions pour les mutations LMD et Spanner.
N'hésitez pas à utiliser les générateurs fournis pour découvrir le scaling de Spanner.