使用時間點復原 (PITR)

控制台

1. 前往 Google Cloud 控制台的「資料庫」頁面。

   前往「資料庫」

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

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

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

5. 勾選「Enable point-in-time recovery」(啟用時間點還原) 核取方塊，然後按一下「Save」(儲存)。

啟用 PITR 功能會產生儲存費用。詳情請參閱定價。

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

gcloud

使用 gcloud firestore databases create 和 --enable-ptir 指令，在建立資料庫時啟用 PITR，如下所示：

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --type=firestore-native\
  --enable-pitr

將值替換為下列項目：

• LOCATION：您要建立資料庫的位置。
• DATABASE_ID - 設為資料庫 ID。

您可以使用 gcloud firestore databases update 指令停用 PITR，如下所示：

gcloud firestore databases update\
  --database=DATABASE_ID\
  --no-enable-pitr

將值替換為下列項目：

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

控制台

1. 前往 Google Cloud 控制台的「資料庫」頁面。

   前往「資料庫」

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

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

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

   • 保留期限：與 MongoDB 相容的 Cloud Firestore 保留資料庫所有版本資料的期限。如果停用時間點復原功能，保留期限為一小時；如果啟用，則為七天。
   • 最早版本時間：時間點復原 (PITR) 期間內可讀取資料舊版本的最早時間戳記。這個值會由與 MongoDB 相容的 Cloud Firestore 持續更新，一經查詢就會過時。如果您要使用這個值復原資料，請務必將查詢值到啟動復原作業之間的時間納入考量。
   • 時間點復原：如果已啟用 PITR，會顯示 Enabled。如果 PITR 已停用，您會看到 Disabled。

gcloud

執行 gcloud firestore databases 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/DATABASE_ID
    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：最早儲存的 PITR 資料時間戳記。
• pointInTimeRecoveryEnablement：如果啟用 PITR，則會顯示 POINT_IN_TIME_RECOVERY_ENABLED。如果停用 PITR，您會看到 POINT_IN_TIME_RECOVERY_DISABLED，或者系統可能不會顯示 pointInTimeRecoveryEnablement 欄位。
• versionRetentionPeriod：以毫秒為單位的 PITR 資料保留時間。如果停用時間點復原功能，值可以是一小時；如果啟用時間點復原功能，值可以是七天。

用戶端程式庫

  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

所有與 MongoDB 相容的 Cloud Firestore 讀取方法都支援 PITR 讀取，包括 get、list、batchGet、listCollectionIds、listDocuments、runQuery、runAggregationQuery 和 partitionQuery。

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

1. 在讀取方法要求中，將 readTime 值做為 readOptions 方法中支援的 PITR 時間戳記傳遞。PITR 時間戳記可以是過去一小時內精確到微秒的時間戳記，也可以是過去一小時以外精確到整分鐘的時間戳記，但不得早於 earliestVersionTime。

2. 搭配 BeginTransaction 方法使用 readTime 參數，做為多個 PITR 讀取作業的ReadOnly交易一部分。

Apache Beam

使用與 MongoDB 相容的 Cloud Firestore IO Apache Beam 連接器，透過 Dataflow 大規模讀取或寫入與 MongoDB 相容的 Cloud Firestore 資料庫中的文件。

Cloud Firestore with MongoDB compatibility IO 連接器的下列讀取方法支援 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 存放區。

主控台

Firebase 控制台不支援資料庫複製功能。您可以按照 Google Cloud CLI 的說明複製資料庫。

gcloud

使用 gcloud firestore databases clone 指令複製資料庫：

gcloud firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

更改下列內容：

• SOURCE_DATABASE：要複製的現有資料庫名稱。名稱格式為 projects/PROJECT_ID/databases/SOURCE_DATABASE_ID。

• PITR_TIMESTAMP：PITR 時間戳記，採用 RFC 3339 格式，精確度為分鐘。例如：2025-06-01T10:20:00.00Z 或 2025-06-01T10:30:00.00-07:00。

• DESTINATION_DATABASE_ID：新複製資料庫的資料庫 ID。這個資料庫 ID 不得與現有資料庫建立關聯。

範例：

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

如要在複製資料庫時繫結某些標記，請使用先前的指令和 --tags 旗標，這是要繫結的標記 KEY=VALUE 組合的選用清單。

範例：

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--tags=key1=value1,key2=value2

根據預設，複製的資料庫會與來源資料庫採用相同的加密設定。如要變更加密設定，請使用 --encryption-type 引數：

• (預設) use-source-encryption：使用與來源資料庫相同的加密設定。
• google-default-encryption：使用 Google 的預設加密機制。
• customer-managed-encryption：使用 CMEK 加密。在 --kms-key-name 引數中指定金鑰 ID。

以下範例說明如何為複製的資料庫設定 CMEK 加密：

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

Firebase CLI

使用 firebase firestore:databases:clone 指令複製資料庫：

firebase firestore:databases:clone \
'SOURCE_DATABASE' \
'DESTINATION_DATABASE' \
--snapshot-time 'PITR_TIMESTAMP'

更改下列內容：

• SOURCE_DATABASE：要複製的現有資料庫名稱。名稱格式為 projects/PROJECT_ID/databases/SOURCE_DATABASE_ID。

• DESTINATION_DATABASE：新複製資料庫的資料庫名稱。名稱格式為 projects/PROJECT_ID/databases/DESTINATION_DATABASE_ID。這個資料庫名稱不得與現有資料庫相關聯。

• PITR_TIMESTAMP：PITR 時間戳記，採用 RFC 3339 格式，精確度為分鐘。例如：2025-06-01T10:20:00.00Z 或 2025-06-01T10:30:00.00-07:00。如未指定，系統會選擇目前時間的快照，並向下取整至分鐘。

根據預設，複製的資料庫會與來源資料庫採用相同的加密設定。如要變更加密設定，請使用 --encryption-type 引數：

• (預設) USE_SOURCE_ENCRYPTION：使用與來源資料庫相同的加密設定。
• GOOGLE_DEFAULT_ENCRYPTION：使用 Google 的預設加密機制。
• CUSTOMER_MANAGED_ENCRYPTION：使用 CMEK 加密。在 --kms-key-name 引數中指定金鑰 ID。

以下範例說明如何為複製的資料庫設定 CMEK 加密：

firebase firestore:databases:clone \
'projects/example-project/databases/(default)' \
'projects/example-project/databases/example-dest-db' \
--snapshot-time 'PITR_TIMESTAMP' \
--encryption-type CUSTOMER_MANAGED_ENCRYPTION