gsutil から gcloud storage への移行

gcloud storage（一般提供）は、Cloud Storage を操作するうえで推奨されるコマンドライン ツールです。このページでは、2 つのツールの主な違いとコマンド マッピングについて説明し、gsutil から gcloud storage への移行を支援します。gcloud storage ツールの詳細については、gcloud storage リファレンス ドキュメントをご覧ください。

Google Cloud CLI をインストールして使用を開始する方法については、Google Cloud CLI をインストールするをご覧ください。

動作の違い

以降のセクションでは、gsutil と gcloud storage の動作の違いについて説明します。

並列呼び出し

gcloud storage は、CLI の複数のインスタンスを別々のターミナルから同時に実行することをサポートしていません。

並列処理

gcloud storage は並列処理をサポートしています。

ワイルドカードの処理

gcloud storage は複数のアスタリスクを簡素化します。アスタリスクを 3 つ以上連続して使用した場合（***）、1 つのアスタリスク（*）として扱われます。

階層名前空間バケットの処理

gcloud storage を使用して、階層名前空間が有効なバケットを作成して管理できます。

出力形式

gcloud storage コマンドと gsutil コマンドでは、出力の形式が異なります。ロギング形式などの小さな変更は影響しない可能性がありますが、エラー メッセージやデータリストに大きな違いがあれば自動化されたスクリプトが使えなくなる可能性があります。

gsutil コマンド出力の解析に依存するスクリプトがある場合は、移行する前にそのスクリプトを確認して gcloud storage 形式に合わせて更新する必要があります。

gcloud コマンドと同等のコマンド

gcloud storage には、既存の gsutil コマンドのすべてについて同等のコマンドがありますが、一部例外もあります。すべての 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 コマンド
バケットラベルを管理する 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
注

1 つの gsutil label ch コマンドでラベルの追加、更新、削除を組み合わせた場合、gcloud storage buckets update を使用した同等のオペレーションとは異なる動作をすることがあります。gsutil の特定の読み取り / 変更 / 書き込み動作に依存するスクリプトは、gcloud storage への移行後に慎重にテストする必要があります。
オペレーション gsutil コマンド gcloud storage コマンド
バケット、オブジェクト、フォルダを一覧表示する 
gsutil ls
 
gcloud storage ls
注

プロジェクト内のオブジェクトをワイルドカードで一覧表示する場合、gsutil ls はオブジェクトのフラットリストを返しますが、gcloud storage ls はバケット名ごとにグループ化されたオブジェクトを返します。

gcloud storage ls -L を使用して詳細なリストを出力する場合、次の動作が適用されます。

  • 各メタデータのラベル（「キー」とも呼ばれる）で、各単語の先頭文字が大文字になる。
  • オブジェクトのメタデータに値がない場合、gcloud storage はその行を出力から除外する。

gcloud storage は常に UTC で日時を出力します。

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）が削除されます。オブジェクトは、バケットのデフォルトの KMS 鍵または Google管理の暗号化で暗号化されます。

gsutil rewrite には、リクエストされた変換でオブジェクトの状態が変更されない場合（オブジェクトがすでにターゲット ストレージ クラスにある場合など）に、オブジェクトの書き換えをスキップするロジックが含まれています。gcloud storage objects update は同じチェックを実行しない可能性があるため、不要なオペレーションにつながる可能性があります。
オペレーション gsutil コマンド gcloud storage コマンド
オブジェクトまたはバケットを削除する 
gsutil rm
 
gcloud storage rm
注

gsutil aliases の del、delete、remove はサポートされていません。

-l フラグと -r フラグを併用すると、gsutil と gcloud storage の動作が異なるという既知の問題があります。再帰的に削除するディレクトリのリストをパイプするスクリプトは、gsutil から gcloud storage への移行前に徹底的にテストする必要があります。
オペレーション gsutil コマンド gcloud storage コマンド
2 つのバケットまたはディレクトリのコンテンツを同期する 
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 フラグを使用して Key-Value ペアを取得します（例: --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 の出力を解析するために作成されたスクリプトでは、新しい出力形式を処理するために調整が必要になる場合があります。

次のステップ

コマンドとフラグのマッピングの詳細については、gsutil GitHub リポジトリの移行リファレンスをご覧ください。