遷移 bucket

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

事前準備

如要遷移 bucket,請先完成下列步驟:

  1. 設定 Storage Intelligence

  2. 啟用虛刪除功能

  3. 檢查配額和限制,確認新位置的配額足以容納 bucket 資料。

  4. 判斷 bucket 遷移類型,瞭解是否需要寫入停機時間。

  5. 移除所有現有的 bucket 標記

  6. 如果您使用廣告空間報表,請儲存設定

  7. 取得必要角色,詳情請參閱下一節。

取得必要角色

如要取得重新放置 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 值區從一個位置遷移到另一個位置。

如要遷移值區,請完成下列步驟:

  1. 模擬測試,確認儲存空間重新定位作業是否正常運作 (選用)

  2. 啟動 bucket 遷移程序

  3. 啟動最終同步處理步驟

如要進一步瞭解這些步驟,請參閱「瞭解 bucket 搬遷程序」。

透過模擬測試測試 bucket 遷移作業 (選用)

為盡量減少值區遷移程序期間的潛在問題,建議您先執行模擬測試,測試端對端程序。模擬測試會模擬 bucket 遷移程序,但不會移動資料,有助於您及早發現並解決問題。模擬測試會檢查下列不相容情況:

雖然由於即時資源可用性等因素,有些問題可能只會在實際遷移期間浮現,因此試運轉無法找出所有可能的問題,但仍可降低在實際遷移期間遇到耗時問題的風險。

控制台

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

    前往「Buckets」(值區) 頁面

  2. 在值區清單中,按一下要重新放置的值區名稱。
  3. 在「Bucket details」(值區詳細資料) 頁面上,按一下「Configuration」(設定) 分頁標籤。
  4. 在「總覽」部分中,按一下「位置」欄位旁的「編輯」圖示
  5. 在「Relocate bucket」(重新定位 bucket) 頁面中,輸入 bucket 的新位置。完成下列每個步驟後,請按一下「繼續」前往下一個步驟:
    1. 在「確認要遷移的 bucket」部分,檢查 bucket 和其位置。
    2. 在「繼續操作前」部分,檢查會阻礙搬遷的設定。如果 bucket 套用了限制,建議您採用 Storage 移轉服務做為替代解決方法。
    3. 在「Choose where to relocate your bucket」(選擇要將 bucket 遷移到哪裡) 部分,執行下列操作:

      1. 選取位置類型
      2. 選取要儲存 bucket 中物件資料的位置

        系統會根據來源和目的地位置,通知您是否需要寫入停機時間。如要瞭解遷移類型和停機時間,請參閱「遷移類型」。

    4. 在「選擇您偏好的處理方式」部分,按一下「從模擬測試著手 (建議)」。模擬測試會模擬遷移作業,找出潛在問題,但不會移動資料。
    5. 按一下「繼續」
  6. 按一下「啟動」
  7. 在「先進行模擬測試」確認對話方塊中,查看顯示的訊息,然後按一下「開始模擬測試」

啟動模擬測試後,系統會開始執行長時間執行的作業。您可以在 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

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

  2. 建立包含 bucket 設定的 JSON 檔案,其中必須包含 destinationLocationvalidateOnly 參數。如需完整的設定清單,請參閱 Buckets: relocate說明文件。以下是常見的設定:

    {
      "destinationLocation": "DESTINATION_LOCATION",
      "destinationCustomPlacementConfig": {
        "dataLocations": [
          LOCATIONS,
            ...
            ]
        },
      "validateOnly": "true"
      }

    其中:

    • DESTINATION_LOCATION 是值區的目標位置。
    • LOCATIONS 是用於可設定的雙區域的位置代碼清單。
    • validateOnly 設為 true,即可執行模擬測試。
  3. 使用 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_NAME/relocate"

    其中:

    • JSON_FILE_NAME 是您建立的 JSON 檔案名稱。
    • BUCKET_NAME 是要搬遷的值區名稱。

    啟動模擬測試後,系統會開始執行長時間執行的作業。符合下列條件時,模擬測試就會成功:

    • 模擬測試未回報任何錯誤。
    • operations 資源會傳回 truedone 欄位值。

      {
      "kind": "storage#operation",
      "name": "projects/_/buckets/bucket/operations/operation_id",
      "metadata": {
        "@type": OperationMetadataType*,
        metadata OperationMetadata*
      },
      "done": "true",
      "response": {
            "@type": ResponseResourceType*,
            response ResponseResource*
          }
        }

      如果模擬執行發現任何問題,請先解決問題,再繼續執行「啟動搬遷程序」步驟。

啟動 bucket 遷移作業

控制台

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

    前往「Buckets」(值區) 頁面

  2. 在值區清單中,按一下要重新放置的值區名稱。
  3. 在「Bucket details」(值區詳細資料) 頁面上,按一下「Configuration」(設定) 分頁標籤。
  4. 在「總覽」部分中,按一下「位置」欄位旁的「編輯」圖示
  5. 在「Relocate bucket」(重新定位 bucket) 頁面中,輸入 bucket 的新位置。完成下列每個步驟後,請按一下「繼續」前往下一個步驟:
    1. 在「確認要遷移的 bucket」部分,檢查 bucket 和其位置。
    2. 在「繼續操作前」部分,檢查會阻礙搬遷的設定。如果 bucket 套用了限制,建議您採用Storage 移轉服務做為替代解決方法。
    3. 在「Choose where to relocate your bucket」(選擇要將 bucket 遷移到哪裡) 部分,執行下列操作:

      1. 選取位置類型
      2. 選取要儲存 bucket 中物件資料的位置

        系統會根據來源和目的地位置,通知您是否需要寫入停機時間。如要瞭解遷移類型和停機時間,請參閱「遷移類型」。

    4. 在「選擇您偏好的處理方式」部分中,按一下「立即搬遷」
    5. 按一下「繼續」
  6. 如要開始搬遷程序,請按一下「開始」
  7. 在「立即搬遷」確認對話方塊中,查看顯示的訊息,然後按一下「開始搬遷」

啟動搬遷程序後,系統會開始長時間執行的作業。您可以在 bucket 詳細資料頁面的「作業」分頁中監控進度

指令列

如要啟動值區搬遷作業,請執行 gcloud storage buckets relocate 指令:

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

其中:

  • BUCKET_NAME 是要重新定位的值區名稱。

  • LOCATION 是 bucket 的目的地位置。

JSON API

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

  2. 建立包含 bucket 設定的 JSON 檔案。如需完整的設定清單,請參閱 Buckets: relocate說明文件。以下是常見的設定:

    {
      "destinationLocation": "DESTINATION_LOCATION",
      "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
        },
      "validateOnly": "false"
      }

    其中:

    • DESTINATION_LOCATION 是值區的目標位置。
    • LOCATIONS 是用於可設定的雙區域的位置代碼清單。
    • validateOnly 設為 false,即可啟動 bucket 遷移作業。
  3. 使用 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_NAME/relocate"

    其中:

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

監控搬遷程序

控制台

如要監控試營運或搬遷程序的進度,請完成下列步驟:

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

    前往「Buckets」(值區) 頁面

  2. 在值區清單中,按一下要重新放置的值區名稱。

  3. 在「Bucket details」(值區詳細資料) 頁面中,按一下「Operations」(作業) 分頁標籤。

  4. 在顯示的 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 遷移作業已完成。 truefalse
kind 表示這個資源代表儲存空間作業。
metadata 提供作業相關資訊。
metadata.@type 指出作業類型為 bucket 遷移。
metadata.commonMetadata 所有作業通用的中繼資料。
metadata.commonMetadata.createTime 長時間執行作業的建立時間。
metadata.commonMetadata.endTime 長時間執行的作業結束時間。
metadata.commonMetadata.progressPercent 長時間執行作業的預估進度 (百分比)。 介於 0100% 之間。值為 -1 表示進度不明或不適用。
metadata.commonMetadata.requestedCancellation 指出使用者是否已要求取消長時間執行的作業。 truefalse
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 已複製的位元組數百分比。 介於 0100% 之間。值為 -1 表示進度不明或不適用。
metadata.progress.discoveredBytes 在來源 bucket 中找到的位元組數。
metadata.progress.discoveredObjectCount 在來源值區中探索到的物件數量。
metadata.progress.discoveredSyncCount 在來源值區中偵測到的物件中繼資料更新次數。
metadata.progress.objectProgressPercent 以百分比表示物件複製進度。 介於 0100% 之間。值為 -1 表示進度不明或不適用。
metadata.progress.remainingBytes 從來源 bucket 複製到目的地 bucket 的剩餘位元組數。
metadata.progress.remainingObjectCount 從來源 bucket 複製到目的地 bucket 的剩餘物件數量。
metadata.progress.remainingSyncCount 待同步處理的物件中繼資料更新作業數量。
metadata.progress.syncProgressPercent 以百分比表示要同步處理的物件中繼資料更新作業進度。 介於 0100% 之間。值為 -1 表示進度不明或不適用。
metadata.relocationState bucket 遷移作業的整體狀態。
  • SYNCING:表示值區搬遷步驟正在將物件從來源值區複製到目的地值區。
  • FINALIZING:表示已啟動最終步驟。
  • FAILED:表示 bucket 遷移步驟發生錯誤,且未順利完成。
  • SUCCEEDED:表示 bucket 遷移步驟已順利完成。
  • CANCELLED:表示值區重新放置步驟已取消。
metadata.sourceLocation bucket 的來源位置。
metadata.validateOnly 指出是否已啟動 bucket 遷移的模擬測試 truefalse
metadata.estimatedWriteDowntimeDuration 預估寫入停機時間長度;finalizationStateREADY 時會填入這項資訊。 值不得小於 7200s
metadata.writeDowntimeExpireTime 寫入停機時間到期時間。
name 這項搬遷作業的專屬 ID。
格式:projects/_/buckets/bucket-name/operations/operation-id
response 作業的回應。
response.@type 回覆類型。
selfLink 這項作業的連結。

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

啟動最終同步處理步驟

如果遷移作業需要停止寫入,您必須啟動最終同步作業。最終同步處理步驟會有一段時間,您無法對 bucket 執行寫入作業。建議您安排最終同步步驟的時間,盡量減少對應用程式的干擾。

控制台

如要啟動最終同步步驟,請完成下列步驟:

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

    前往「Buckets」(值區) 頁面

  2. 在值區清單中,按一下要重新放置的值區名稱。

  3. 在「Bucket details」(值區詳細資料) 頁面中,按一下「Operations」(作業) 分頁標籤。

  4. 在 bucket 作業清單中,按一下遷移作業,即可查看作業詳細資料頁面。在作業詳細資料頁面中,當資料複製作業完成至少 99% 時,系統會顯示訊息列,指出這是開始最終同步處理的最佳時機。

  5. 選用:如要設定允許的寫入停機時間上限,請按一下「設定允許的停機時間上限 (TTL)」,然後指定停機時間上限。

  6. 按一下「開始最終同步處理」

  7. 在隨即顯示的確認對話方塊中,按一下「開始」,即可開始最終同步程序。

作業詳細資料頁面會顯示搬遷摘要、重要指標和錯誤摘要。

指令列

繼續操作前,請先檢查「啟動 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 小時為 12hTTL_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,再啟動最終同步步驟。

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

  2. 建立包含值區重新放置設定的 JSON 檔案。如需完整的設定清單,請參閱 Buckets: advanceRelocateBucket說明文件。以下是常見的設定:

    {
    "expireTime": "EXPIRE_TIME",
    "ttl": "TTL_DURATION"
    }

    其中:

    • EXPIRE_TIME 是寫入停機時間的到期時間。
    • TTL_DURATION 是指在重新安置程序中,寫入停機階段的存留時間 (TTL)。以字串表示,例如 12 小時為 12hTTL_DURATION 會決定寫入停機階段的時長上限。如果寫入停機時間超過這個上限,遷移程序會自動還原至 bucket 遷移步驟,並重新啟用對 bucket 的寫入作業。這個值必須介於 6h (6 小時) 至 48h (48 小時) 之間。如未指定,預設值為 12h (12 小時)。
  3. 使用 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 是啟動 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 後,請完成下列步驟:

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

如何處理失敗的 bucket 遷移作業

處理失敗的 bucket 重新安置作業前,請先考量下列因素:

  • 如果 bucket 遷移失敗,目的地可能會留下過時的資源,例如暫存檔案或不完整的資料副本。您必須等待 7 到 14 天,才能啟動另一項 bucket 遷移作業,將 bucket 遷移到相同目的地。您可以立即啟動 bucket 搬遷作業,將 bucket 搬遷至其他目的地。

  • 如果目的地位置並非資料的最佳位置,您可能需要回溯搬遷作業。不過,您無法立即啟動搬遷作業。為維持穩定性及避免資料衝突,您必須等待最多 14 天,才能再次啟動遷移程序。

後續步驟