本頁面介紹如何使用時間點復原 (PITR) 在 Cloud Firestore 中保留和復原資料。
若要了解 PITR 概念，請參閱時間點恢復。
權限
若要取得管理 PITR 設定所需的權限，請要求您的管理員在您要啟用 PITR 的專案上授予您以下 IAM 角色：
- 雲端資料儲存擁有者 (
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 後，您無法立即開始閱讀過去 7 天的內容。
- 如果您想在建立資料庫時啟用 PITR，則必須使用
gcloud firestore databases create指令。不支援在使用 GCP Console 建立資料庫時啟用 PITR。 - 啟用 PITR 後，Cloud Firestore 開始保留版本。
- 停用 PITR 後，您將無法在 PITR 視窗中讀取 PITR 資料。
- 如果在停用 PITR 後立即重新啟用 PITR，則過去的 PITR 資料將不再可用。在停用 PITR 之前建立的任何 PITR 資料都將在 PITR 到期日期後刪除。
- 如果您在過去一小時內意外刪除了資料並且停用了 PITR，您可以在刪除後一小時內啟用 PITR 來恢復資料。
- 對過期 PITR 資料執行的任何讀取都會失敗。
啟用 PITR
在使用 PITR 之前，請為您的 Google Cloud 專案啟用結算功能。只有啟用了結算功能的 Google Cloud 專案才能使用 PITR 功能。
若要為您的資料庫啟用 PITR：
安慰
在 Google Cloud Platform Console 中，前往資料庫頁面。
從資料庫清單中選擇所需的資料庫。
在導覽功能表中，按一下災難復原。
點擊編輯以編輯設定。
選取啟用時間點恢復複選框，然後按一下儲存。
啟用 PITR 會產生儲存成本。請參閱定價以了解更多資訊。
若要停用 PITR，請從 GCP Console 的災難復原頁面中清除啟用時間點復原複選框。
雲雲
使用gcloud firestore databases create指令在建立資料庫期間啟用 PITR，如下所示：
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指令來停用 PITR，如下所示：
gcloud firestore databases update\
[--database=DATABASE_ID; default="(default)"]\
--no-enable-pitr
替換值如下：
-
DATABASE_ID- 設定為資料庫 ID 或（預設）。
取得保留期限和最早版本時間
安慰
在 Google Cloud Platform Console 中，前往資料庫頁面。
從資料庫清單中選擇所需的資料庫。
在導覽功能表中，按一下災難復原。
在「設定」部分中，記下「保留期」和「最早版本時間」 。
- 保留期：Cloud Firestore 保留資料庫所有版本資料的期限。停用 PITR 時該值為 1 小時，啟用 PITR 時該值為 7 天。
- 最早版本時間：可以在 PITR 視窗中讀取舊版本資料的最早時間戳記。該值由 Cloud Firestore 不斷更新，並在查詢時變得過時。如果您使用此值來恢復數據，請確保考慮從查詢該值到啟動恢復的時間。
- 時間點復原：如果啟用了 PITR，則顯示
Enabled。如果 PITR 被停用，您將看到Disabled。
雲雲
運行gcloud firestore 資料庫描述指令，如下所示：
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- 儲存的最早 PITR 資料的時間戳記。 -
pointInTimeRecoveryEnablement：如果啟用 PITR，則顯示POINT_IN_TIME_RECOVERY_ENABLED。如果停用 PITR，您將看到POINT_IN_TIME_RECOVERY_DISABLED，或者可能不會顯示pointInTimeRecoveryEnablement欄位。 -
versionRetentionPeriod- 保留 PITR 資料的時間段（以毫秒為單位）。如果停用 PITR，則該值可以為一小時；如果啟用 PITR，則該值可以為 7 天。
讀取 PITR 數據
您可以使用客戶端程式庫、REST API 方法或 FirestoreIO Apache Beam 連接器讀取 PITR 資料。
客戶端庫
爪哇
您必須使用ReadOnly事務來讀取 PITR 資料。不能直接在reads中指定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事務來讀取 PITR 資料。不能直接在reads中指定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)}
)
休息API
所有 Cloud Firestore 讀取方法都支援 PITR 讀取，這些方法包括get 、 list 、 batchGet 、 listCollectionIds 、 listDocuments 、 runQuery 、 runAggregationQuery和partitionQuery 。
若要使用 REST 方法執行讀取，請嘗試以下選項之一：
在您的讀取方法請求中，將
readTime值作為readOptions方法中支援的 PITR 時間戳進行傳遞。 PITR 時間戳可以是過去一小時內的微秒精度時間戳，也可以是過去一小時之後的整分鐘時間戳，但不能早於earliestVersionTime。將
readTime參數與BeginTransaction方法一起使用作為多個 PITR 讀取的ReadOnly事務的一部分。
阿帕契光束
使用 Cloud FirestoreIO Apache Beam 連接器透過 Dataflow 大規模讀取或寫入 Cloud Firestore 資料庫中的文件。
Cloud FirestoreIO 連接器的以下讀取方法支援 PITR 讀取。這些讀取方法支援withReadTime(@Nullable Instant readTime)方法，您可以將其用於 PITR 讀取：
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
爪哇
以下程式碼可與範例資料流管道程式碼一起使用以進行批次讀取或寫入操作。此範例使用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指令將資料庫從 PITR 資料匯出到 Cloud Storage。您可以匯出 PITR 數據，其中時間戳記是過去 7 天內的整分鐘時間戳，但不能早於earliestVersionTime 。如果指定時間戳不再存在數據，則匯出操作失敗。
PITR導出操作支援所有篩選器，包括所有文件的匯出和特定集合的匯出。
匯出資料庫，將
snapshot-time參數指定為所需的復原時間戳記。雲雲
執行以下命令將資料庫匯出到您的儲存桶。
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。 - 確保您指定的時間戳記是過去 7 天內的整分鐘時間戳，但不早於
earliestVersionTime。如果指定時間戳不再存在數據，則會產生錯誤。即使指定時間在過去一小時內，時間戳也必須是整分鐘。 - 您無需為失敗的 PITR 匯出付費。
-
導入到資料庫。
使用匯入所有文件中的步驟匯入已匯出的資料庫。如果資料庫中已存在任何文檔，它將被覆蓋。