在 2024 年演示日活动中，观看有关如何使用 Firebase 构建和运行 AI 赋能应用的演示。立即观看。

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

使用時間點復原 (PITR)

本頁面說明如何使用時間點復原 (PITR) 功能，保留及復原 Cloud Firestore 中的資料。

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

權限

如要取得管理 PITR 設定所需的權限，請要求管理員在您要啟用 PITR 的專案中，授予下列 IAM 角色：

Cloud Datastore 擁有者 (roles/datastore.owner)

針對自訂角色，請確認已授予下列權限：

如要在建立資料庫時啟用 PITR，請執行下列操作：datastore.databases.create
如要更新現有資料庫的 PITR 設定，請參閱 datastore.databases.update、datastore.databases.list
如要從 PITR 資料執行讀取作業：datastore.databases.get、datastore.entities.get、datastore.entities.list
如何匯出 PITR 資料：datastore.databases.export
如要匯入 PITR 資料，請按照以下步驟操作：datastore.databases.import

事前準備

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

啟用 PITR 後，您無法立即開始讀取七天前的資料。
如果您想在建立資料庫時啟用 PITR，必須使用 gcloud firestore databases create 指令。使用 Google Cloud 控制台建立資料庫時，系統不支援啟用 PITR。
Cloud Firestore 啟用 PITR 後，就會開始保留從該時間點開始的版本。
停用 PITR 後，您就無法在 PITR 視窗中讀取 PITR 資料。
如果在停用 PITR 後立即重新啟用，您將無法再使用過去的 PITR 資料。停用 PITR 前建立的任何 PITR 資料，都會在 PITR 到期日後刪除。
如果您在過去一小時內不小心刪除資料，且 PITR 已停用，只要在刪除資料後一小時內啟用 PITR，即可還原資料。
對已過期 PITR 資料執行的任何讀取作業都會失敗。

啟用 PITR

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

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

控制台

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

前往「資料庫」
從資料庫清單中選取必要資料庫。
在導覽選單中，按一下「Disaster Recovery」(災難復原)。
按一下「編輯」即可編輯設定。
勾選「啟用指定時間點復原」核取方塊，然後按一下「儲存」。

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

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

gcloud

在建立資料庫時啟用 PITR，方法是使用 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 指令停用 PITR，如下所示：

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

請按照下列方式替換值：

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

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

控制台

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

前往「資料庫」
從資料庫清單中選取必要資料庫。
在導覽選單中，按一下「Disaster Recovery」(災難復原)。
在「設定」部分，請注意「保留期間」和「最早版本時間」。
- 保留期限：Cloud Firestore 保留資料庫所有版本資料的期限。這個值在停用 PITR 時為一小時，啟用 PITR 時則為七天。
- 最早版本時間：在 PITR 期間可讀取舊版資料的最早時間戳記。這個值會持續由 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：時間點復原功能保留資料的時間長度 (以毫秒為單位)。值可以是 1 小時 (如果停用 PITR)，或 7 天 (如果啟用 PITR)。

讀取 PITR 資料

您可以使用用戶端程式庫、REST API 方法或 FirestoreIO Apache Beam 連接器讀取 PITR 資料。

用戶端程式庫

Java

您必須使用 ReadOnly 交易才能讀取 PITR 資料。您無法直接在讀取作業中指定 readTime。詳情請參閱「交易和批次寫入」。

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

節點

您必須使用 ReadOnly 交易才能讀取 PITR 資料。您無法直接在讀取作業中指定 readTime。詳情請參閱「交易和批次寫入」。

  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 方法執行讀取作業，請嘗試下列其中一種做法：

在讀取方法要求中，將 readTime 值傳遞為 readOptions 方法中支援的 PITR 時間戳記。PITR 時間戳記可以是過去一小時內的微秒精確度時間戳記，或是過去一小時後的整分鐘時間戳記，但不得早於 earliestVersionTime。
將 readTime 參數與 BeginTransaction 方法搭配使用，做為多個 PITR 讀取作業的 ReadOnly 交易的一部分。

Apache Beam

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

Cloud FirestoreIO 連接器的下列讀取方法支援 PITR 讀取作業。以下讀取方法支援您用於 PITR 讀取的 withReadTime(@Nullable Instant readTime) 方法：

Java

以下程式碼可搭配範例 Dataflow 管道程式碼使用，用於大量讀取或寫入作業。本範例會使用 withReadTime(@Nullable Instant readTime) 方法讀取 PITR。

  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 存放區。

匯出及匯入 PITR 資料

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

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

匯出資料庫，並將 snapshot-time 參數指定為所需的復原時間戳記。
gcloud
執行下列指令，將資料庫匯出至您的值區。
```
gcloud firestore export gs://BUCKET_NAME_PATH \
    --snapshot-time=PITR_TIMESTAMP \
    --collection-ids=COLLECTION_IDS \
    --namespace-ids=NAMESPACE_IDS
```
其中
- BUCKET_NAME_PATH：有效的 Cloud Storage 值區，其中包含匯出檔案的選用路徑前置字串。
- 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'。
- NAMESPACE_IDS：命名空間 ID 清單，例如 'customer','orders'。
匯出 PITR 資料前，請注意下列事項：
- 請使用 RFC 3339 格式指定時間戳記。例如 2023-05-26T10:20:00.00Z 或 2023-10-19T10:30:00.00-07:00。
- 請確認您指定的時間戳記是過去七天內的整分鐘時間戳記，但不得早於 earliestVersionTime。如果指定時間戳記時資料已不存在，系統會產生錯誤。時間戳記必須是整分鐘，即使指定時間是在過去一小時內也一樣。
- 您不會因 PITR 匯出作業失敗而遭收費。
匯入資料庫。

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