本頁說明如何使用物件保留鎖定功能,包括為值區啟用這項功能,以及為值區中的物件設定保留設定。
必要的角色
如要取得啟用值區物件保留鎖定功能,以及在物件上設定保留設定所需的權限,請要求管理員在值區或包含該值區的專案中,授予您「Storage 管理員」身分與存取權管理 (IAM) 角色 (roles/storage.admin
)。這個預先定義的角色具備設定及管理保留設定所需的權限。如要查看確切的必要權限,請展開「必要權限」部分:
所需權限
storage.buckets.create
storage.buckets.enableObjectRetention
storage.buckets.get
storage.buckets.list
- 如果您打算使用Google Cloud 控制台執行本頁的操作說明,才需要這項權限。
storage.objects.get
storage.objects.list
- 如果您打算使用Google Cloud 控制台執行本頁的操作說明,才需要這項權限。
storage.objects.overrideUnlockedRetention
- 只有在打算鎖定或縮短現有保留設定時,才需要這項權限。
storage.objects.setRetention
storage.objects.update
您或許還可透過自訂角色取得這些權限。
如要瞭解如何授予值區角色,請參閱「搭配值區使用 IAM」。如要瞭解如何授予專案角色,請參閱「管理專案存取權」。
啟用值區的物件保留功能
請按照下列操作說明,為值區中的物件啟用保留設定。如要為現有 bucket 啟用物件保留設定,請按照 Google Cloud 控制台操作說明操作。
控制台
為新值區啟用物件保留設定:
- 如常建立值區,並在「選擇保護物件資料的方式」步驟中,依序選取「保留 (符合法規)」和「啟用物件保留」。
為現有 bucket 啟用物件保留設定:
- 在 Google Cloud 控制台,前往「Cloud Storage bucket」頁面。
在 bucket 清單中,點選要啟用物件保留功能的 bucket 名稱。
選取頁面頂端的「保護」分頁標籤。
值區的物件保留狀態會顯示在「物件保留」部分。
在「物件保留」專區中,按一下「物件保留功能未啟用」。
在隨即顯示的對話方塊中,按一下「確認」。
指令列
照常建立 bucket,並在指令中加入 --enable-per-object-retention
旗標。
用戶端程式庫
C++
詳情請參閱 Cloud Storage C++ API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
C#
詳情請參閱 Cloud Storage C# API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
詳情請參閱 Cloud Storage Java API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
詳情請參閱 Cloud Storage Node.js API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
PHP
詳情請參閱 Cloud Storage PHP API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
詳情請參閱 Cloud Storage Python API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
REST API
查看值區的物件保留狀態
如要查看是否可以為值區中的物件設定保留設定:
控制台
- 在 Google Cloud 控制台,前往「Cloud Storage bucket」頁面。
按一下要檢查狀態的值區名稱。
按一下「保護」分頁標籤。
值區的物件保留狀態會顯示在「物件保留」部分。
指令列
使用加上 --format
旗標的 gcloud storage buckets describe
指令:
gcloud storage buckets describe gs://BUCKET_NAME --format="default(per_object_retention)"
其中 BUCKET_NAME
是您要查看保留政策的值區名稱。例如:my-bucket
。
如果成功,且值區有保留政策,回應會類似以下內容:
per_object_retention: mode: Enabled
如果成功,且值區沒有保留政策,回應會類似以下內容:
null
用戶端程式庫
C++
詳情請參閱 Cloud Storage C++ API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看 bucket 的物件保留設定,請按照顯示 bucket 中繼資料的操作說明進行,並在回應中尋找物件保留欄位。C#
詳情請參閱 Cloud Storage C# API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看 bucket 的物件保留設定,請按照顯示 bucket 中繼資料的操作說明進行,並在回應中尋找物件保留欄位。Java
詳情請參閱 Cloud Storage Java API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看 bucket 的物件保留設定,請按照顯示 bucket 中繼資料的操作說明進行,並在回應中尋找物件保留欄位。Node.js
詳情請參閱 Cloud Storage Node.js API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看 bucket 的物件保留設定,請按照顯示 bucket 中繼資料的操作說明進行,並在回應中尋找物件保留欄位。PHP
詳情請參閱 Cloud Storage PHP API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看 bucket 的物件保留設定,請按照顯示 bucket 中繼資料的操作說明進行,並在回應中尋找物件保留欄位。Python
詳情請參閱 Cloud Storage Python API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看 bucket 的物件保留設定,請按照顯示 bucket 中繼資料的操作說明進行,並在回應中尋找物件保留欄位。REST API
JSON API
安裝並初始化 gcloud CLI,以便為
Authorization
標頭產生存取權杖。使用
cURL
透過包含objectRetention
欄位的GET
Bucket 要求呼叫 JSON API:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=objectRetention"
其中
BUCKET_NAME
是相關值區的名稱。例如:my-bucket
。
XML API
安裝並初始化 gcloud CLI,以便為
Authorization
標頭產生存取權杖。使用
cURL
透過GET
值區要求 (範圍為?object-lock
) 呼叫 XML API:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?object-lock"
其中
BUCKET_NAME
是相關值區的名稱。例如:my-bucket
。
設定物件的保留設定
如要為物件設定保留設定,物件必須儲存在已啟用物件保留功能的值區中。如要為物件設定保留設定,請按照下列步驟操作:
控制台
- 在 Google Cloud 控制台,前往「Cloud Storage bucket」頁面。
在值區清單中,按一下包含要設定或修改保留設定物件的值區名稱。
系統會開啟「Bucket details」(值區詳細資料) 頁面,並選取「Objects」(物件) 分頁標籤。
前往物件,該物件可能位於資料夾中。
按一下物件名稱。
「物件詳細資料」頁面隨即開啟,顯示物件中繼資料。
在「保護」部分中,按一下「從物件保留設定」相關的「編輯」圖示 (edit)。
「編輯保留期限」窗格隨即開啟。
在「物件保留設定」部分,按一下「已啟用」或「已停用」。
- 如果已啟用保留設定,請在「保留期限」部分選取設定的日期和時間,然後在「保留模式」部分點選「解除鎖定」或「鎖定」。
按一下「確認」。
指令列
使用 gcloud storage objects update
指令並加上適當的旗標。如要新增或修改保留設定,請使用下列指令。請注意,如果您修改現有設定,導致設定遭到鎖定或保留時間縮短,則必須額外加入 --override-unlocked-retention
標記:
gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --retain-until=DATETIME --retention-mode=STATE
其中:
BUCKET_NAME
是相關值區的名稱。例如:my-bucket
。OBJECT_NAME
是相關物件的名稱。例如:kitten.png
。DATETIME
是最早可刪除物件的日期和時間。例如:2028-02-15T05:30:00Z
。STATE
是Locked
或Unlocked
。
如果成功,回應會類似以下範例:
Updating gs://my-bucket/kitten.png... Completed 1
如要從物件中移除保留設定,請使用下列指令:
gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --clear-retention --override-unlocked-retention
其中:
BUCKET_NAME
是相關值區的名稱。例如:my-bucket
。OBJECT_NAME
是相關物件的名稱。例如:kitten.png
。
用戶端程式庫
C++
詳情請參閱 Cloud Storage C++ API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
C#
詳情請參閱 Cloud Storage C# API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
詳情請參閱 Cloud Storage Java API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
詳情請參閱 Cloud Storage Node.js API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
PHP
詳情請參閱 Cloud Storage PHP API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
詳情請參閱 Cloud Storage Python API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
REST API
JSON API
安裝並初始化 gcloud CLI,以便為
Authorization
標頭產生存取權杖。建立包含下列資訊的 JSON 檔案:
{ "retention": { "mode": STATE, "retainUntilTime": "DATETIME" } }
其中:
STATE
是Locked
或Unlocked
。DATETIME
是可刪除物件的最早日期和時間。例如:2028-02-15T05:30:00Z
。
使用
cURL
透過PATCH
物件要求呼叫 JSON API:curl -X PATCH --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?overrideUnlockedRetention=BOOLEAN"
其中:
JSON_FILE_NAME
是您在步驟 2 建立的檔案路徑。BUCKET_NAME
是相關值區的名稱。例如:my-bucket
。OBJECT_NAME
是相關物件的網址編碼名稱。例如pets/kitten.png
,網址編碼為pets%2Fkitten.png
。- 如果要求縮短、移除或鎖定現有的保留設定,
BOOLEAN
必須為true
。否則,可以完全從要求中排除overrideUnlockedRetention
參數。
XML API
安裝並初始化 gcloud CLI,以便為
Authorization
標頭產生存取權杖。建立包含下列資訊的 XML 檔案:
<Retention> <Mode> STATE </Mode> <RetainUntilDate> DATETIME </RetainUntilDate> </Retention>
其中:
STATE
可以是GOVERNANCE
或COMPLIANCE
。DATETIME
是可刪除物件的最早日期和時間。例如:2028-02-15T05:30:00Z
。
使用
cURL
透過PUT
物件要求呼叫 XML API,範圍限定為?retention
:curl -X PUT --data-binary @XML_FILE_NAME \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "x-goog-bypass-governance-retention: BOOLEAN" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?retention"
其中:
XML_FILE_NAME
是您在步驟 2 建立的 XML 檔案路徑。- 如果要求縮短、移除或鎖定現有的保留設定,
BOOLEAN
必須為true
。否則,可以完全從要求中排除x-goog-bypass-governance-retention
標頭。 BUCKET_NAME
是相關值區的名稱。例如:my-bucket
。OBJECT_NAME
是相關物件的網址編碼名稱。例如pets/kitten.png
,網址編碼為pets%2Fkitten.png
。
查看物件的保留設定
如要查看物件設定的保留設定 (如有):
控制台
- 在 Google Cloud 控制台,前往「Cloud Storage bucket」頁面。
在值區清單中,按一下包含要查看保留設定物件的值區名稱。
系統會開啟「Bucket details」(值區詳細資料) 頁面,並選取「Objects」(物件) 分頁標籤。
前往物件,該物件可能位於資料夾中。
按一下物件名稱。
「物件詳細資料」頁面隨即開啟,顯示物件中繼資料。 物件的任何保留設定資訊都會顯示在「保護」部分。
指令列
使用加上 --format
旗標的 gcloud storage objects describe
指令:
gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(retention_settings)"
其中:
BUCKET_NAME
是相關值區的名稱。例如:my-bucket
。OBJECT_NAME
是相關物件的名稱。例如:kitten.png
。
如果成功,且物件有保留設定,回應會類似以下內容:
retention_settings: mode: Unlocked retainUntilTime: '2028-11-30T14:11:14+00:00'
如果成功,且物件沒有保留設定,回應會類似以下內容:
null
用戶端程式庫
C++
詳情請參閱 Cloud Storage C++ API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看物件的保留設定,請按照顯示物件中繼資料的操作說明,在回應中尋找保留欄位。C#
詳情請參閱 Cloud Storage C# API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看物件的保留設定,請按照顯示物件中繼資料的操作說明,在回應中尋找保留欄位。Java
詳情請參閱 Cloud Storage Java API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看物件的保留設定,請按照顯示物件中繼資料的操作說明,在回應中尋找保留欄位。Node.js
詳情請參閱 Cloud Storage Node.js API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看物件的保留設定,請按照顯示物件中繼資料的操作說明,在回應中尋找保留欄位。PHP
詳情請參閱 Cloud Storage PHP API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看物件的保留設定,請按照顯示物件中繼資料的操作說明,在回應中尋找保留欄位。Python
詳情請參閱 Cloud Storage Python API 參考說明文件。
如要驗證 Cloud Storage,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要查看物件的保留設定,請按照顯示物件中繼資料的操作說明,在回應中尋找保留欄位。REST API
JSON API
安裝並初始化 gcloud CLI,以便為
Authorization
標頭產生存取權杖。使用
cURL
透過包含retention
欄位的GET
物件要求呼叫 JSON API:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/OBJECT_NAME?fields=retention"
其中:
BUCKET_NAME
是相關值區的名稱。例如:my-bucket
。OBJECT_NAME
是相關物件的名稱。例如:kitten.png
。
XML API
安裝並初始化 gcloud CLI,以便為
Authorization
標頭產生存取權杖。使用
cURL
透過GET
物件要求呼叫 XML API,範圍限定為?retention
:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?retention"
其中:
BUCKET_NAME
是相關值區的名稱。例如:my-bucket
。OBJECT_NAME
是相關物件的名稱。例如:kitten.png
。
後續步驟
- 進一步瞭解保留設定。
- 瞭解其他保護 Cloud Storage 資料的功能。
- 瞭解物件生命週期管理,此功能會在檔案到達其保留期限時自動刪除檔案。