Migrer depuis App Engine Datastore vers Firestore en mode Datastore

Ce guide explique comment migrer depuis App Engine Datastore vers Firestore en mode Datastore (également appelé Datastore).

Firestore en mode Datastore est semblable à App Engine Datastore, car ils font tous deux référence au même service Datastore sous-jacent. Bien qu'App Engine Datastore soit accessible uniquement via les anciens services groupés App Engine, Firestore en mode Datastore est un produit Google Cloud autonome, accessible via les bibliothèques clientes Cloud.

Firestore en mode Datastore propose également un niveau gratuit qui vous permet de gérer une base de données de documents NoSQL hautement évolutive et vous offre la possibilité de migrer vers Cloud Run ou une autre plate-forme d'hébergement d'applications Google Cloud.

Avant de commencer

Consultez les différents modes de base de données Firestore pour vous assurer de comprendre le meilleur cas d'utilisation pour votre application. Notez que ce guide explique comment migrer vers le mode Datastore.
Examinez et comprenez les tarifs et les quotas de Firestore en mode Datastore.

Firestore en mode Datastore inclut une utilisation gratuite avec des limites quotidiennes, et des opérations de stockage, de lecture et d'écriture illimitées pour les comptes payants. Les applications App Engine étant désactivées, elles ne reçoivent aucun trafic et ne génèrent aucuns frais. Toutefois, l'utilisation de Datastore peut être facturable si elle dépasse les limites de quota gratuites.
Activez les API suivantes dans le projet contenant votre application :
- API Artifact Registry pour stocker et gérer vos artefacts de compilation.
- API Cloud Build pour créer, tester et déployer votre application en continu.
- API Cloud Datastore pour migrer depuis les services groupés App Engine Datastore vers Firestore en mode Datastore.
  
  Activer les API
Vous devez disposer d'une application App Engine existante exécutant Java 8 ou 11 et connectée au service App Engine Datastore.

Présentation du processus

De manière générale, le processus de migration vers Firestore en mode Datastore à partir d'App Engine Datastore comprend les étapes suivantes :

Mettre à jour les fichiers de configuration
Mettre à jour votre application Java
Valider votre transaction
Résultats de la requête

Mettre à jour les fichiers de configuration

Mettre à jour vos fichiers de configuration pour utiliser les bibliothèques clientes en mode Datastore

Mettez à jour le fichier pom.xml de votre application de référence Java :

Supprimez les importations appengine-api-1.0-sdk du SDK App Engine, comme suit :

<dependency>
  <groupId>com.google.appengine</groupId>
  <artifactId>appengine-api-1.0-sdk</artifactId>
  <version>2.0.4</version>
</dependency>

Ajoutez le client Datastore, comme suit :

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-datastore</artifactId>
  <!-- Use latest version -->
  <version>2.2.9</version>
</dependency>

Mettre à jour votre application Java

Mettre à jour les instructions d'importation

Modifiez les fichiers de votre application en mettant à jour les lignes d'importation et d'initialisation :

Supprimez les instructions d'importation App Engine suivantes pour App Engine Datastore com.google.appengine.api.datastore.* :

  import com.google.appengine.api.datastore.DatastoreService;
  import com.google.appengine.api.datastore.DatastoreServiceFactory;
  import com.google.appengine.api.datastore.Entity;
  import com.google.appengine.api.datastore.FetchOptions;
  import com.google.appengine.api.datastore.Query;

Ajoutez les importations com.google.cloud.datastore.* suivantes de Firestore en mode Datastore :

  import com.google.cloud.Timestamp;
  import com.google.cloud.datastore.Datastore;
  import com.google.cloud.datastore.DatastoreOptions;
  import com.google.cloud.datastore.Entity;
  import com.google.cloud.datastore.Key;
  import com.google.cloud.datastore.FullEntity;
  import com.google.cloud.datastore.KeyFactory;
  import com.google.cloud.datastore.Query;
  import com.google.cloud.datastore.QueryResults;
  import com.google.cloud.datastore.StructuredQuery;

Modifier l'accès de votre application au service Datastore

Firestore en mode Datastore utilise la classe Datastore au lieu de DatastoreService. Pour modifier l'accès de votre application au service Datastore, procédez comme suit :

Recherchez les lignes qui utilisent la méthode DatastoreServiceFactory.getDatastoreService(), comme suit :
```
// Initialize a client
DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
```
Remplacez la méthode DatastoreServiceFactory.getDatastoreService() par la méthode DatastoreOptions.getDefaultInstance().getService(), comme suit :
```
// Initialize a client
Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
```

Obtenir une clé générée par Datastore

Après avoir initialisé un client, obtenez votre clé en créant une nouvelle ressource KeyFactory de la classe Kind appropriée, puis demandez à Datastore d'en générer une pour vous. Pour obtenir une clé générée par Datastore, procédez comme suit :

Créez un objet newKeyFactory.
Appelez la méthode setKind() pour déterminer l'élément kind de l'entité utilisée pour les catégorisations de requêtes.

Ajoutez la méthode newKey() pour générer une clé Datastore :

//Prepare a new entity
String kind = "visit";
Key key = datastore.allocateId(datastore.newKeyFactory().setKind(kind).newKey());

Modifier la création d'entités

Après avoir obtenu une clé Datastore, créez des entités à l'aide des méthodes suivantes :

Utilisez Entity.newBuilder, puis transmettez la clé générée par le datastore.

Recherchez les lignes qui utilisent l'appel de constructeur Entity, comme suit :
```
Entity visit = new Entity(kind);
```
Remplacez l'appel du constructeur Entity par l'appel du constructeur Entity.newBuilder, comme suit :
```
Entity visit = Entity.newBuilder(key);
```
Utilisez la méthode set pour définir des propriétés sur des entités.

Le premier paramètre correspond à la propriété souhaitée, et le second à la valeur. Dans le cas de la propriété timestamp, la valeur est un Timestamp au lieu d'un Instant.toString().

Recherchez les lignes qui utilisent la méthode setProperty, comme suit :
```
visit.setProperty("user_ip", userIp);
visit.setProperty("timestamp", Instant.now().toString());
```
Remplacez la méthode setProperty par la méthode set, comme suit :
```
Entity visit = Entity.newBuilder(key).set("user_ip", userIp).set("timestamp", Timestamp.now()).build();
```

Valider votre transaction

La bibliothèque cliente Firestore en mode Datastore utilise la méthode add() pour valider une transaction. Pour valider votre transaction, procédez comme suit :

Recherchez les lignes qui utilisent la méthode put(), comme suit :
```
// Save the entity
datastore.put(visit);
```
Remplacez la méthode put() par la méthode add(), comme suit :
```
// Save the entity
datastore.add(visit);
```

Résultats de la requête

Les requêtes récupèrent les entities qui répondent à un ensemble de conditions spécifié. Vous pouvez utiliser les méthodes suivantes pour afficher les résultats :

La méthode OrderBy affiche les résultats par ordre croissant ou décroissant.
La méthode Limit limite le nombre maximal de résultats récupérés à l'aide de dans le même compilateur.

Les requêtes utilisent une méthode de modèle de compilateur avec la variable kind. La variable kind est définie sur Visit à partir de l'étape Obtenir une clé générée par Datastore.

Pour récupérer les 10 premiers résultats, procédez comme suit :

Recherchez les lignes qui utilisent la méthode addSort(), comme suit :

  // Retrieve the last 10 visits from the datastore, ordered by timestamp.
  Query query = new Query(kind).addSort("timestamp", Query.SortDirection.DESCENDING);
  List<Entity> results = datastore.prepare(query).asList(FetchOptions.Builder.withLimit(10));

Remplacez la méthode addSort() par la méthode setOrderBy(), puis ajoutez la méthode setLimit(), comme suit :

// Retrieve the last 10 visits from the datastore, ordered by timestamp.
Query<Entity> query = Query.newEntityQueryBuilder()
                        .setKind(kind)
                        .setOrderBy(StructuredQuery.OrderBy.desc("timestamp"))
                        .setLimit(10)
                        .build();

Une fois la requête prête, exécutez le code à l'aide de datastore.run() et collectez les résultats dans une collection QueryResultsEntity.

L'objet QueryResults obtenu est un itérateur doté d'une fonction hasNext().

Vérifiez si l'ensemble de résultats contient un objet next pour le traitement, au lieu de parcourir la liste des résultats. Exemple :

QueryResults<Entity> results = datastore.run(query);

      resp.setContentType("text/plain");
      PrintWriter out = resp.getWriter();
      out.print("Last 10 visits:\n");
      while (results.hasNext()) {
          Entity entity = results.next();
          out.format(
                  "Time: %s Addr: %s\n", entity.getTimestamp("timestamp"), entity.getString("user_ip"));
      }

Exemples

Pour voir un exemple de migration d'une application Java 8 vers Firestore en mode Datastore, comparez l'exemple de code App Engine Datastore pour Java 8 et l'exemple de code Firestore en mode Datastore dans GitHub.

Étapes suivantes

Découvrez comment utiliser Firestore en mode Datastore.
Pour en savoir plus, consultez la documentation de Firestore en mode Datastore.
Découvrez comment migrer à partir des anciens services groupés pour Java.