從 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 存放區中的遷移參考資料。