從 App Engine Datastore 遷移至 Datastore 模式的 Firestore

本指南說明如何從 App Engine Datastore 遷移至 Datastore 模式的 Firestore (也稱為 Datastore)。

Datastore 模式的 Firestore 與 App Engine Datastore 類似，兩者都參照相同的基礎 Datastore 服務。App Engine Datastore 只能透過 App Engine 舊版套裝服務存取，而 Datastore 模式的 Firestore 則是獨立 Google Cloud 產品，可透過 Cloud 用戶端程式庫存取。

Datastore 模式的 Firestore 也提供免費層級，可讓您管理高度可擴充的 NoSQL 文件資料庫，並在日後彈性遷移至 Cloud Run 或其他 Google Cloud 應用程式 Google Cloud 代管平台。

事前準備

請先瞭解不同的 Firestore 資料庫模式，確保您知道應用程式的最佳用途。請注意，本指南涵蓋如何遷移至 Datastore 模式。
查看並瞭解 Firestore (Datastore 模式) 的定價和配額。

Firestore (Datastore 模式) 提供免費用量，但設有每日上限。付費帳戶則享有無限的儲存空間，以及不限次數的讀取和寫入作業。停用 App Engine 應用程式後，應用程式不會收到任何流量，因此不會產生費用，但如果 Datastore 用量超出免付費配額限制，可能仍會產生費用。
在包含應用程式的專案中啟用下列 API：
- Artifact Registry API，用於儲存及管理建構作業構件
- Cloud Build API，可持續建構、測試及部署應用程式。
- Cloud Datastore API，可從 App Engine 隨附的 Datastore 遷移至 Datastore 模式的 Firestore。
  
  啟用 API
現有的 App Engine 應用程式執行 Java 8 或 11，並連線至 App Engine Datastore 服務。

流程總覽

從 App Engine Datastore 遷移至 Datastore 模式的 Firestore，大致包含以下步驟：

更新設定檔
更新 Java 應用程式
提交交易
查詢結果

更新設定政策

更新設定檔，使用 Datastore 模式用戶端程式庫。

更新基準 Java 應用程式的 pom.xml 檔案：

移除 App Engine SDK appengine-api-1.0-sdk 匯入作業，例如：

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

新增 Datastore 用戶端，如下所示：

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

更新 Java 應用程式

更新匯入陳述式

更新匯入和初始化行，藉此修改應用程式檔案：

移除下列 App Engine Datastore com.google.appengine.api.datastore.* 的 App Engine 匯入陳述式：

  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;

新增下列 Firestore (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;

修改應用程式存取 Datastore 服務的方式

Datastore 模式的 Firestore 會使用 Datastore 類別，而非 DatastoreService。如要修改應用程式存取 Datastore 服務的方式，請按照下列步驟操作：

找出使用 DatastoreServiceFactory.getDatastoreService() 方法的程式碼行，如下所示：

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

將 DatastoreServiceFactory.getDatastoreService() 替換為 DatastoreOptions.getDefaultInstance().getService() 方法，如下所示：
```
// Initialize a client
Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
```

取得 Datastore 產生的金鑰

初始化用戶端後，請建立適當的 Kind，然後讓 Datastore 為您產生金鑰。KeyFactory如何取得 Datastore 產生的金鑰：

建立 newKeyFactory。
呼叫 setKind() 方法，判斷用於查詢分類的實體 kind。

附加 newKey() 方法，產生 Datastore 鍵：

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

修改實體建立作業

取得 Datastore 鍵後，請使用下列方法建立實體：

使用 Entity.newBuilder，並傳遞由 Datastore 產生的鍵。

找出使用 Entity 建構函式呼叫的行，如下所示：
```
Entity visit = new Entity(kind);
```
使用 Entity.newBuilder 建構函式呼叫取代 Entity 建構函式呼叫，如下所示：
```
Entity visit = Entity.newBuilder(key);
```
使用 set 方法設定實體的屬性。

第一個參數是預期屬性，第二個參數是值。如果是 timestamp 屬性，值會是 Timestamp，而不是 Instant.toString()。

找出使用 setProperty 方法的程式碼行，如下所示：
```
visit.setProperty("user_ip", userIp);
visit.setProperty("timestamp", Instant.now().toString());
```
將 setProperty 方法替換為 set 方法，如下所示：
```
Entity visit = Entity.newBuilder(key).set("user_ip", userIp).set("timestamp", Timestamp.now()).build();
```

提交交易

Datastore 模式的 Firestore 用戶端程式庫會使用 add() 方法提交交易。如要提交交易：

找出使用 put() 方法的程式碼行，如下所示：
```
// Save the entity
datastore.put(visit);
```
將 put() 方法替換為 add() 方法，如下所示：
```
// Save the entity
datastore.add(visit);
```

查詢結果

查詢會擷取符合一組特定條件的entities。您可以使用下列方法顯示結果：

OrderBy 方法會以遞增或遞減順序顯示結果。
Limit 方法會限制在同一個建構工具中擷取的結果數量上限。

查詢會使用含有 kind 變數的建構工具模式方法。kind 變數會從「取得 Datastore 產生的金鑰」步驟設為 Visit。

如要擷取前 10 個結果，請執行下列操作：

找出使用 addSort() 方法的程式碼行，如下所示：

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

將 addSort() 方法替換為 setOrderBy() 方法，並附加 setLimit() 方法，如下所示：

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

查詢準備就緒後，請使用 datastore.run() 執行程式碼，並在 QueryResultsEntity 集合中收集結果。

產生的 QueryResults 物件是具有 hasNext() 函式的迭代器。

檢查結果集是否有 next 物件可供處理，而不是在結果清單中循環。例如：

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

範例

如要查看如何將 Java 8 應用程式遷移至 Datastore 模式的 Firestore，請比較 GitHub 中的 App Engine Datastore for Java 8 程式碼範例和 Datastore 模式的 Firestore 程式碼範例。

從 App Engine Datastore 遷移至 Datastore 模式的 Firestore 透過集合功能整理內容 你可以依據偏好儲存及分類內容。