本頁面說明如何使用時間點復原 (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),必須使用
gcloud firestore databases create
指令。透過 GCP 主控台建立資料庫時,不支援啟用時間點復原功能。 - Cloud Firestore 會在您啟用時間點復原後開始保留版本。
- 停用時間點復原功能之後,您就無法在時間點復原 (PITR) 視窗中讀取時間點復原資料。
- 如果您在停用時間點復原 (PITR) 功能之後立即重新啟用,就無法使用過去的時間點復原資料。任何在停用時間點復原前建立的時間點復原資料都會在時間點復原 (PITR) 到期日之後刪除。
- 如果您不小心刪除了過去 1 小時內的資料,而且已停用 PITR,則只要在刪除資料的一小時內啟用時間點復原功能,即可還原資料。
- 對過期的時間點復原 (PITR) 資料執行所有讀取作業都會失敗。
啟用時間點復原功能
使用時間點復原工具前,請先為 Google Cloud 專案啟用計費功能。只有啟用帳單功能的 Google Cloud 專案才能使用時間點復原功能。
如何為資料庫啟用時間點復原功能:
控制台
在 Google Cloud Platform Console 中,前往「Databases」頁面。
從資料庫清單中選取所需的資料庫。
在導覽選單中,按一下「災難復原」。
按一下「編輯」即可編輯設定。
勾選「啟用時間點復原」核取方塊,然後按一下「儲存」。
啟用時間點復原功能會產生儲存空間費用。詳情請參閱定價。
如要停用時間點復原功能,請在 GCP 控制台的「災難復原」頁面中,取消勾選「啟用時間點復原」核取方塊。
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 或 (預設)。
取得保留期限和最早版本時間
控制台
在 Google Cloud Platform Console 中,前往「Databases」頁面。
從資料庫清單中選取所需的資料庫。
在導覽選單中,按一下「災難復原」。
在「設定」部分,記下「保留期限」和「最早版本時間」。
- 保留期限:Cloud Firestore 為資料庫保留所有版本資料的時間範圍。這個值為停用時間點復原功能時的一小時,值是啟用時間點復原功能時七天。
- 最早版本時間:最早可以在 PITR 視窗中讀取舊版資料的時間時間戳記。Cloud Firestore 會持續更新這個值,且會在查詢時過時。如果您使用這個值復原資料,請務必考量從「完成」復原當下查詢該值的時間。
- 時間點復原:如果已啟用時間點復原功能,會顯示
Enabled
。如果 PITR 已停用,則會顯示Disabled
。
gcloud
按照以下方式執行 gcloud Firestore libraries 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
- 最早儲存的時間點復原資料時間戳記。pointInTimeRecoveryEnablement
:如果啟用時間點復原功能,會顯示POINT_IN_TIME_RECOVERY_ENABLED
。如果 PITR 已停用,您會看到POINT_IN_TIME_RECOVERY_DISABLED
或pointInTimeRecoveryEnablement
欄位可能未顯示。versionRetentionPeriod
- 時間點復原資料保留的時間範圍 (以毫秒為單位)。這個值可能是在 PITR 停用時設為一小時,如果啟用了時間點復原功能,則該值可能是 7 天。
讀取時間點復原資料
您可以使用用戶端程式庫、REST API 方法或 FirestoreIO Apache Beam 連接器來讀取 PITR 資料。
用戶端程式庫
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 方法執行讀取作業,請嘗試下列其中一種選項:
在讀取方法要求中,在
readOptions
方法中,將readTime
值做為支援的時間點復原時間戳記傳遞。時間點復原時間戳記可以是過去 1 小時內的微秒精確度時間戳記,或是超過過去一小時的整分鐘時間戳記,但早於earliestVersionTime
。針對多次 PITR 讀取作業,在
ReadOnly
交易中搭配使用readTime
參數和BeginTransaction
方法。
Apache Beam
使用 Cloud FirestoreIO Apache Beam 連接器,透過 Dataflow 以大規模的 Cloud Firestore 資料庫讀取或寫入文件。
下列 Cloud FirestoreIO 連接器的讀取方法支援 PITR 讀取功能。下列讀取方法支援可用於 PITR 讀取的 withReadTime(@Nullable Instant readTime)
方法:
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
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
指令,從時間點復原資料將資料庫匯出至 Cloud Storage。您可以匯出時間點復原資料,其中時間戳記是過去七天內 (但不得早於 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
:以分鐘為單位的時間點復原時間戳記,例如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
。如果資料不再存在於指定的時間戳記,就會產生錯誤。時間戳記必須是整數,即使指定時間是過去一小時內也一樣。 - 系統不會向您收取時間點復原匯出失敗的費用。
匯入資料庫。
按照匯入所有文件中的步驟匯入匯出的資料庫。如果資料庫中已有文件,系統就會覆寫該文件。