使用時間點復原 (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，請按照下列步驟操作：

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

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

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

gcloud firestore databases describe --database=DATABASE_ID

    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

讀取 PITR 資料

您可以使用用戶端程式庫、REST API 方法或 FirestoreIO Apache Beam 連接器讀取 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)}
  )

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

匯出及匯入 PITR 資料

您可以使用 gcloud firestore export 指令，將資料庫從 PITR 資料匯出至 Cloud Storage。您可以匯出時間戳記為過去七天內整分鐘時間戳記的 PITR 資料，但不得早於 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'。

   匯出 PITR 資料前，請注意下列事項：

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

2. 匯入資料庫。

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