本頁面由 Cloud Translation API 翻譯而成。

使用時間點復原 (PITR)

本頁面說明如何使用時間點還原 (PITR) 功能，在與 MongoDB 相容的 Firestore 中保留及還原資料。

如要瞭解 PITR 概念，請參閱「時間點復原」。

權限

如要取得管理 PITR 設定所需的權限，請要求管理員在您要啟用 PITR 設定的專案中，授予您 Cloud Datastore 擁有者 (roles/datastore.owner) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備管理 PITR 設定所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要管理 PITR 設定，您必須具備下列權限：

如要在建立資料庫時啟用 PITR，請執行下列操作： datastore.databases.create
如要更新現有資料庫的時間點復原設定，請按照下列步驟操作： datastore.databases.update,datastore.databases.list
如要從 PITR 資料執行讀取作業： datastore.databases.get,datastore.entities.get,datastore.entities.list
如要匯出 PITR 資料，請按照下列步驟操作： datastore.databases.export
如要匯入 PITR 資料，請按照下列步驟操作： datastore.databases.import
如要複製資料庫，請按照下列步驟操作： datastore.databases.clone

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

事前準備

開始使用 PITR 前，請注意下列事項：

啟用 PITR 後，您無法立即開始讀取七天前的資料。
如要在建立資料庫時啟用 PITR，請務必使用 gcloud firestore databases create 指令。使用 Google Cloud 主控台建立資料庫時，不支援啟用 PITR。
啟用 PITR 後，與 MongoDB 相容的 Firestore 會開始保留版本。
停用 PITR 後，您就無法在 PITR 期間讀取 PITR 資料。
如果停用 PITR 後立即重新啟用，系統將無法再提供過去的 PITR 資料。停用 PITR 前建立的任何 PITR 資料，都會在 PITR 到期日後刪除。
如果您在過去一小時內不慎刪除資料，且 PITR 已停用，請在刪除資料後一小時內啟用 PITR，即可還原資料。
對過期 PITR 資料執行的任何讀取作業都會失敗。

啟用 PITR

使用 PITR 前，請先為 Google Cloud 專案啟用計費功能。只有啟用計費功能的 Google Cloud 專案才能使用 PITR 功能。

如要為資料庫啟用 PITR，請按照下列步驟操作：

控制台

前往 Google Cloud 控制台的「Databases」頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「Disaster Recovery」(災難復原)。
按一下「編輯」即可編輯設定。
勾選「Enable point-in-time recovery」(啟用時間點還原) 核取方塊，然後按一下「Save」(儲存)。

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

如要停用 PITR，請在 Google Cloud 控制台的「Disaster Recovery」(災害復原) 頁面中，取消勾選「Enable point-in-time recovery」(啟用時間點復原) 核取方塊。

gcloud

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

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --edition=enterprise\
  --enable-pitr

將值替換為下列項目：

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

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

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

將值替換為下列項目：

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

取得保留期限和最早版本時間

控制台

前往 Google Cloud 控制台的「Databases」頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「Disaster Recovery」(災難復原)。
在「設定」部分，請注意「保留期限」和「最早版本時間」。
- 保留期限：與 MongoDB 相容的 Firestore 保留資料庫所有版本資料的期限。如果停用 PITR，保留期限為一小時；如果啟用 PITR，保留期限為七天。
- 最早版本時間：時間點復原 (PITR) 期間內可讀取資料舊版本的最早時間戳記。與 MongoDB 相容的 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 資料保留時間。如果停用時間點復原功能，值可以是一小時；如果啟用時間點復原功能，值可以是七天。

讀取 PITR 資料

您可以使用各種 MongoDB 用戶端驅動程式中的快照工作階段，讀取 PITR 資料。在工作階段中設定 snapshotTimestamp。以下範例使用 MongoDB Java 驅動程式，其他驅動程式也提供類似功能：

Java

    var session =
        mongoClient.startSession(ClientSessionOptions.builder().snapshot(true).build());
  session.setSnapshotTimestamp(new BsonTimestamp(seconds, nanos));

  // run a find query with PITR timestamp
  collection.find(session, <filter>).toList();

  // run an aggregation query pipeline with PITR timestamp
  collection.aggregate(session, <aggregation pipeline stages>).toList();

  // run distinct command with PITR timestamp
  collection.distinct(session, <field>, <return value type class>).toList();

在 MongoDB 中，BsonTimestamp 是 MongoDB 內部專用的 64 位元 BSON 型別。前 32 位元代表紀元時間戳記 (以秒為單位)，後 32 位元則代表 MongoDB 叢集內的序數作業計數。

在與 MongoDB 相容的 Firestore 中，快照時間戳記仍使用 BsonTimestamp 值型別，但會將前 32 位元解讀為紀元時間戳記秒數，後 32 位元則解讀為秒數內的奈秒。請注意，系統僅支援部分奈秒 PITR 快照。允許使用過去 1 小時內的時間戳記 (以微秒為單位)，以及過去 7 天內的時間戳記 (以分鐘為單位)。如要瞭解支援哪些讀取時間戳記，請參閱時間點復原 (PITR) 總覽。

從資料庫複製

您可以將現有資料庫在所選時間戳記的狀態複製到新資料庫：

複製的資料庫是新資料庫，會建立在與來源資料庫相同的位置。

Firestore 會使用來源資料庫的時間點復原 (PITR) 資料進行複製。複製的資料庫包括所有資料和索引。
根據預設，複製的資料庫會採用與來源資料庫相同的加密方式，也就是使用 Google 的預設加密機制或 CMEK 加密機制。您可以指定不同的加密類型，或是使用不同的金鑰進行 CMEK 加密。
時間戳記的精細度為一分鐘，且指定過去的時間點，該時間點位於 PITR 視窗定義的期間內：
- 如果資料庫已啟用 PITR，您可以選取過去 7 天內的任何時間點 (如果啟用 PITR 的時間未滿 7 天，則可選取的時間範圍會更短)。
- 如果未啟用 PITR，您可以選取過去一小時內的任一分鐘。
- 你可以查看資料庫說明中可選取的最早時間戳記。

控制台

前往 Google Cloud 控制台的「Databases」頁面。

前往「資料庫」
在要複製的資料庫表格列中，按一下「查看更多」。按一下「Clone」(複製)。系統會顯示「建立副本」對話方塊。
在「Create a clone」(建立副本) 對話方塊中，提供資料庫副本的參數：
1. 在「為本機副本提供 ID」欄位中，輸入新複製資料庫的資料庫 ID。這個資料庫 ID 不得與現有資料庫建立關聯。
2. 在「Clone from」(從以下時間點複製) 欄位中，選取要用於複製的時間點。所選時間對應於 PITR 時間戳記，精確度為分鐘。
按一下 [建立本機複本]。

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

從 PITR 資料匯出及匯入

您可以使用 gcloud firestore export 指令，從 PITR 資料將資料庫匯出至 Cloud Storage。您可以匯出時間戳記為過去七天內整分鐘的時間點復原資料，但不得早於 earliestVersionTime。如果指定時間戳記的資料已不存在，匯出作業就會失敗。

PITR 匯出作業支援所有篩選條件，包括匯出所有文件和匯出特定集合。

匯出資料庫，並將 snapshot-time 參數指定為所選復原時間戳記。
gcloud
執行下列指令，將資料庫匯出至 bucket。
```
gcloud firestore export gs://BUCKET_NAME_PATH \
    --snapshot-time=PITR_TIMESTAMP \
    --collection-ids=COLLECTION_IDS
```
更改下列內容：
- BUCKET_NAME_PATH - 有效的 Cloud Storage bucket，以及儲存匯出檔案的選用路徑前置字串。
- PITR_TIMESTAMP - PITR 時間戳記，精細程度為分鐘，例如 2023-05-26T10:20:00.00Z 或 2023-10-19T10:30:00.00-07:00。
- COLLECTION_IDS：集合 ID 或集合群組 ID 清單，例如 'specific-collection-group1','specific-collection-group2'。
匯出 PITR 資料前，請注意下列事項：
- 請以 RFC 3339 格式指定時間戳記。例如：2023-05-26T10:20:00.00Z 或 2023-10-19T10:30:00.00-07:00。
- 請確認指定的時間戳記是過去七天內的整分時間戳記，但不得早於 earliestVersionTime。如果指定時間戳記的資料已不存在，系統會產生錯誤。即使指定時間在過去一小時內，時間戳記也必須是整分鐘。
- 如果 PITR 匯出作業失敗，系統不會收取任何費用。
匯入資料庫。

按照「匯入所有文件」一文中的步驟，匯入匯出的資料庫。如果資料庫中已有任何文件，系統會覆寫該文件。