使用時間點復原 (PITR)

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

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

權限

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

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

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

事前準備

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

• 啟用 PITR 後，您無法立即開始讀取七天前的資料。
• 如要在建立資料庫時啟用 PITR，請務必使用 gcloud firestore databases create 指令。使用 Google Cloud 主控台建立資料庫時，不支援啟用 PITR。
• 啟用 PITR 後，Datastore 模式會開始保留版本。
• 停用 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/(default)
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: DATASTORE_MODE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

讀取 PITR 資料

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

  Datastore datastore = ...
  Timestamp timestamp = ...

  // lookup
  Key key = ...
  Entity entity = datastore.get(key, ReadOption.readTime(timestamp));

  // runQuery
  Query<Entity> query = ...
  QueryResults<Entity> queryResult = datastore.run(query, ReadOption.readTime(timestamp));

  // runAggregationQuery
  AggregationQuery countAggregationQuery = ...
  Long count = getOnlyElement(datastore.runAggregation(countAggregationQuery, ReadOption.readTime(timestamp))).get("total_count");

  from datetime import datetime, timezone

  read_time = datetime.now(tz=timezone.utc)

  key = …
  # read without PITR read time
  entity = client.get(key)

  # read with PITR read time
  entity = client.get(key, read_time=read_time)

  # PITR read using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      entity = client.get(key)

  query = client.query…
  # run query without PITR read time
  iterator = query.fetch()

  # run query with PITR read time
  iterator = query.fetch(read_time=read_time)

  # PITR read query using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      iterator = query.fetch()

  com.google.datastore.v1.Query query = ...
    Instant readTime = Instant.ofEpochSecond(1684098540L);

    DatastoreV1.Read read =
            DatastoreIO.v1()
                .read()
                .withProjectId(project)
                .withQuery(query)
                .withNamespace(namespace)
                .withReadTime(readTime);

    PCollection<Entity> entities = pipeline.apply(read);
    ...

從 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。
   • 請確認指定的時間戳記是過去 7 天內的整分鐘時間戳記，但不得早於 earliestVersionTime。如果指定時間戳記的資料已不存在，系統會顯示錯誤訊息。即使指定時間在過去一小時內，時間戳記也必須是整分鐘。
   • 如果 PITR 匯出作業失敗，系統不會向您收費。

2. 匯入資料庫。

   按照「匯入所有實體」一節中的步驟匯入匯出的資料庫。如果資料庫中已有任何實體，系統會覆寫該實體。系統也支援使用實體篩選器匯入部分特定種類及/或命名空間。