使用時間點復原 (PITR) 功能

控制台

1. 在 Google Cloud Platform Console 中，前往「Databases」頁面。

   前往「資料庫」頁面

2. 從資料庫清單中選取所需的資料庫。

3. 在導覽選單中，按一下「災難復原」。

4. 按一下「編輯」即可編輯設定。

5. 勾選「啟用時間點復原」核取方塊，然後按一下「儲存」。

啟用時間點復原功能會產生儲存空間費用。詳情請參閱定價。

如要停用時間點復原功能，請在 GCP 控制台的「災難復原」頁面中，取消勾選「啟用時間點復原」核取方塊。

gcloud

在建立資料庫期間，使用 gcloud firestore databases create 指令啟用時間點復原功能，如下所示：

gcloud firestore databases create\
  --location=LOCATION\
  [--database=DATABASE_ID; default="(default)"]\
  [--type=TYPE; default="firestore-native"]\
  --enable-pitr

按照下列方式取代值：

• Location：您要建立資料庫的位置。
• DATABASE_ID：設為資料庫 ID 或 (預設)。
• TYPE - 設為 Firestore-native。

您可以使用 gcloud firestore databases update 指令停用時間點復原功能，如下所示：

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --no-enable-pitr

按照下列方式取代值：

• DATABASE_ID：設為資料庫 ID 或 (預設)。

控制台

1. 在 Google Cloud Platform Console 中，前往「Databases」頁面。

   前往「資料庫」頁面

2. 從資料庫清單中選取所需的資料庫。

3. 在導覽選單中，按一下「災難復原」。

4. 在「設定」部分，記下「保留期限」和「最早版本時間」。

   • 保留期限：Cloud Firestore 為資料庫保留所有版本資料的時間範圍。這個值為停用時間點復原功能時的一小時，值是啟用時間點復原功能時七天。
   • 最早版本時間：最早可以在 PITR 視窗中讀取舊版資料的時間時間戳記。Cloud Firestore 會持續更新這個值，且會在查詢時過時。如果您使用這個值復原資料，請務必考量從「完成」復原當下查詢該值的時間。
   • 時間點復原：如果已啟用時間點復原功能，會顯示 Enabled。如果 PITR 已停用，則會顯示 Disabled。

gcloud

按照以下方式執行 gcloud Firestore libraries describe 指令：

gcloud firestore databases describe --database=DATABASE_ID

請將 DATABASE_ID 替換為資料庫 ID 或 default。

輸出內容如下所示：

    appEngineIntegrationMode: ENABLED
    concurrencyMode: PESSIMISTIC
    createTime: '2021-03-24T17:02:35.234Z'
    deleteProtectionState: DELETE_PROTECTION_DISABLED
    earliestVersionTime: '2023-06-12T16:17:25.222474Z'
    etag: IIDayqOevv8CMNTvyNK4uv8C
    keyPrefix: s
    locationId: nam5
    name: projects/PROJECT_ID/databases/(default)
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: FIRESTORE_NATIVE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

其中：

• earliestVersionTime - 最早儲存的時間點復原資料時間戳記。
• pointInTimeRecoveryEnablement：如果啟用時間點復原功能，會顯示 POINT_IN_TIME_RECOVERY_ENABLED。如果 PITR 已停用，您會看到 POINT_IN_TIME_RECOVERY_DISABLED 或 pointInTimeRecoveryEnablement 欄位可能未顯示。
• versionRetentionPeriod - 時間點復原資料保留的時間範圍 (以毫秒為單位)。這個值可能是在 PITR 停用時設為一小時，如果啟用了時間點復原功能，則該值可能是 7 天。

用戶端程式庫

  Firestore firestore = …

  TransactionOptions options =
          TransactionOptions.createReadOnlyOptionsBuilder()
              .setReadTime(
                  com.google.protobuf.Timestamp.newBuilder()
                      .setSeconds(1684098540L)
                      .setNanos(0))
              .build();

  ApiFuture<Void> futureTransaction = firestore.runTransaction(
              transaction -> {
                // Does a snapshot read document lookup
                final DocumentSnapshot documentResult =
                    transaction.get(documentReference).get();

                // Executes a snapshot read query
                final QuerySnapshot queryResult =
                  transaction.get(query).get();
              },
              options);

  // Blocks on transaction to complete
  futureTransaction.get();

  const documentSnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(documentRef),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

  const querySnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(query),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
  )

REST API

所有 Cloud Firestore 讀取方法都支援 PITR 讀取作業，這些方法包括 get、list、batchGet、listCollectionIds、listDocuments、runQuery、runAggregationQuery 和 partitionQuery。

如要使用 REST 方法執行讀取作業，請嘗試下列其中一種選項：

1. 在讀取方法要求中，在 readOptions 方法中，將 readTime 值做為支援的時間點復原時間戳記傳遞。時間點復原時間戳記可以是過去 1 小時內的微秒精確度時間戳記，或是超過過去一小時的整分鐘時間戳記，但早於 earliestVersionTime。

2. 針對多次 PITR 讀取作業，在 ReadOnly 交易中搭配使用 readTime 參數和 BeginTransaction 方法。

Apache Beam

使用 Cloud FirestoreIO Apache Beam 連接器，透過 Dataflow 以大規模的 Cloud Firestore 資料庫讀取或寫入文件。

下列 Cloud FirestoreIO 連接器的讀取方法支援 PITR 讀取功能。下列讀取方法支援可用於 PITR 讀取的 withReadTime(@Nullable Instant readTime) 方法：

• FirestoreV1.BatchGetDocuments
• FirestoreV1.ListCollectionIds
• FirestoreV1.ListDocuments
• FirestoreV1.PartitionQuery

• FirestoreV1.RunQuery

  Instant readTime = Instant.ofEpochSecond(1684098540L);

  PCollection<Document> documents =
      pipeline
          .apply(Create.of(collectionId))
          .apply(
              new FilterDocumentsQuery(
                  firestoreOptions.getProjectId(), firestoreOptions.getDatabaseId()))
          .apply(FirestoreIO.v1().read().runQuery().withReadTime(readTime).withRpcQosOptions(rpcQosOptions).build())
  ...

如需 Dataflow 管道中 readTime 範例的完整清單，請前往 GitHub 存放區。