運用存留時間政策管理資料保留設定

本頁面說明如何使用 Google Cloud 主控台和 Google Cloud CLI 設定時間到期 (TTL) 政策。閱讀本頁面之前,請先瞭解 Cloud Firestore 資料模型

存留時間總覽

使用 TTL 政策,自動移除資料庫中的過時資料。存留時間政策會將特定欄位指定為特定集合群組中文件的到期時間。您可以透過 TTL 清除過時的資料,降低儲存空間成本。通常會在到期日後的 24 小時內刪除資料。

定價

TTL 刪除作業會計入文件刪除費用。如要瞭解刪除作業的定價,請參閱 Cloud Firestore 定價

限制

  • 每個集合群組只能標示一個欄位為 TTL 欄位。
  • 您最多可以設定 200 個欄位層級設定。一個欄位設定可包含相同欄位的多個設定。舉例來說,如果單一欄位索引豁免設定和同一個欄位的 TTL 政策都計入限制,就會造成一個欄位設定。
  • 對於 Datastore 模式的 Firestore 客戶,存留時間無法與 Optimistic With Entity Groups 並行模式搭配使用。建議您將並行模式變更為樂觀並行模式

刪除存留時間

請注意 TTL 驅動刪除作業的下列重要行為:

  • 透過 TTL 刪除並非即時程序,過期文件會持續顯示在查詢和查閱要求中,直到 TTL 程序實際刪除這些文件為止。存留時間可讓您在刪除時程和刪除作業的總持有成本之間取得平衡。通常會在到期日後的 24 小時內刪除資料。

  • 透過 TTL 刪除文件時,系統不會刪除該文件下的子集合。

  • 在現有集合群組上套用存留時間政策後,系統會根據新存留時間政策大量刪除所有過期資料。請注意,這項大量刪除作業並非立即完成,實際時間取決於該收集群組的資料量。

  • 如果文件的到期時間已過,而您在集合中新增了新的 TTL 政策,系統會在 TTL 政策完成設定並生效後的 24 小時內刪除該文件。

  • TTL 不一定會按照文件到期時間戳記的順序刪除文件。

  • 刪除作業不會以交易方式執行。具有相同到期時間的文件不一定會在同一時間刪除。如果需要這種行為,請使用用戶端程式庫執行刪除作業。

  • Cloud Firestore 一律會使用最新的 TTL 欄位來判斷到期日。舉例來說,如果已過期但尚未刪除的文件,其 TTL 欄位更新為較晚的日期,則文件不會過期,系統會使用新日期。

  • TTL 的設計目的是盡量降低對其他資料庫活動的影響。系統會以較低的優先順序處理 TTL 觸發的刪除作業。我們也採用其他策略,以便平滑因 TTL 驅動刪除作業而造成的流量尖峰。

  • 透過 TTL 刪除會呼叫所有有效的快照監聽器,並觸發 Cloud Functions Cloud Firestore 觸發條件。

存留時間欄位和索引

存留時間欄位可以建立索引,也可以不建立索引。不過,由於 TTL 欄位是時間戳記,因此為該欄位建立索引可能會影響較高流量率的效能。為時間戳記欄位建立索引可能會產生熱點,這違反最佳做法。熱點是指讀取、寫入和刪除頻率高的狹小文件範圍。

根據預設,Cloud Firestore 會為所有欄位建立單一欄位索引。您可以建立單一欄位索引豁免設定,停用 TTL 欄位的索引。

權限

設定存留時間政策的使用者必須具備專案中的下列權限:

  • 您必須具備 datastore.indexes.listdatastore.indexes.get 權限,才能查看 TTL 政策。
  • 您必須具備 datastore.indexes.update 權限,才能修改 TTL 政策。
  • 您必須使用 datastore.operations.listdatastore.operations.get 才能查看 TTL 作業的狀態。

如要瞭解指派這些權限的角色,請參閱 Cloud Firestore 身分與存取權管理角色

事前準備

在使用 gcloud CLI 管理 TTL 政策之前,請使用 gcloud components update 指令將元件更新至最新可用版本:

gcloud components update

建立存留時間政策

建立存留時間政策時,您可以指定文件欄位做為集合群組中文件的到期時間。

TTL 會使用指定的欄位,識別可刪除的文件。這個 TTL 欄位必須是 Date and time 類型。您可以選取現有的欄位,也可以指定日後要新增的欄位。

設定 TTL 欄位值前,請考量以下事項:

  • TTL 欄位值可以是未來、現在或過去的時間。如果值是過去的時間,則文件即可立即刪除。舉例來說,您可以使用 expireAt 欄位建立 TTL 政策,然後新增至現有文件。

  • 使用任何其他資料類型或未設定 TTL 欄位值,都會停用個別文件的 TTL。

如要建立 TTL 政策,請按照下列步驟操作:

Google Cloud Console

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」

  2. 從資料庫清單中選取必要資料庫。

  3. 在導覽選單中,按一下「Time-to-live」(生命週期)

  4. 點選「建立政策」

  5. 輸入收集群組名稱和時間戳記欄位名稱。

  6. 按一下「建立」

控制台會返回「Time-to-live」頁面。如果作業順利啟動,頁面會在 TTL 政策表格中新增項目。如果失敗,頁面會顯示錯誤訊息。

gcloud

使用 firestore fields ttls update 指令設定 TTL 政策。新增 --async 標記,避免 gcloud CLI 為了等待作業完成而停頓。

 gcloud firestore fields ttls update
  ttl_field --collection-group=collection_group_name
  --enable-ttl 

存留時間政策啟用期間

即使資料庫為空白,啟用 TTL 政策也可能需要十分鐘以上。啟動作業後,關閉終端機不會取消作業。

查看存留時間政策

如要查看 TTL 政策及其狀態,請按照下列步驟操作:

Google Cloud Console

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」

  2. 從資料庫清單中選取必要資料庫。

  3. 在導覽選單中,按一下「Time-to-live」(生命週期)

控制台會列出資料庫的 TTL 政策,並附上每項政策的狀態。

gcloud

使用 firestore fields ttls list 指令設定 TTL 政策。下列指令會列出所有 TTL 政策。

   gcloud firestore fields ttls list
   

如要列出特定集合群組下的 TTL 政策,請使用以下指令:

   gcloud firestore fields ttls list  --collection-group=collection_group_name
   

查看作業詳細資料

您可以使用 gcloud CLI 查看 TTL 政策的更多詳細資料,瞭解其處於 CREATING 狀態。

使用 operations list 指令查看所有執行中和最近完成的作業:

gcloud firestore operations list

回應中會包含作業進度的預估值。

停用存留時間政策

如要停用 TTL 政策,請按照下列步驟操作:

Google Cloud Console

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」

  2. 從資料庫清單中選取必要資料庫。

  3. 在導覽選單中,按一下「Time-to-live」(生命週期)

  4. 在存留時間政策表格中,找出存留時間政策的資料列。在這個資料表列中,按一下「刪除」 (垃圾桶) 按鈕。

  5. 按一下「刪除」確認。

控制台會返回「Time-to-live」頁面。如果成功,Cloud Firestore 會從表格中移除 TTL 政策。

gcloud

1. 使用 firestore fields ttls update 指令設定 TTL 政策。新增 --async 標記,避免 gcloud CLI 為了等待作業完成而停頓。

   gcloud firestore fields ttls update ttl_field --collection-group=collection_group_name --disable-ttl
   

監控存留時間刪除作業

您可以使用 Cloud Monitoring 查看 TTL 驅動刪除作業的指標。Cloud Firestore 提供下列 TTL 指標:

指標類型 指標名稱 指標說明
firestore.googleapis.com/document/ttl_deletion_count 存留時間刪除計數

存留時間政策刪除的文件總數。

firestore.googleapis.com/document/ttl_expiration_to_deletion_delays 存留時間到期到刪除的延遲時間

文件在 TTL 政策到期後,實際刪除前所經過的時間。

如要設定含有 Cloud Firestore 指標的資訊主頁,請參閱「管理自訂資訊主頁」和「新增資訊主頁小工具」。