Le module Spring Data Spanner vous aide à utiliser Spanner dans n'importe quelle application Java conçue avec le framework Spring.
Comme tous les modules Spring Data, Spring Data Spanner fournit un modèle de programmation basé sur Spring qui conserve les garanties de cohérence et l'évolutivité de Spanner. Ses fonctionnalités sont semblables à Spring Data JPA et Hibernate ORM, avec des annotations conçues pour Spanner. Pour en savoir plus sur l'utilisation de Spring Data JPA avec Spanner, consultez Intégrer Spanner à Spring Data JPA (dialecte GoogleSQL).
Si vous connaissez déjà Spring, Spring Data Spanner peut faciliter l'utilisation de Spanner dans votre application et réduire la quantité de code à écrire.
Cette page explique comment ajouter Spring Data Spanner à une application Java. Pour en savoir plus sur le module, consultez la référence Spring Data Spanner.
Installer le module
Si vous utilisez Maven, ajoutez la nomenclature Spring Cloud GCP (BOM) et Spring Data Spanner à votre fichier pom.xml. Ces dépendances fournissent les composants Spring Data Spanner à votre ApplicationContext Spring :
Vous devez également créer un compte de service et utiliser la clé de compte de service pour vous authentifier avec Google Cloud.
Pour plus d'informations, consultez les instructions sur la configuration d'un environnement de développement Java. Vous n'avez pas besoin d'installer la bibliothèque cliente Google Cloud pour Java. Le starter Spring Boot installe automatiquement la bibliothèque cliente.
Configurer le module
Cette section décrit certains des paramètres de configuration les plus couramment utilisés pour Spring Data Spanner. Pour obtenir la liste complète des paramètres, consultez la documentation de référence.
Spécifier une instance et une base de données
Pour spécifier l'instance et la base de données par défaut, définissez les propriétés de configuration suivantes pour votre application :
| Valeur | Description |
|---|---|
spring.cloud.gcp.spanner.project-id |
Facultatif. ID du projet Google Cloud . Remplace la valeur de spring.cloud.gcp.config.project-id. |
spring.cloud.gcp.spanner.instance-id |
ID de l'instance Spanner. |
spring.cloud.gcp.spanner.database |
Base de données à laquelle se connecter. |
Modéliser les données Spanner
Avec Spring Data Spanner, vous pouvez utiliser des objets Java simples (POJO) pour modéliser les données que vous stockez dans vos tables Spanner.
Pour chaque table de votre base de données, déclarez une entité qui représente un enregistrement dans cette table. Utilisez des annotations pour mapper l'entité et ses propriétés sur une table et ses colonnes.
Vous pouvez utiliser les annotations suivantes pour modéliser des relations simples entre des entités et des tables :
| Annotations d'entités | |
|---|---|
@Column(name = "columnName")
|
Facultatif. Mappe la propriété à une colonne spécifique de la table Spanner, en remplaçant la stratégie de dénomination qui mappe automatiquement les noms.
Lorsque vous omettez cette propriété, la stratégie de dénomination par défaut pour Spring Data Spanner mappe les noms de propriétés Java |
@Embedded |
Indique que la propriété est un objet encapsulé pouvant contenir les composants d'une clé primaire. Si la propriété est réellement utilisée dans la clé primaire, vous devez également inclure l'annotation |
|
|
Indique qu'une propriété contient une liste de lignes entrelacées dans la ligne actuelle.
Par défaut, Spring Data Spanner récupère les lignes imbriquées lors de la création de l'instance. Pour récupérer les lignes tardivement, lorsque vous accédez à la propriété, utilisez
Exemple : Si une entité |
@NotMapped |
Indique qu'une propriété n'est pas stockée dans la base de données et doit être ignorée. |
|
|
Indique que la propriété est un composant de la clé primaire et identifie la position de la propriété dans la clé primaire, en partant de 1. La valeur Exemple : |
@Table(name = "TABLE_NAME") |
La table que modélise l'entité. Chaque instance de l'entité représente un enregistrement dans la table. Remplacez
Exemple : |
Si vous devez modéliser des relations plus complexes, consultez la documentation de référence Spring Data Spanner pour en savoir plus sur les autres annotations compatibles avec le module.
Les exemples suivants montrent une façon de modéliser les tables Singers et Albums pour Spring Data Spanner :
- Pour les entités
Singer, l'exemple inclut une propriétéalbums, avec une annotation@Interleaved. Cette propriété contient une liste d'albums entrelacés avec l'entitéSinger. Spring Data Spanner remplit automatiquement cette propriété. - Pour les entités
Album, l'exemple inclut une propriétérelatedAlbumsqui n'est pas stockée dans Spanner.
Interroger et modifier des données
Pour interroger et modifier des données avec Spring Data Spanner, vous pouvez acquérir un bean SpannerTemplate, qui implémente SpannerOperations. SpannerTemplate fournit des méthodes permettant d'effectuer des requêtes SQL et de modifier des données à l'aide d'instructions LMD (langage de manipulation de données). Vous pouvez également utiliser ce bean pour accéder à l'API de lecture et à l'API de mutation pour Spanner.
De plus, vous pouvez étendre l'interface SpannerRepository pour encapsuler toute la logique d'application qui interroge et modifie les données dans Spanner.
Les sections suivantes expliquent comment utiliser SpannerTemplate et SpannerRepository.
Acquérir un bean de modèle
Utilisez l'annotation @Autowired pour acquérir automatiquement un bean SpannerTemplate. Vous pouvez ensuite utiliser SpannerTemplate dans votre classe.
L'exemple suivant illustre l'acquisition et l'utilisation du bean dans une classe :
Le bean SpannerTemplate permet d'exécuter des transactions en lecture seule et des transactions en lecture/écriture. En outre, l'annotation @Transactional permet de créer des transactions déclaratives.
Acquérir un bean de dépôt
Si vous utilisez un SpannerRepository, vous pouvez vous servir de l'annotation @Autowired pour acquérir un bean qui met en œuvre l'interface de votre dépôt. Un dépôt inclut des méthodes permettant d'exécuter des fonctions Java en tant que transactions en lecture seule et transactions en lecture/écriture. Pour les opérations de niveau inférieur, vous pouvez obtenir le modèle de bean utilisé par le dépôt.
Les exemples suivants montrent l'interface d'un dépôt, ainsi que l'acquisition et l'utilisation du bean dans une classe :
Gérer Spanner
Pour obtenir des informations sur vos bases de données Spanner, mettre à jour un schéma avec une instruction du langage de définition de données (LDD) ou effectuer d'autres tâches administratives, vous pouvez acquérir un bean SpannerDatabaseAdminTemplate.
Utilisez l'annotation @Autowired pour acquérir automatiquement le bean. Vous pouvez ensuite utiliser SpannerDatabaseAdminTemplate dans votre classe.
L'exemple suivant illustre l'acquisition et l'utilisation du bean dans une classe :
Étapes suivantes
- Commencez à utiliser Spring Cloud GCP.
- En savoir plus sur l'utilisation de Spring Data Spanner dans vos applications
- Ouvrez une demande sur GitHub pour signaler un bug ou poser une question sur le module.
- En savoir plus sur la compatibilité du framework Spring sur Google Cloud
- Participez à un atelier de programmation sur le déploiement et l'exécution d'une application utilisant Spring Cloud GCP.