本頁說明如何將 bucket 從一個位置遷移到另一個位置。如要瞭解 bucket 遷移功能,請參閱「bucket 遷移」。
事前準備
如要遷移 bucket,請先完成下列步驟:
檢查配額和限制,確認新位置的配額足以容納 bucket 資料。
判斷 bucket 遷移類型,瞭解是否需要寫入停機時間。
如果您使用廣告空間報表,請儲存設定。
取得必要角色,詳情請參閱下一節。
取得必要角色
如要取得重新放置 bucket 所需的權限,請要求管理員授予您專案的儲存空間管理員 (roles/storage.admin) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
這個預先定義的角色具備重新放置 bucket 所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:
所需權限
如要重新放置 bucket,您必須具備下列權限:
-
如要遷移 bucket,請按照以下步驟操作:
storage.buckets.relocate -
如要查看 bucket 遷移作業的狀態,請按照下列步驟操作:
storage.bucketOperations.get -
如要查看專案的 bucket 遷移作業清單,請按照以下步驟操作:
storage.bucketOperations.list -
如要取消值區遷移作業,請按照下列步驟操作:
storage.bucketOperations.cancel -
如要在模擬測試和 bucket 遷移階段查看 bucket 的中繼資料:
storage.buckets.get -
如要取得要重新放置的 bucket 中的物件:
storage.objects.get -
如要列出要重新放置的 bucket 中的物件,請按照以下步驟操作:
storage.objects.list
遷移 bucket
本節說明如何將 Cloud Storage 值區從一個位置遷移到另一個位置。
如要遷移值區,請完成下列步驟:
如要進一步瞭解這些步驟,請參閱「瞭解 bucket 搬遷程序」。
透過模擬測試測試 bucket 遷移作業 (選用)
為盡量減少值區遷移程序期間的潛在問題,建議您先執行模擬測試,測試端對端程序。模擬測試會模擬 bucket 遷移程序,但不會移動資料,有助於您及早發現並解決問題。模擬測試會檢查下列不相容情況:
- 客戶自行管理的加密金鑰 (CMEK) 或客戶提供的加密金鑰 (CSEK)
- 已鎖定的保留政策
- 設有暫時性保留的物件
- 多部分上傳
雖然由於即時資源可用性等因素,有些問題可能只會在實際遷移期間浮現,因此試運轉無法找出所有可能的問題,但仍可降低在實際遷移期間遇到耗時問題的風險。
控制台
- 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
- 在值區清單中,按一下要重新放置的值區名稱。
- 在「Bucket details」(值區詳細資料) 頁面上,按一下「Configuration」(設定) 分頁標籤。
- 在「總覽」部分中,按一下「位置」欄位旁的「編輯」圖示 。
- 在「Relocate bucket」(重新定位 bucket) 頁面中,輸入 bucket 的新位置。完成下列每個步驟後,請按一下「繼續」前往下一個步驟:
- 在「確認要遷移的 bucket」部分,檢查 bucket 和其位置。
- 在「繼續操作前」部分,檢查會阻礙搬遷的設定。如果 bucket 套用了限制,建議您採用 Storage 移轉服務做為替代解決方法。
-
在「Choose where to relocate your bucket」(選擇要將 bucket 遷移到哪裡) 部分,執行下列操作:
- 在「選擇您偏好的處理方式」部分,按一下「從模擬測試著手 (建議)」。模擬測試會模擬遷移作業,找出潛在問題,但不會移動資料。
- 按一下「繼續」。
- 按一下「啟動」。
- 在「先進行模擬測試」確認對話方塊中,查看顯示的訊息,然後按一下「開始模擬測試」。
指令列
如要啟動模擬測試,請執行 gcloud storage buckets relocate 指令並加上 --dry-run 旗標:
gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION --dry-run
其中:
BUCKET_NAME是要重新定位的值區名稱。LOCATION是 bucket 的目的地位置。
啟動模擬測試後,系統會開始執行長時間執行的作業。您會收到作業 ID 和作業說明。如要追蹤模擬測試的進度和完成狀態,請取得長時間執行作業的詳細資料。
如果模擬執行發現任何問題,請先解決問題,再繼續進行搬遷步驟。
JSON API
安裝並初始化 gcloud CLI,以便為
Authorization標頭產生存取權杖。建立包含 bucket 設定的 JSON 檔案,其中必須包含
destinationLocation和validateOnly參數。如需完整的設定清單,請參閱Buckets: relocate說明文件。以下是常見的設定:{ "destinationLocation": "DESTINATION_LOCATION", "destinationCustomPlacementConfig": { "dataLocations": [ LOCATIONS, ... ] }, "validateOnly": "true" }
其中:
DESTINATION_LOCATION是值區的目標位置。LOCATIONS是用於可設定的雙區域的位置代碼清單。validateOnly設為true,即可執行模擬測試。
-
curl -X POST --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/relocate"
其中:
JSON_FILE_NAME是您建立的 JSON 檔案名稱。BUCKET_NAME是要搬遷的值區名稱。
啟動模擬測試後,系統會開始執行長時間執行的作業。符合下列條件時,模擬測試就會成功:
- 模擬測試未回報任何錯誤。
operations資源會傳回true的done欄位值。{ "kind": "storage#operation", "name": "projects/_/buckets/bucket/operations/operation_id", "metadata": { "@type": OperationMetadataType*, metadata OperationMetadata* }, "done": "true", "response": { "@type": ResponseResourceType*, response ResponseResource* } }如果模擬執行發現任何問題,請先解決問題,再繼續執行「啟動搬遷程序」步驟。
啟動 bucket 遷移作業
控制台
- 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
- 在值區清單中,按一下要重新放置的值區名稱。
- 在「Bucket details」(值區詳細資料) 頁面上,按一下「Configuration」(設定) 分頁標籤。
- 在「總覽」部分中,按一下「位置」欄位旁的「編輯」圖示 。
- 在「Relocate bucket」(重新定位 bucket) 頁面中,輸入 bucket 的新位置。完成下列每個步驟後,請按一下「繼續」前往下一個步驟:
- 在「確認要遷移的 bucket」部分,檢查 bucket 和其位置。
- 在「繼續操作前」部分,檢查會阻礙搬遷的設定。如果 bucket 套用了限制,建議您採用Storage 移轉服務做為替代解決方法。
-
在「Choose where to relocate your bucket」(選擇要將 bucket 遷移到哪裡) 部分,執行下列操作:
- 在「選擇您偏好的處理方式」部分中,按一下「立即搬遷」。
- 按一下「繼續」。
- 如要開始搬遷程序,請按一下「開始」。
- 在「立即搬遷」確認對話方塊中,查看顯示的訊息,然後按一下「開始搬遷」。
指令列
如要啟動值區搬遷作業,請執行 gcloud storage buckets relocate 指令:
gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION
其中:
BUCKET_NAME是要重新定位的值區名稱。LOCATION是 bucket 的目的地位置。
JSON API
安裝並初始化 gcloud CLI,以便為
Authorization標頭產生存取權杖。建立包含 bucket 設定的 JSON 檔案。如需完整的設定清單,請參閱
Buckets: relocate說明文件。以下是常見的設定:{ "destinationLocation": "DESTINATION_LOCATION", "destinationCustomPlacementConfig": { "dataLocations": [ LOCATIONS, ... ] }, "validateOnly": "false" }
其中:
DESTINATION_LOCATION是值區的目標位置。LOCATIONS是用於可設定的雙區域的位置代碼清單。validateOnly設為false,即可啟動 bucket 遷移作業。
-
curl -X POST --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/relocate"
其中:
JSON_FILE_NAME是您建立的 JSON 檔案名稱。BUCKET_NAME是要重新定位的值區名稱。
監控搬遷程序
控制台
如要監控試營運或搬遷程序的進度,請完成下列步驟:
- 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
在值區清單中,按一下要重新放置的值區名稱。
在「Bucket details」(值區詳細資料) 頁面中,按一下「Operations」(作業) 分頁標籤。
在顯示的 bucket 作業清單中,按一下預先執行或遷移作業,即可查看詳細資料。
作業詳細資料頁面會顯示搬遷摘要、重要指標和錯誤摘要。
指令列
啟動 bucket 遷移作業後,系統會開始長時間執行的作業。 您會收到作業 ID 和作業說明。如要追蹤遷移程序進度和完成情況,請取得長時間執行的作業詳細資料。
JSON API
值區遷移是長時間執行的作業,需要監控。 如要查看處理狀態,請定期查看長時間執行作業的詳細資料。如要瞭解如何檢查搬遷程序狀態,請參閱取得長時間執行作業的詳細資料。
以下範例顯示重新安置作業產生的輸出內容:
done: false
kind: storage#operation
metadata:
'@type': type.googleapis.com/google.storage.control.v2.RelocateBucketMetadata
commonMetadata:
createTime: '2024-10-21T04:26:59.666Z
endTime: '2024-12-29T23:39:53.340Z'
progressPercent: 99
requestedCancellation: false
type: relocate-bucket
updateTime: '2024-10-21T04:27:03.2892'
destinationLocation: US-CENTRAL1
finalizationState: 'READY'
progress:
byteProgressPercent: 100
discoveredBytes: 200
remainingBytes: 0
discoveredObjectCount: 10
remainingObjectCount: 8
objectProgressPercent: 100
discoveredSyncCount: 8
remainingSyncCount: 0
syncProgressPercent: 100
relocationState: SYNCING
sourceLocation: US
validateOnly: false
estimatedWriteDowntimeDuration: '7200s'
writeDowntimeExpireTime: '2024-12-30T10:34:01.786Z'
name: projects//buckets/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w
response:
'@type': type.googleapis.com/google.storage.control.v2.RelocateBucketResponse
selfLink: https://storage.googleusercontent.com/storage/v1_ds/b/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w
下表提供有關搬遷作業所產生輸出內容中主要欄位的資訊:
| 欄位名稱 | 說明 | 可能的值 |
|---|---|---|
done |
表示 bucket 遷移作業已完成。 | true、false |
kind |
表示這個資源代表儲存空間作業。 | |
metadata |
提供作業相關資訊。 | |
metadata.@type |
指出作業類型為 bucket 遷移。 | |
metadata.commonMetadata |
所有作業通用的中繼資料。 | |
metadata.commonMetadata.createTime |
長時間執行作業的建立時間。 | |
metadata.commonMetadata.endTime |
長時間執行的作業結束時間。 | |
metadata.commonMetadata.progressPercent |
長時間執行作業的預估進度 (百分比)。 | 介於 0 至 100% 之間。值為 -1 表示進度不明或不適用。 |
metadata.commonMetadata.requestedCancellation |
指出使用者是否已要求取消長時間執行的作業。 | true、false |
metadata.commonMetadata.type |
指出長時間執行的作業類型。 | |
metadata.commonMetadata.updateTime |
上次更新長時間執行作業的時間。 | |
metadata.destinationLocation |
bucket 的目的地位置。 | |
metadata.finalizationState |
指出是否已準備好啟動最終同步處理步驟。 |
|
metadata.progress |
遷移作業的進度詳細資料。 | |
metadata.progress.byteProgressPercent |
已複製的位元組數百分比。 | 介於 0 至 100% 之間。值為 -1 表示進度不明或不適用。 |
metadata.progress.discoveredBytes |
在來源 bucket 中找到的位元組數。 | |
metadata.progress.discoveredObjectCount |
在來源值區中探索到的物件數量。 | |
metadata.progress.discoveredSyncCount |
在來源值區中偵測到的物件中繼資料更新次數。 | |
metadata.progress.objectProgressPercent |
以百分比表示物件複製進度。 | 介於 0 至 100% 之間。值為 -1 表示進度不明或不適用。 |
metadata.progress.remainingBytes |
從來源 bucket 複製到目的地 bucket 的剩餘位元組數。 | |
metadata.progress.remainingObjectCount |
從來源 bucket 複製到目的地 bucket 的剩餘物件數量。 | |
metadata.progress.remainingSyncCount |
待同步處理的物件中繼資料更新作業數量。 | |
metadata.progress.syncProgressPercent |
以百分比表示要同步處理的物件中繼資料更新作業進度。 | 介於 0 至 100% 之間。值為 -1 表示進度不明或不適用。 |
metadata.relocationState |
bucket 遷移作業的整體狀態。 |
|
metadata.sourceLocation |
bucket 的來源位置。 | |
metadata.validateOnly |
指出是否已啟動 bucket 遷移的模擬測試。 | true、false |
metadata.estimatedWriteDowntimeDuration |
預估寫入停機時間長度;finalizationState 為 READY 時會填入這項資訊。 |
值不得小於 7200s。 |
metadata.writeDowntimeExpireTime |
寫入停機時間到期時間。 | |
name |
這項搬遷作業的專屬 ID。 格式: projects/_/buckets/bucket-name/operations/operation-id |
|
response |
作業的回應。 | |
response.@type |
回覆類型。 | |
selfLink |
這項作業的連結。 |
如果您在使用其他 Cloud Storage 功能時遇到問題,請參閱「限制」一節。
啟動最終同步處理步驟
如果遷移作業需要停止寫入,您必須啟動最終同步作業。最終同步處理步驟會有一段時間,您無法對 bucket 執行寫入作業。建議您安排最終同步步驟的時間,盡量減少對應用程式的干擾。
控制台
如要啟動最終同步步驟,請完成下列步驟:
- 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
在值區清單中,按一下要重新放置的值區名稱。
在「Bucket details」(值區詳細資料) 頁面中,按一下「Operations」(作業) 分頁標籤。
在 bucket 作業清單中,按一下遷移作業,即可查看作業詳細資料頁面。在作業詳細資料頁面中,當資料複製作業完成至少 99% 時,系統會顯示訊息列,指出這是開始最終同步處理的最佳時機。
選用:如要設定允許的寫入停機時間上限,請按一下「設定允許的停機時間上限 (TTL)」,然後指定停機時間上限。
按一下「開始最終同步處理」。
在隨即顯示的確認對話方塊中,按一下「開始」,即可開始最終同步程序。
作業詳細資料頁面會顯示搬遷摘要、重要指標和錯誤摘要。
指令列
繼續操作前,請先檢查「啟動 Bucket 搬遷作業」步驟的輸出內容,確認 Bucket 已完全準備就緒 (finalizationState 值)。
如果 finalizationState 值為 READY,請執行 gcloud storage buckets
relocate 指令,啟動最終同步:
gcloud storage buckets relocate --finalize --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID
其中:
BUCKET_NAME是要重新定位的值區名稱。OPERATION_ID是儲存空間搬遷長時間執行作業的 ID,會在您呼叫的方法回應中傳回。舉例來說,呼叫gcloud storage operations list會傳回下列回應,而長時間執行作業 ID 為AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74。
`name: projects/_/buckets/my-bucket/operations/AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74`
設定 ttl 標記,進一步控管重新安置程序。例如:
gcloud storage buckets relocate --finalize --ttl TTL_DURATION --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID
其中:
TTL_DURATION 是指在重新安置程序中,寫入停機階段的存留時間 (TTL)。以字串表示,例如 12 小時為 12h。TTL_DURATION 會決定寫入停機階段的時長上限。如果寫入停機時間超過這個上限,遷移程序會自動還原至 bucket 遷移步驟,並重新啟用對 bucket 的寫入作業。這個值必須介於 6h (6 小時) 至 48h (48 小時) 之間。如未指定,預設值為 12h (12 小時)。
JSON API
繼續操作前,請先檢查 bucket relocation 步驟的輸出內容,確認 bucket 已完全準備就緒 (finalizationState 值)。finalizationState 值必須為 READY,才能繼續。
如果過早啟動最終同步處理步驟,指令會傳回錯誤訊息 The relocate bucket operation is not ready to advance to finalization running state,但搬遷程序會繼續執行。
建議您等到 progressPercent 值為 99,再啟動最終同步步驟。
安裝並初始化 gcloud CLI,以便為
Authorization標頭產生存取權杖。建立包含值區重新放置設定的 JSON 檔案。如需完整的設定清單,請參閱
Buckets: advanceRelocateBucket說明文件。以下是常見的設定:{ "expireTime": "EXPIRE_TIME", "ttl": "TTL_DURATION" }
其中:
EXPIRE_TIME是寫入停機時間的到期時間。TTL_DURATION是指在重新安置程序中,寫入停機階段的存留時間 (TTL)。以字串表示,例如 12 小時為12h。TTL_DURATION會決定寫入停機階段的時長上限。如果寫入停機時間超過這個上限,遷移程序會自動還原至 bucket 遷移步驟,並重新啟用對 bucket 的寫入作業。這個值必須介於6h(6 小時) 至48h(48 小時) 之間。如未指定,預設值為12h(12 小時)。
-
curl -X POST --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/BUCKET_NAME/operations/OPERATION_ID/advanceRelocateBucket"
其中:
JSON_FILE_NAME是您建立的 JSON 檔案名稱。BUCKET_NAME是要重新定位的值區名稱。OPERATION_ID是啟動 bucket 搬遷作業的長時間作業 ID。如要取得 bucket 的長時間執行作業 ID 清單,請參閱「作業:清單」。
bucket 遷移成功後,14 天內無法再次遷移同一個 bucket。
驗證 bucket 遷移程序
啟動搬遷作業後,請確認作業是否順利完成。本節提供相關指引,說明如何確認資料是否已成功轉移。
使用下列方法驗證搬遷程序是否成功:
輪詢長時間執行的作業:Bucket 遷移作業是長時間執行的作業。您可以使用
operation id輪詢長時間執行的作業,監控作業進度,並驗證success狀態,確認作業是否成功完成。這包括定期查詢作業狀態,直到作業達到終止狀態為止。如要瞭解如何監控長時間執行的作業,請參閱「在 Cloud Storage 中使用長時間執行的作業」。分析 Cloud 稽核記錄項目:Cloud 稽核記錄會詳細記錄 Google Cloud 環境中的事件和作業。您可以分析與搬遷作業相關的 Cloud 稽核記錄項目,確認作業是否成功。分析記錄中是否有任何錯誤、警告或非預期行為,這些都可能指出移轉期間發生問題。如要瞭解如何查看 Cloud 稽核記錄,請參閱「查看稽核記錄」。
您可以根據下列記錄項目,判斷遷移作業是否成功:
成功搬遷:
Relocate bucket succeeded. All existing objects are now in the new placement configuration.無法重新定位:
Relocate bucket has failed. Bucket location remains unchanged.
您也可以使用 Pub/Sub 通知設定快訊,在記錄檔中出現特定成功或失敗事件時收到通知。如要瞭解如何設定 Pub/Sub 通知,請參閱「設定 Cloud Storage 的 Pub/Sub 通知」。
完成 bucket 遷移後工作
成功遷移 bucket 後,請完成下列步驟:
- 選用:還原值區上任何標記式存取權控管。
- 在遷移過程中,現有的商品目錄報表設定不會保留,您必須手動重新建立。如要瞭解如何建立庫存報表設定,請參閱「建立庫存報表設定」。
- 更新基礎架構即程式碼設定 (例如 Terraform 和 Google Kubernetes Engine 設定連接器),指定 Bucket 的新位置。
- 區域端點與特定位置相關聯,您需要修改應用程式程式碼,以反映新的端點。
如何處理失敗的 bucket 遷移作業
處理失敗的 bucket 重新安置作業前,請先考量下列因素:
如果 bucket 遷移失敗,目的地可能會留下過時的資源,例如暫存檔案或不完整的資料副本。您必須等待 7 到 14 天,才能啟動另一項 bucket 遷移作業,將 bucket 遷移到相同目的地。您可以立即啟動 bucket 搬遷作業,將 bucket 搬遷至其他目的地。
如果目的地位置並非資料的最佳位置,您可能需要回溯搬遷作業。不過,您無法立即啟動搬遷作業。為維持穩定性及避免資料衝突,您必須等待最多 14 天,才能再次啟動遷移程序。
後續步驟
- 瞭解 bucket 遷移。