Esta página foi traduzida pela API Cloud Translation.

Migre do Armazenamento de dados do App Engine para o Firestore no modo Datastore

Este guia demonstra como migrar do App Engine Datastore para o Firestore no modo Datastore (também conhecido como Datastore).

O Firestore no modo Datastore é semelhante ao Datastore do App Engine, uma vez que ambos se referem ao mesmo serviço Datastore subjacente. Embora o App Engine Datastore só seja acessível através dos serviços agrupados legados do App Engine, o Firestore no modo Datastore é um produto autónomo Google Cloud que é acedido através das bibliotecas de cliente da nuvem.

O Firestore no modo Datastore também oferece um nível gratuito e permite-lhe gerir uma base de dados de documentos NoSQL altamente escalável, bem como dá-lhe flexibilidade no futuro para migrar para o Cloud Run ou outra plataforma de alojamento de apps. Google Cloud

Antes de começar

Reveja os diferentes modos da base de dados do Firestore para garantir que compreende o melhor exemplo de utilização para a sua app. Tenha em atenção que este guia aborda como migrar para o modo Datastore.
Reveja e compreenda os preços e as quotas do Firestore no modo Datastore.

O Firestore no modo Datastore oferece utilização gratuita com limites diários e armazenamento, leitura e operações de escrita ilimitados para contas pagas. Embora as apps do App Engine estejam desativadas, não recebem tráfego para incorrer em custos. No entanto, a utilização do Datastore pode ser faturável se exceder os limites da quota gratuita.
Ative as seguintes APIs no projeto que contém a sua app:
- API Artifact Registry para armazenar e gerir os seus artefactos de compilação
- API Cloud Build para criar, testar e implementar continuamente a sua aplicação.
- API Cloud Datastore para migrar do Datastore incluído no App Engine para o Firestore no modo Datastore.
  
  Ative as APIs
Ter uma app do App Engine existente a executar o Java 8 ou 11 que esteja ligada ao serviço App Engine Datastore.

Vista geral do processo

A um nível elevado, o processo de migração para o Firestore no modo Datastore a partir do App Engine Datastore consiste nos seguintes passos:

Atualize os ficheiros de configuração
Atualize a sua app Java
Confirme a transação
Resultados da consulta

Atualize os ficheiros de configuração

Atualize os ficheiros de configuração para usar as bibliotecas de cliente do modo Datastore.

Atualize o ficheiro pom.xml da sua app Java de base:

Remova as importações do SDK do App Engine appengine-api-1.0-sdk, como as seguintes:

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

Adicione o cliente Datastore, como o seguinte:

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

Atualize a sua app Java

Atualize as declarações de importação

Modifique os ficheiros da aplicação atualizando as linhas de importação e inicialização:

Remova as seguintes declarações de importação do App Engine para o armazenamento de dados do App Engine 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;

Adicione as seguintes importações do Firestore no modo Datastore:com.google.cloud.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;

Modifique a forma como a sua app acede ao serviço Datastore

O Firestore no modo Datastore usa a classe Datastore em vez de DatastoreService. Para modificar a forma como a sua app acede ao serviço Datastore:

Encontre as linhas que usam o método DatastoreServiceFactory.getDatastoreService(), como o seguinte:

// Initialize a client
DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

Substitua o método DatastoreServiceFactory.getDatastoreService() por DatastoreOptions.getDefaultInstance().getService(), como no seguinte exemplo:
```
// Initialize a client
Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
```

Obtenha uma chave gerada pelo Datastore

Depois de inicializar um cliente, obtenha a chave criando um novo KeyFactory do Kind adequado e, em seguida, peça ao Datastore para gerar um para si. Para obter uma chave gerada pelo Datastore:

Crie um newKeyFactory.
Chame o método setKind() para determinar o kind da entidade usada para categorizações de consultas.

Anexe o método newKey() para gerar uma chave do Datastore:

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

Modifique a criação de entidades

Depois de obter uma chave do Datastore, crie entidades através dos seguintes métodos:

Use Entity.newBuilder e transmita a chave gerada pelo Datastore.

Encontre as linhas que usam a chamada do construtor Entity, como a seguinte:
```
Entity visit = new Entity(kind);
```
Substitua a chamada do construtor Entity pela chamada do construtor Entity.newBuilder, como no seguinte exemplo:
```
Entity visit = Entity.newBuilder(key);
```
Use o método set para definir propriedades em entidades.

O primeiro parâmetro é a propriedade pretendida e o segundo é o valor. No caso da propriedade timestamp, o valor é um Timestamp em vez de um Instant.toString().

Encontre as linhas que usam o método setProperty, como as seguintes:
```
visit.setProperty("user_ip", userIp);
visit.setProperty("timestamp", Instant.now().toString());
```
Substitua o método setProperty pelo método set, como no exemplo seguinte:
```
Entity visit = Entity.newBuilder(key).set("user_ip", userIp).set("timestamp", Timestamp.now()).build();
```

Confirme a sua transação

A biblioteca cliente do Firestore no modo Datastore usa o método add() para confirmar uma transação. Para confirmar a transação:

Encontre linhas que usam o método put(), como as seguintes:
```
// Save the entity
datastore.put(visit);
```
Substitua o método put() pelo método add(), como no exemplo seguinte:
```
// Save the entity
datastore.add(visit);
```

Resultados da consulta

As consultas obtêm entities que cumprem um conjunto de condições especificado. Pode usar os seguintes métodos para apresentar resultados:

O método OrderBy apresenta os resultados por ordem ascendente ou descendente.
O método Limit limita o número máximo de resultados obtidos através de no mesmo criador.

A consulta usa um método de padrão de criação com a variável kind. A variável kind está definida como Visit a partir do passo Obtenha uma chave gerada pelo Datastore.

Para obter os primeiros 10 resultados:

Encontre linhas que usam o método addSort(), como as seguintes:

  // 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));

Substitua o método addSort() pelo método setOrderBy() e anexe o método setLimit(), da seguinte forma:

// 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();

Quando a consulta estiver pronta, execute o código com datastore.run() e recolha os resultados numa coleção QueryResultsEntity.

O objeto QueryResults resultante é um iterador com uma função hasNext().

Verifique se o conjunto de resultados tem um objeto next para processamento, em vez de percorrer a lista de resultados. Por exemplo:

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"));
      }

Exemplos

Para ver um exemplo de como migrar uma app Java 8 para o Firestore no modo Datastore, compare o exemplo de código do App Engine Datastore para Java 8 e o exemplo de código do Firestore no modo Datastore no GitHub.

Próximos passos

Saiba como usar o Firestore no modo Datastore.
Consulte a documentação do Firestore no modo Datastore para ver mais detalhes.
Saiba como migrar dos serviços incluídos antigos para Java.