使用時間點復原 (PITR)

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

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

權限

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

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

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

事前準備

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

• 啟用 PITR 後，您無法立即開始讀取七天前的資料。
• 如要在建立資料庫時啟用 PITR，請務必使用 gcloud firestore databases create 指令。使用 Google Cloud 主控台建立資料庫時，不支援啟用 PITR。
• 啟用 PITR 後，Firestore 會開始保留版本。
• 停用 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。您可以匯出時間戳記為過去七天內整分鐘的時間點復原資料，但不得早於 earliestVersionTime。如果指定時間戳記的資料已不存在，匯出作業就會失敗。

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

1. 匯出資料庫，並將 snapshot-time 參數指定為所選復原時間戳記。

   gcloud

   執行下列指令，將資料庫匯出至 bucket。

   gcloud firestore export gs://BUCKET_NAME_PATH \
       --snapshot-time=PITR_TIMESTAMP \
       --collection-ids=COLLECTION_IDS \
       --namespace-ids=NAMESPACE_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'。
   • 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. 匯入資料庫。

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