本頁面由 Cloud Translation API 翻譯而成。

遷移值區

本頁說明如何將 bucket 從一個位置遷移到另一個位置。如要瞭解 bucket 遷移功能，請參閱「bucket 遷移」。

事前準備

如要遷移 bucket，請先完成下列步驟：

設定 Storage Intelligence。
啟用虛刪除功能。
檢查配額和限制，確保新位置有足夠的配額可容納 bucket 的資料。
判斷值區重新安置類型，瞭解是否需要寫入停機時間。
移除所有現有的 bucket 標記。
如果您使用廣告空間報表，請儲存設定。
取得必要角色，詳情請參閱下一節。

取得必要角色

如要取得遷移值區所需的權限，請要求管理員為您授予專案的儲存空間管理員 (roles/storage.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備重新放置值區所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

所需權限

如要重新放置 bucket，您必須具備下列權限：

如要遷移 bucket： storage.buckets.relocate
如要查看 bucket 搬遷作業的狀態： storage.bucketOperations.get
如要查看專案的值區搬遷作業清單： storage.bucketOperations.list
如要取消值區搬遷作業： storage.bucketOperations.cancel
如要在值區搬遷的試執行和增量資料複製階段查看值區的中繼資料： storage.buckets.get
如要取得要搬遷的 bucket 中的物件： storage.objects.get
如要列出要重新放置的值區中的物件： storage.objects.list

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

遷移 bucket

本節說明如何將 Cloud Storage 值區從一個位置遷移到另一個位置。遷移 bucket 時，您會啟動遞增資料複製程序、監控程序，然後啟動最終同步步驟。如要進一步瞭解這些步驟，請參閱「瞭解 bucket 遷移程序」。

執行模擬測試

為盡量減少儲存空間遷移程序期間的潛在問題，建議您先進行模擬測試。模擬測試會模擬 bucket 遷移程序，但不會移動資料，有助於您及早發現並解決問題。模擬測試會檢查下列不相容情況：

雖然模擬執行無法找出所有可能的問題，因為有些問題可能只會在實際遷移期間，因即時資源可用性等因素而浮現，但模擬執行可降低在實際遷移期間遇到耗時問題的風險。

指令列

模擬 bucket 遷移的模擬測試：

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION --dry-run

其中：

BUCKET_NAME 是要重新定位的值區名稱。
LOCATION 是 bucket 的目的地位置。

啟動模擬測試後，系統會開始長時間執行的作業。您會收到作業 ID 和作業說明。如要追蹤模擬執行的進度和完成狀態，請取得長時間執行的作業詳細資料。

如果模擬執行發現任何問題，請先解決問題，再繼續進行啟動增量資料複製步驟。

REST API

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 呼叫 JSON API：

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/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 遷移作業：

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION

其中：

BUCKET_NAME 是要重新定位的值區名稱。
LOCATION 是 bucket 的目的地位置。

注意： 建立可設定的雙區域時，您必須將 --location 旗標設為與基礎區域相關聯的位置代碼，並使用 --placement 旗標搭配一組有效的區域。例如： --location=US --placement=US-CENTRAL1,US-EAST1

REST API

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

建立包含值區設定的 JSON 檔案。如需完整的設定清單，請參閱 Buckets: relocate 說明文件。以下是常見的設定：
```
{
  "destinationLocation": "DESTINATION_LOCATION",
  "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
    },
  "validateOnly": "false"
}
```
其中：
- DESTINATION_LOCATION 是值區的目標位置。
- LOCATIONS 是用於可設定的雙區域的位置代碼清單。
- validateOnly 設為 false，啟動 Bucket 搬遷的增量資料複製步驟。

使用 cURL 呼叫 JSON API：

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/relocate"

其中：

JSON_FILE_NAME 是您建立的 JSON 檔案名稱。
BUCKET_NAME 是要重新定位的值區名稱。

監控增量資料副本

儲存空間的搬遷程序是長時間執行的作業，必須監控才能瞭解進度。您可以定期查看長時間執行的作業清單，瞭解增量資料複製步驟的狀態。如要瞭解如何取得長時間執行的作業詳細資料、列出或取消長時間執行的作業，請參閱「在 Cloud Storage 中使用長時間執行的作業」。

以下範例顯示增量資料複製作業產生的輸出內容：

  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`	指出啟動最終同步步驟的準備狀態。	`READY`：表示您可以啟動最終同步步驟。不過，建議您等到 `progressPercent` 欄位的值達到 `99` 再進行。 `WAITING_ON_SYNC`：表示您無法啟動最終同步處理步驟。 `NOT_REQUIRED`：表示這個 bucket 不需要最後的同步步驟，您可以略過。 `BLOCKED_ON_ERRORS`：表示因發生錯誤，最終步驟暫時停止。您必須先解決錯誤，才能繼續執行這個步驟。 `RUNNING`：表示正在進行最終步驟。 `FINALIZED`：表示最終步驟已順利完成。
`metadata.progress`	搬遷作業的進度詳細資料。
`metadata.progress.byteProgressPercent`	以百分比表示的位元組複製進度。	介於 `0` 至 `100`% 之間。值為 `-1` 表示進度不明或不適用。
`metadata.progress.discoveredBytes`	在來源值區中找到的位元組數。
`metadata.progress.discoveredObjectCount`	在來源值區中找到的物件數量。
`metadata.progress.discoveredSyncCount`	在來源 bucket 中發現的物件中繼資料更新次數。
`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 遷移作業的整體狀態。	`SYNCING`：表示增量資料複製步驟正在將物件從來源值區複製到目的地值區。 `FINALIZING`：表示已啟動最終步驟。 `FAILED`：表示增量資料複製步驟發生錯誤，且未順利完成。 `SUCCEEDED`：表示增量資料副本步驟已順利完成。 `CANCELLED`：表示增量資料複製步驟已取消。
`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`	這項作業的連結。

注意：metadata.commonMetadata.progressPercent 會顯示長時間執行的作業整體完成進度。所有步驟完成後，進度會達到 100%。這是唯一可靠的完整成功指標。其他進度指標會顯示位元組、物件和中繼資料的移動情形。這些裝置可能比 metadata.commonMetadata.progressPercent 更快達到 100%。位元組、物件和中繼資料移轉完成後，值區搬遷作業會完成最後的步驟，然後 metadata.commonMetadata.progressPercent 會更新為 100%。

如果您在使用其他 Cloud Storage 功能時遇到問題，請參閱「限制」一節。

啟動最終同步步驟

在最後的同步處理步驟中，您將有一段時間無法對 bucket 執行寫入作業。建議您將最後的同步步驟安排在對應用程式影響最小的時段。

請先檢查增量資料副本步驟的輸出內容中的 finalizationState 值，確認 bucket 已完全準備就緒，再繼續操作。finalizationState 值必須為 READY，才能繼續操作。

如果過早啟動最終同步步驟，指令會傳回 The relocate bucket operation is not ready to advance to finalization running state 錯誤訊息，但搬遷程序會繼續執行。

建議您等到 progressPercent 值為 99，再啟動最終同步步驟。

指令列

finalizationState 值為 READY 時，請啟動 bucket 搬遷作業的最終同步步驟：

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 會決定寫入停機階段的允許時間長度上限。如果寫入停機時間超過這個限制，系統會自動將重新安置程序還原為增量複製步驟，並重新啟用對該值區的寫入作業。這個值必須介於 6h (6 小時) 至 48h (48 小時) 之間。如未指定，預設值為 12h (12 小時)。

REST API

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

建立 JSON 檔案，其中包含值區搬遷的設定。如需完整的設定清單，請參閱 Buckets: advanceRelocateBucket 說明文件。以下是常見的設定：
```
{
    "expireTime": "EXPIRE_TIME",
    "ttl": "TTL_DURATION"
}
```
其中：
- EXPIRE_TIME 是寫入停機時間到期的時間。
- TTL_DURATION 是指在重新安置程序中，寫入停機階段的存留時間 (TTL)。以字串表示，例如 12 小時為 12h。TTL_DURATION 會決定寫入停機階段的允許時間長度上限。如果寫入停機時間超過這個限制，系統會自動將重新安置程序還原為增量複製步驟，並重新啟用對該值區的寫入作業。這個值必須介於 6h (6 小時) 至 48h (48 小時) 之間。如未指定，預設值為 12h (12 小時)。
使用 cURL 呼叫 JSON API：
```
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 是長時間執行的作業 ID，會顯示在您呼叫的方法回應中。舉例來說，呼叫 Operations: list 會傳回下列回應，而長時間執行作業 ID 為 AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74。

驗證 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 後，請完成下列步驟：

選用：還原值區上任何標記式存取權控管。
在遷移過程中，現有的商品目錄報表設定不會保留，您必須手動重新建立。如要瞭解如何建立庫存報表設定，請參閱「建立庫存報表設定」。
更新基礎架構即程式碼設定 (例如 Terraform 和 Google Kubernetes Engine 設定連接器)，指定新的 bucket 位置。
區域端點與特定位置相關聯，您需要修改應用程式程式碼，以反映新的端點。

如何處理 Bucket 搬遷作業失敗的問題

處理失敗的 Bucket 搬遷作業前，請先考量下列因素：

如果值區搬遷失敗，目的地可能會留下過時的資源，例如暫存檔案或不完整的資料副本。您必須等待 7 到 14 天，才能啟動另一項 bucket 遷移作業，將 bucket 遷移到相同目的地。您可以立即啟動 bucket 搬遷作業，將 bucket 搬遷至其他目的地。
如果目的地位置並非資料的最佳位置，您可能需要回溯搬遷作業。不過，您無法立即啟動搬遷作業。你必須等待最多 14 天，才能再次啟動遷移程序。這項限制是為了確保穩定性及避免資料衝突。

後續步驟

瞭解bucket 遷移。

遷移值區 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

取得必要角色

所需權限

遷移 bucket

執行模擬測試

指令列

REST API

JSON API

啟動增量資料複製作業

指令列

REST API

JSON API

監控增量資料副本

啟動最終同步步驟

指令列

REST API

JSON API

驗證 bucket 遷移程序

完成後續的儲存空間重新配置工作

如何處理 Bucket 搬遷作業失敗的問題

後續步驟

遷移值區