Application Spring Boot avec Cloud Spanner

1. Présentation

Cloud Spanner est un SGBDR multirégional hautement disponible, évolutif horizontalement et multirégional. Cet atelier de programmation utilise une plus petite instance de Cloud Spanner, mais n'oubliez pas de l'arrêter lorsque vous avez terminé.

Points abordés

• Utiliser Cloud Spanner pour enregistrer et récupérer des données avec Spring Boot

Ce dont vous avez besoin

• Un projet Google Cloud Platform
• Un navigateur tel que Chrome ou Firefox

Comment allez-vous utiliser ce tutoriel ?

Je vais le lire uniquement Je vais le lire et effectuer les exercices

Quel est votre niveau d'expérience avec les services Google Cloud Platform ?

Débutant Intermédiaire Expert

2. Préparation

Configuration de l'environnement d'auto-formation

1. Connectez-vous à Cloud Console, puis créez un projet ou réutilisez un projet existant. (Si vous n'avez pas encore de compte Gmail ou G Suite, vous devez en créer un.)

Remarque : Vous pouvez facilement accéder à Cloud Console en mémorisant son URL, à savoir console.cloud.google.com.

Mémorisez l'ID du projet. Il s'agit d'un nom unique permettant de différencier chaque projet Google Cloud (le nom ci-dessus est déjà pris ; vous devez en trouver un autre). Il sera désigné par le nom PROJECT_ID tout au long de cet atelier de programmation.

Remarque : Si vous utilisez un compte Gmail, vous pouvez conserver l'emplacement par défaut défini sur Aucune organisation. Si vous utilisez un compte G Suite, choisissez un emplacement pertinent pour votre organisation.

2. Vous devez ensuite activer la facturation dans Cloud Console pour pouvoir utiliser les ressources Google Cloud.

L'exécution de cet atelier de programmation est très peu coûteuse, voire sans frais. Veillez à suivre les instructions de la section "Nettoyer" qui indique comment désactiver les ressources afin d'éviter les frais une fois ce tutoriel terminé. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300 $.

Activer Cloud Shell

1. Dans Cloud Console, cliquez sur Activer Cloud Shell .

Si vous n'avez encore jamais démarré Cloud Shell, un écran intermédiaire s'affiche en dessous de la ligne de séparation pour décrire de quoi il s'agit. Si tel est le cas, cliquez sur Continuer (cet écran ne s'affiche qu'une seule fois). Voici à quoi il ressemble :

Le provisionnement et la connexion à Cloud Shell ne devraient pas prendre plus de quelques minutes.

Cette machine virtuelle contient tous les outils de développement nécessaires. Elle intègre un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances réseau et l'authentification. Vous pouvez réaliser une grande partie, voire la totalité, des activités de cet atelier dans un simple navigateur ou sur votre Chromebook.

Une fois connecté à Cloud Shell, vous êtes en principe authentifié et le projet est défini avec votre ID de projet.

2. Exécutez la commande suivante dans Cloud Shell pour vérifier que vous êtes authentifié :

gcloud auth list

Résultat de la commande

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Remarque : gcloud est l'outil de ligne de commande performant et unifié de Google Cloud. Il est préinstallé dans Cloud Shell. Il est également compatible avec la saisie semi-automatique via la touche de tabulation. Pour en savoir plus, consultez la section présentation de l'outil de ligne de commande gcloud.

gcloud config list project

Résultat de la commande

[core]
project = <PROJECT_ID>

Si vous obtenez un résultat différent, exécutez cette commande :

gcloud config set project <PROJECT_ID>

Résultat de la commande :

Updated property [core/project].

3. Initialiser Cloud Spanner

Activez l'API Cloud Spanner à l'aide de la gcloud CLI:

gcloud services enable spanner.googleapis.com

Créez une instance Cloud Spanner:

gcloud spanner instances create spanner-instance \
 --config=regional-us-central1 \
 --nodes=1 --description="A Spanner Instance"

Créez une base de données dans l'instance:

gcloud spanner databases create orders \
  --instance=spanner-instance

Créez un fichier schema.ddl pour décrire le schéma de données:

cat << EOF > schema.ddl
CREATE TABLE orders (
  order_id STRING(36) NOT NULL,
  description STRING(255),
  creation_timestamp TIMESTAMP,
) PRIMARY KEY (order_id);

CREATE TABLE order_items (
  order_id STRING(36) NOT NULL,
  order_item_id STRING(36) NOT NULL,
  description STRING(255),
  quantity INT64,
) PRIMARY KEY (order_id, order_item_id),
  INTERLEAVE IN PARENT orders ON DELETE CASCADE;
EOF

Appliquez le schéma à la base de données Cloud Spanner:

gcloud spanner databases ddl update orders \
  --instance=spanner-instance \
  --ddl="$(<schema.ddl)"

4. Amorcer une nouvelle application Java Spring Boot

Dans l'environnement Cloud Shell, utilisez la commande suivante pour initialiser et amorcer une nouvelle application Spring Boot:

$ curl https://start.spring.io/starter.tgz \
  -d packaging=jar \
  -d dependencies=cloud-gcp,web,lombok \
  -d baseDir=spanner-example \
  -d type=maven-project \
  -d bootVersion=3.2.6 | tar -xzvf -

$ cd spanner-example

Cette opération crée un répertoire spanner-example/ avec un nouveau projet Maven, ainsi que le pom.xml de Maven, un wrapper Maven et un point d'entrée d'application.

Dans le fichier pom.xml, ajoutez le déclencheur Spring Data Cloud Spanner.

spanner-example/pom.xml

<project>
  ...
  <dependencies>
        ...
        <!-- Add Spring Cloud GCP Spanner Starter -->
        <dependency>
                <groupId>com.google.cloud</groupId>
                <artifactId>spring-cloud-gcp-starter-data-spanner</artifactId>
        </dependency>

        ...

  </dependencies>

  ...
</project>

Dans application.properties, configurez les informations de connexion à la base de données Spanner:

spanner-example/src/main/resources/application.properties

spring.cloud.gcp.spanner.instance-id=spanner-instance
spring.cloud.gcp.spanner.database=orders

Assurez-vous que JAVA_HOME est défini sur la bonne version:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64/

Recompilez l'application pour vous assurer que votre configuration Maven est correcte:

./mvnw package

5. Créer les entités

Grâce à la compatibilité de Spring Cloud GCP avec Spring Data Spanner, vous pouvez facilement créer un objet Java et un mappage ORM idiomatique sur une table Spanner à l'aide de Spring Data.

Commencez par créer une classe Order Item.

spanner-example/src/main/java/com/example/demo/OrderItem.java

package com.example.demo;

import com.google.cloud.spring.data.spanner.core.mapping.Column;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;

@Table(name="order_items")
@Data
class OrderItem {
  @PrimaryKey(keyOrder = 1)
  @Column(name="order_id")
  private String orderId;

  @PrimaryKey(keyOrder = 2)
  @Column(name="order_item_id")
  private String orderItemId;

  private String description;
  private Long quantity;
}

Pour les relations parent/enfant dans Spanner, vous devez utiliser une clé primaire composite. Dans cet exemple, la clé composite est order_id et order_item_id.

Ensuite, créez une classe Order:

spanner-example/src/main/java/com/example/demo/Order.java

package com.example.demo;

import java.time.LocalDateTime;
import java.util.List;
import lombok.Data;
import com.google.cloud.spring.data.spanner.core.mapping.Column;
import com.google.cloud.spring.data.spanner.core.mapping.Interleaved;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;

@Table(name="orders")
@Data
public class Order {
  @PrimaryKey
  @Column(name="order_id")
  private String id;

  private String description;

  @Column(name="creation_timestamp")
  private LocalDateTime timestamp;

  @Interleaved
  private List<OrderItem> items;
}

Cette classe utilise l'annotation @Interleaved pour créer une relation de type un à plusieurs avec les articles commandés.

6. Créer l'interface OrderRepository

Créez la classe OrderRepository avec le contenu suivant:

spanner-example/src/main/java/com/example/demo/OrderRepository.java

package com.example.demo;

import com.google.cloud.spring.data.spanner.repository.SpannerRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface OrderRepository extends SpannerRepository<Order, String> {
}

L'interface étend SpannerRepository<Order, String>, où Order correspond à la classe de domaine et String au type de clé primaire. Spring Data fournira automatiquement un accès CRUD via cette interface et vous n'aurez pas besoin de créer de code supplémentaire.

7. Créer un contrôleur REST pour les opérations de base

Ouvrez la classe DemoApplication de l'application principale et modifiez-la comme suit:

spanner-example/src/main/java/com/example/demo/DemoApplication.java

package com.example.demo;

import java.time.LocalDateTime;
import java.util.UUID;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.server.ResponseStatusException;

@SpringBootApplication
public class DemoApplication {
        public static void main(String[] args) {
                SpringApplication.run(DemoApplication.class, args);
        }
}

@RestController
class OrderController {
  private final OrderRepository orderRepository;

        OrderController(OrderRepository orderRepository) {
                this.orderRepository = orderRepository;
        }

        @GetMapping("/api/orders/{id}")
        public Order getOrder(@PathVariable String id) {
          return orderRepository.findById(id)
                                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, id + " not found"));
        }

        @PostMapping("/api/orders")
        public String createOrder(@RequestBody Order order) {
                // Spanner currently does not auto generate IDs
                // Generate UUID on new orders
                order.setId(UUID.randomUUID().toString());
                order.setTimestamp(LocalDateTime.now());

                order.getItems().forEach(item -> {
                        // Assign parent ID, and also generate child ID
                        item.setOrderId(order.getId());
                        item.setOrderItemId(UUID.randomUUID().toString());
                });

          Order saved = orderRepository.save(order);
          return saved.getId();
        }
}

8. Exécuter l'application

Recompilez et exécutez l'application.

./mvnw spring-boot:run

Celui-ci devrait démarrer correctement et écouter sur le port 8080.

Vous pouvez publier un enregistrement de commande sur le point de terminaison:

curl -H"Content-Type: application/json" -d'{"description": "My orders", "items": [{"description": "Android Phone", "quantity": "1"}]}' \
  http://localhost:8080/api/orders

Il doit répondre avec le code UUID de la commande.

Vous pouvez ensuite récupérer la commande avec le UUID:

curl http://localhost:8080/api/orders/REPLACE_WITH_ORDER_UUID

Pour savoir comment les données sont stockées dans Cloud Spanner, accédez à la console Cloud, puis à Spanner → Instance Spanner → Base de données des commandes → Table des commandes → Données.

9. Effectuer un nettoyage

Pour effectuer un nettoyage, supprimez l'instance Spanner afin qu'elle ne génère plus de frais.

gcloud spanner instances delete spanner-instance -q

10. Félicitations !

Dans cet atelier de programmation, vous avez créé une application CLI interactive capable de stocker et de récupérer des données de Cloud Spanner.

En savoir plus

• Cloud Spanner: https://cloud.google.com/spanner/
• Projet Spring sur GCP: https://googlecloudplatform.github.io/spring-cloud-gcp/reference/html/
• Dépôt GitHub Spring sur GCP: https://github.com/spring-cloud/spring-cloud-gcp
• Java sur Google Cloud Platform: https://cloud.google.com/java/

Licence

Ce document est publié sous une licence Creative Commons Attribution 2.0 Generic.