從 gsutil 遷移至 gcloud storage

建議使用 Google Cloud CLI 指令列工具與 Cloud Storage 互動。本頁面說明 gsutil 和 gcloud CLI 的 gcloud storage 指令之間的主要差異和指令對應關係，協助您從前者轉換至後者。如果您的指令碼使用 gsutil，可以參考本頁資訊，改用對應的 gcloud storage 指令更新指令碼。

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

如需 gcloud storage 指令的詳細說明，請參閱 gcloud storage 參考文件。

行為差異

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

平行叫用

gcloud storage 不支援在同一部機器上使用多個終端機平行叫用。

平行處理

gcloud storage 支援平行處理。

萬用字元處理

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

處理階層命名空間 bucket

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

支援本機到本機的檔案複製作業

gcloud storage 專門用於與 Cloud Storage 互動，不支援本機到本機的檔案複製作業。如要使用 gcloud storage 成功移動資料，至少須有一個引數 (來源或目的地) 為 Cloud Storage 資源 URI。例如：gs://my-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 則會傳回依 bucket 名稱分組的物件。

使用 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 指令
移除物件或 bucket 
gsutil rm
 
gcloud storage rm
附註

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

目前已知 gsutil 和 gcloud storage 在同時使用 -l 和 -r 旗標時，行為會有所不同。如果指令碼會將目錄清單導向遞迴刪除作業，請務必先徹底測試，再從使用 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 的輸出內容而編寫，可能需要調整，才能處理 gcloud storage objects list --stat 的輸出格式。

後續步驟

如要進一步瞭解指令和旗標對應，請參閱 gsutil GitHub 存放區中的遷移參考資料。