本頁面說明如何使用時間點復原 (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
事前準備
開始使用時間點復原功能前,請注意下列事項:
- 你無法在 啟用時間點復原功能。
- 如果您想在建立資料庫時啟用時間點復原功能,則必須使用
gcloud firestore databases create
指令。在以下情況下啟用時間點復原功能 不支援使用 Google Cloud 控制台建立資料庫 - Cloud Firestore會從以下日期後開始保留版本: 啟用時間點復原功能。
- 停用時間點復原功能後,就無法在時間點復原 (PITR) 視窗中讀取時間點復原資料。
- 如果您在停用時間點復原 (PITR) 功能之後立即重新啟用,系統會提供先前的時間點復原資料 已不再提供。您在停用時間點復原功能前建立的任何時間點復原資料,都會 在時間點復原週期後刪除。
- 如果過去 1 小時內不小心刪除資料,並停用了時間點復原功能, 只要在資料刪除後的一小時內啟用時間點復原功能,即可還原資料。
- 對過期的時間點復原 (PITR) 資料執行所有讀取作業都會失敗。
啟用時間點復原功能
使用時間點復原工具前,請先為 Google Cloud 啟用計費功能 專案。 只有啟用帳單功能的 Google Cloud 專案才能使用時間點復原功能。
如何為資料庫啟用時間點復原功能:
主控台
前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。
從資料庫清單中選取所需的資料庫。
在導覽選單中,按一下「災難復原」。
按一下「編輯」即可編輯設定。
勾選「啟用時間點復原」核取方塊,然後按一下「儲存」。
啟用時間點復原功能會產生儲存空間費用。詳情請參閱定價。
如要停用時間點復原功能,請在 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 或 (預設)。
取得保留期限和最早版本時間
主控台
前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。
從資料庫清單中選取所需的資料庫。
在導覽選單中,按一下「災難復原」。
在「設定」部分,記下「保留期限」和「最早版本時間」。
- 保留期限:Cloud Firestore保留的時間範圍 資料庫的所有資料版本當 PITR 等於 停用時,當啟用時間點復原功能時,也會自動停用七天。
- 最早版本時間:最早的時間戳記 可在時間點復原 (PITR) 視窗中讀取資料這個值會持續更新 由 Cloud Firestore 觸發,且在查詢時已過時。如果發生以下情況: 並使用這個值復原資料,請務必考量 您啟動 以及災難復原
- 時間點復原:如果為時間點復原,會顯示
Enabled
。 如果時間點復原功能已停用,你會看到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
(如果時間點復原) 如果時間點復原功能處於停用狀態,系統會顯示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 連接器。這些讀取方法支援
可用於時間點復原的 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) 資料匯出及匯入
您可以將資料庫從時間點復原 (PITR) 資料匯出至 Cloud Storage
呼叫 gcloud firestore export
指令您可以匯出時間點復原資料,時間戳記是指時間戳記在
過去 7 天,但早於 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
。如果指定的資料已不存在 時間戳記,就會產生錯誤。時間戳記必須是整數,即使指定時間是過去一小時內也一樣。 - 系統不會向您收取時間點復原匯出失敗的費用。
匯入資料庫。
按照「匯入所有文件」一文中的步驟匯入 以及匯出的資料庫如果資料庫中已有文件 。