從 gsutil 遷移至 gcloud storage

gcloud storage (正式發布) 是與 Cloud Storage 互動時建議使用的指令列工具。本頁面說明兩種工具的主要差異和指令對應，協助您從 gsutil 轉換到 gcloud storage。如需 gcloud storage 工具的詳細說明，請參閱 gcloud storage 參考說明文件。

如要瞭解如何安裝及開始使用 Google Cloud CLI，請參閱「安裝 Google Cloud CLI」。

行為差異

以下各節說明 gsutil 和 gcloud storage 的行為差異。

平行叫用

gcloud storage 不支援從不同終端機同時執行多個 CLI 執行個體。

平行處理

gcloud storage 支援平行處理。

萬用字元處理

gcloud storage 會簡化多個星號。如果連續使用三個以上的星號 (***)，系統會將其視為單一星號 (*)。

處理階層命名空間 bucket

gcloud storage 可用於建立及管理已啟用階層命名空間的 bucket。

輸出格式

gcloud storage 和 gsutil 指令的輸出格式不同。 雖然記錄格式等微小變更可能不會影響您，但錯誤訊息和資料清單的重大差異可能會導致自動化指令碼中斷。

如果您有依賴剖析 gsutil 指令輸出的指令碼，請先檢查並更新這些指令碼，使其符合 gcloud storage 格式，再進行轉換。

對應的 gcloud 指令

所有現有的 gsutil 指令在 gcloud storage 中都有對等的指令，但還是有一些例外。如要取得 gcloud storage 指令的完整清單，請參閱參考說明文件或執行 gcloud storage --help。下表簡要說明常見 gsutil 指令的變更。

作業 gsutil 指令 gcloud storage 指令
管理存取控制清單 (ACL) 
gsutil acl get
gsutil acl set
gsutil acl ch

gcloud storage RESOURCE describe --format="multi(acl:format=json)"
gcloud storage RESOURCE update --acl-file=ACL_FILE_PATH
gcloud storage RESOURCE update --add-acl-grant=GRANT
gcloud storage RESOURCE update --remove-acl-grant=GRANT
作業 gsutil 指令 gcloud storage 指令
串連物件並顯示物件內容 
gsutil cat
 
gcloud storage cat
作業 gsutil 指令 gcloud storage 指令
將物件合併為新物件，藉此串連物件 
gsutil compose
 
gcloud storage objects compose
附註
如要在 gcloud storage objects compose 中套用先決條件，請使用特定旗標，例如 --if-generation-match 或 --if-metageneration-match。
作業 gsutil 指令 gcloud storage 指令
複製物件和其他資源 
gsutil cp
 
gcloud storage cp
附註

使用 Google Cloud 控制台建立的模擬資料夾會被視為 0 位元組的預留位置物件。gcloud storage cp 可用於複製模擬資料夾，但 gsutil cp 無法。

處理錯誤時，gcloud storage cp 會嘗試複製所有資源，即使其中一個資源無效或不存在也一樣。gsutil cp 遇到無效資源時，可能會立即停止整個作業。

下載物件時，gcloud storage cp 會建立目的地路徑中指定的任何遺失本機目錄。如果目的地目錄不存在，gsutil cp 就會失敗。
作業 gsutil 指令 gcloud storage 指令
顯示物件使用的磁碟空間總量 
gsutil du
 
gcloud storage du
作業 gsutil 指令 gcloud storage 指令
計算檔案雜湊值 
gsutil hash
 
gcloud storage hash
附註

gsutil hash 會使用加法旗標來加入特定雜湊，例如 -c 或 -m。gcloud storage hash 使用減法旗標排除雜湊，例如 --skip-md5 或 --skip-crc32c。
作業 gsutil 指令 gcloud storage 指令
管理 bucket 標籤 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
附註

在單一 gsutil label ch 指令中新增、更新及移除標籤的組合，行為可能與使用 gcloud storage buckets update 的對等作業不同。如果指令碼依賴 gsutil 的特定讀取/修改/寫入行為，請在轉換至 gcloud storage 後仔細測試。
作業 gsutil 指令 gcloud storage 指令
列出 bucket、物件和資料夾 
gsutil ls
 
gcloud storage ls
附註

使用萬用字元列出專案中的物件時，gsutil ls 會傳回物件的扁平清單，而 gcloud storage ls 則會傳回依值區名稱分組的物件。

使用 gcloud storage ls -L 傳回詳細的房源資訊做為輸出內容時，適用下列行為：

  • 各項中繼資料的標籤 (也稱為「鍵」) 中，每個字的第一個字母都會大寫。
  • 如果物件的中繼資料沒有值，gcloud storage 會從輸出內容中省略該行。

gcloud storage 一律會輸出世界標準時間的日期時間。

gcloud storage 會在指令輸出的結尾傳回任何錯誤訊息。
作業 gsutil 指令 gcloud storage 指令
移動及重新命名物件或目錄 
gsutil mv
 
gcloud storage mv
作業 gsutil 指令 gcloud storage 指令
就地重寫物件 
gsutil rewrite
 
gcloud storage objects update
附註

如果 boto 設定檔中已設定 encryption_key，gsutil rewrite -k 會將金鑰套用至物件。如果未設定 encryption_key，則 gsutil rewrite -k 等於 gcloud storage objects update --clear-encryption-key。這會從物件中移除所有客戶提供的加密金鑰 (CSEK) 或客戶自行管理的加密金鑰 (CMEK)。然後使用 bucket 的預設 KMS 金鑰或 Google代管的加密方式，加密物件。

gsutil rewrite 包含相關邏輯，可略過物件的重寫作業，前提是要求的轉換不會變更物件狀態 (例如，物件已處於目標儲存空間類別)。gcloud storage objects update可能不會執行相同的檢查，進而導致不必要的作業。
作業 gsutil 指令 gcloud storage 指令
移除物件或值區 
gsutil rm
 
gcloud storage rm
附註

系統不支援 gsutil 別名 del、delete 和 remove。

已知問題：同時使用 -l 和 -r 旗標時，gsutil 和 gcloud storage 的行為會有所不同。將要以遞迴方式刪除的目錄清單傳送至管道的指令碼，應先經過全面測試，再從使用 gsutil 轉換為 gcloud storage。
作業 gsutil 指令 gcloud storage 指令
同步處理兩個 bucket 或目錄的內容 
gsutil rsync
 
gcloud storage rsync
附註

根據預設，如果來源和目的地的物件大小和上次修改時間相符，gsutil rsync 會將物件視為未變更。只有在物件缺少修改時間，或您使用 -c 旗標手動強制執行時，才會進行更徹底的檢查碼比較。gcloud storage rsync 也會先檢查檔案大小和上次修改時間；不過，如果物件大小相符，但修改時間不同或遺失，系統會自動執行總和檢查碼比較。

gcloud storage rsync 預設會平行執行作業，以提升效能。除非使用頂層 -m 旗標，否則 gsutil rsync 會依序執行。

gsutil rsync 預設會追蹤符號連結。 gcloud storage rsync 預設會忽略這些欄位，但使用 --no-ignore-symlinks 旗標時除外。
作業 gsutil 指令 gcloud storage 指令
設定上傳物件的中繼資料 
gsutil setmeta
 
gcloud storage objects update
附註

gsutil setmeta 使用單一可重複的 -h 標記，指定要設定或移除的中繼資料。gcloud storage objects update 會為每個中繼資料欄位使用不同的標記 (例如：--content-type、--clear-cache-control 或 --update-custom-metadata)。

在 gsutil setmeta 中，-h 標記用於設定完整標題名稱 (例如：-h "x-goog-meta-icecreamflavor:vanilla")。在 gcloud storage objects update 中，則使用 --update-custom-metadata 標記，並採用鍵值組合 (例如：--update-custom-metadata=icecreamflavor=vanilla)。如要移除自訂中繼資料欄位，gsutil setmeta 會使用 -h "x-goog-meta-icecreamflavor"，而 gcloud storage objects update 則會使用 --remove-custom-metadata=icecreamflavor。
作業 gsutil 指令 gcloud storage 指令
顯示物件狀態 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
附註

gcloud storage objects list --stat 的輸出格式與 gsutil stat 的輸出格式不同，且已知有間距不一致的問題。如果指令碼是為了剖析 gsutil stat 的輸出內容而編寫，可能需要調整才能處理新的輸出格式。