本頁面說明如何使用 Google Cloud Platform 主控台和 Google Cloud CLI 設定存留時間 (TTL) 政策。閱讀本頁之前,請先瞭解 Cloud Firestore 資料模型。
存留時間總覽
您可以運用存留時間政策,自動移除資料庫中過時的資料。存留時間政策會將特定欄位指定為指定集合群組中文件的到期時間。透過存留時間,您可以清除過時資料來降低儲存空間費用。通常會在到期日後的 24 小時內刪除資料。
定價
存留時間刪除作業會計入文件刪除費用。如需刪除作業的定價資訊,請參閱 Cloud Firestore 定價。
限制和限制
- 每個集合群組只能有一個欄位標示為「存留時間」欄位,
- 最多允許 200 個欄位層級設定。一個欄位設定可以包含相同欄位的多項設定。舉例來說,如果單一欄位的索引豁免項目和同一個欄位的存留時間政策,就會視為一項欄位設定計入限制。
- 針對 Datastore 模式的 Firestore 客戶,TTL 無法與「Optimistic With 實體群組」並行模式搭配使用。建議將並行模式變更為「最佳化並行模式」。
刪除存留時間
請注意,以存留時間為準刪除作業的主要行為包括:
透過存留時間刪除資料不會立即執行,過期的文件會繼續顯示在查詢和查詢要求中,直到存留時間程序確實刪除到期的文件。存留時間改變刪除時程,有利於減少刪除作業的總持有成本。通常會在到期日後的 24 小時內刪除資料。
透過存留時間刪除文件不會刪除該文件下的子集合。
如果對現有集合群組套用存留時間政策,則會根據新的存留時間政策,大量刪除所有過期資料。請注意,這類大量刪除並不會立即刪除,具體取決於該集合群組中有多少資料。
如果文件設有過去的到期時間,而您在集合中新增存留時間政策,則該文件會在存留時間政策設定完成且生效後的 24 小時內刪除。
存留時間不一定會按照到期日時間戳記的順序刪除文件。
刪除作業並非透過交易完成。具有相同到期時間的文件不一定會同時刪除。如果您需要此行為,請使用用戶端程式庫執行刪除作業。
Cloud Firestore 一律會遵循最新的「TTL」欄位來判斷到期時間。例如,如果過期但尚未刪除的文件存留時間欄位更新為較晚的日期,該文件將不會過期,並使用新的日期。
存留時間是設計來盡量減少對其他資料庫活動的影響。系統會將存留時間的刪除作業視為較低的優先順序。另外,其他策略也能透過存留時間導向的刪除作業順利排除流量高峰。
透過存留時間執行刪除作業時,系統會呼叫所有有效的快照事件監聽器,並觸發 Cloud Functions Cloud Firestore 觸發條件。
存留時間欄位與索引
TTL 欄位可以建立索引或未建立索引。不過,由於存留時間欄位是時間戳記,為欄位建立索引可能會影響流量的速率。為時間戳記欄位建立索引可能會建立熱點,這屬於最佳做法。互動區是高讀取、寫入和刪除頻率,且剛好在小文件範圍內。
根據預設,Cloud Firestore 會為所有欄位建立單一欄位索引。您可以建立單一欄位索引豁免設定,藉此停用存留時間欄位的索引。
權限
設定存留時間政策的主體必須具備專案中的下列權限:
- 查看存留時間政策需要
datastore.indexes.list
和datastore.indexes.get
權限。 - 修改存留時間政策必須具備
datastore.indexes.update
權限。 - 需要
datastore.operations.list
和datastore.operations.get
才能檢查存留時間作業的狀態。
如要瞭解指派這些權限的角色,請參閱 Cloud Firestore Identity and Access Management 角色。
事前準備
使用 gcloud CLI 管理存留時間政策之前,請先使用 gcloud components update
指令將元件更新為最新可用版本:
gcloud components update
建立存留時間政策
建立存留時間政策時,您可以為集合群組中的文件指定文件欄位做為到期時間。
存留時間會使用特定欄位找出符合刪除條件的文件。
這個 TTL 欄位必須為 Date and time
類型。您可以選取現有的欄位,也可以指定預計稍後新增的欄位。
設定 TTL 欄位值前,請考量以下事項:
TTL 欄位的值可以是未來、現在或過去的時間。如果值是過去的時間,則文件會立即符合刪除資格。舉例來說,您可以建立使用
expireAt
欄位的存留時間政策,然後將該政策新增至現有文件。如果您使用任何其他資料類型或未設定「TTL」欄位值,個別文件的存留時間就會停用。
如要建立存留時間政策,請按照下列步驟操作:
Google Cloud 控制台
在 Google Cloud Platform Console 中,前往「Databases」頁面。
從資料庫清單中選取所需的資料庫。
在導覽選單中,按一下「存留時間」。
點按「建立政策」。
輸入集合群組名稱和時間戳記欄位名稱。
點選「Create」(建立)。
控制台就會返回「存留時間」頁面。如果作業成功啟動,頁面會在存留時間政策表格中新增項目。失敗時,頁面會顯示錯誤訊息。
gcloud
使用 firestore fields ttls
update
指令設定存留時間政策。新增 --async
標記可避免 gcloud CLI 等待作業完成。
gcloud firestore fields ttls update ttl_field --collection-group=collection_group_name --enable-ttl
存留時間政策啟用時長
即使在空白資料庫上,啟用存留時間政策可能需要十分鐘以上。啟動作業後,關閉終端機並不會取消作業。
查看存留時間政策
如要查看存留時間政策及其狀態,請按照下列步驟操作:
Google Cloud 控制台
在 Google Cloud Platform Console 中,前往「Databases」頁面。
從資料庫清單中選取所需的資料庫。
在導覽選單中,按一下「存留時間」。
控制台會列出資料庫的存留時間政策,並顯示每項政策的狀態。
gcloud
使用 firestore fields ttls list
指令設定存留時間政策。下列指令會列出所有存留時間政策。
gcloud firestore fields ttls list
如要列出特定集合群組下的存留時間政策,請按照下列步驟操作:
gcloud firestore fields ttls list --collection-group=collection_group_name
查看作業詳細資料
您可以使用 gcloud CLI 查看狀態為 CREATING
的存留時間政策相關詳細資料。
使用 operations list
指令查看所有執行中和最近完成的作業:
gcloud firestore operations list
回應會包含作業進度的預估結果。
停用存留時間政策
如要停用存留時間政策,請按照下列步驟操作:
Google Cloud 控制台
在 Google Cloud Platform Console 中,前往「Databases」頁面。
從資料庫清單中選取所需的資料庫。
在導覽選單中,按一下「存留時間」。
在存留時間政策表格中,找出存留時間政策的資料列。在這個表格列中,按一下「Delete」(刪除) (垃圾桶) 按鈕。
按一下「刪除」確認這項操作。
控制台就會返回「存留時間」頁面。成功之後,Cloud Firestore 會移除資料表中的存留時間政策。
gcloud
1. 使用 firestore fields ttls update
指令設定存留時間政策。新增 --async
標記可避免 gcloud CLI 等待作業完成。
gcloud firestore fields ttls update ttl_field --collection-group=collection_group_name --disable-ttl
監控存留時間刪除作業
您可以使用 Cloud Monitoring 查看以存留時間為準刪除作業的指標。Cloud Firestore 提供下列存留時間指標:
指標類型 | 指標名稱 | 指標說明 |
---|---|---|
firestore.googleapis.com/document/ttl_deletion_count | 存留時間 (TTL) 的刪除次數 |
依存留時間政策刪除的文件總數。 |
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays | 延遲時間的存留時間 (TTL) 已延遲 |
文件在存留時間政策 (依存留時間政策) 規定到實際刪除之間經過的時間。 |
如要設定含有 Cloud Firestore 指標的資訊主頁,請參閱管理自訂資訊主頁及新增資訊主頁小工具。