使用時間點復原 (PITR)

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

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

權限

如要取得管理時間點復原設定所需的權限，請要求管理員針對您要啟用時間點復原功能的專案授予您下列 IAM 角色：

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

如果是自訂角色，請確認已授予下列權限：

• 如何在建立資料庫時啟用時間點復原功能：datastore.databases.create
• 如要更新現有資料庫的時間點復原設定，請前往：datastore.databases.update、datastore.databases.list
• 如何執行時間點復原 (PITR) 資料的讀取作業：datastore.databases.get、datastore.entities.get、datastore.entities.list
• 如要匯出時間點復原資料：datastore.databases.export
• 如何匯入時間點復原資料：datastore.databases.import

事前準備

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

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

啟用時間點復原功能

使用時間點復原工具前，請先為 Google Cloud 啟用計費功能 專案。 只有啟用帳單功能的 Google Cloud 專案才能使用時間點復原功能。

如何為資料庫啟用時間點復原功能：

主控台

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

   前往「資料庫」頁面

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

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

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

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

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

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

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 控制台的「Databases」(資料庫) 頁面。

   前往「資料庫」頁面

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

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

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

   • 保留期限：Cloud Firestore保留的時間範圍 資料庫的所有資料版本當 PITR 等於 停用時，當啟用時間點復原功能時，也會自動停用七天。
   • 最早版本時間：最早的時間戳記 可在時間點復原 (PITR) 視窗中讀取資料這個值會持續更新 由 Cloud Firestore 觸發，且在查詢時已過時。如果發生以下情況： 並使用這個值復原資料，請務必考量 您啟動 以及災難復原
   • 時間點復原：如果為時間點復原，會顯示 Enabled。 如果時間點復原功能已停用，你會看到 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/(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：儲存最早 PITR 資料的時間戳記。
• pointInTimeRecoveryEnablement：顯示 POINT_IN_TIME_RECOVERY_ENABLED (如果時間點復原) 如果 PITR 已停用，您會看到 POINT_IN_TIME_RECOVERY_DISABLED，或是可能不會顯示 pointInTimeRecoveryEnablement 欄位。
• versionRetentionPeriod - 時間點復原資料保留的時間範圍 (以毫秒為單位)。這個值可能是在 PITR 停用時設為一小時，如果啟用了時間點復原功能，則該值可能是 7 天。

讀取時間點復原資料

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

用戶端程式庫

注意：您可以在伺服器用戶端程式庫 (Go、Java、Node.js 和 PHP) 中讀取 PITR 資料。不支援行動版和網頁版 SDK，也就是 Android、iOS 和 Web。

Java

必須使用 ReadOnly 交易讀取時間點復原資料。您無法在讀取中直接指定 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 交易才能讀取時間點復原資料。您無法在讀取中直接指定 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 方法執行讀取作業，請嘗試下列其中一種選項：

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

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

Apache Beam

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

下列 Cloud FirestoreIO 連接器。這些讀取方法支援 可用於時間點復原的 withReadTime(@Nullable Instant readTime) 方法 讀取：

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

• FirestoreV1.RunQuery

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) 資料匯出及匯入

您可以將資料庫從時間點復原 (PITR) 資料匯出至 Cloud Storage 呼叫 gcloud firestore export 指令您可以匯出時間點復原資料，時間戳記是指時間戳記在 過去 7 天，但早於 earliestVersionTime。如果資料不再需要 就會失敗。

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

1. 匯出資料庫，並將 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'。

   匯出時間點復原資料前，請注意下列事項：

   • 請在 RFC 3339 中指定時間戳記 格式。 例如 2023-05-26T10:20:00.00Z 或 2023-10-19T10:30:00.00-07:00。
   • 請確保您指定的時間戳記是整分鐘的時間戳記 建立在過去七天內，但並非早於 earliestVersionTime。如果指定的資料已不存在 時間戳記，就會產生錯誤。時間戳記必須是整數，即使指定時間是過去一小時內也一樣。
   • 系統不會向您收取時間點復原匯出失敗的費用。

2. 匯入資料庫。

   按照「匯入所有文件」一文中的步驟匯入 以及匯出的資料庫如果資料庫中已有文件 。