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 エイリアス 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 はデフォルトでシンボリック リンクをたどります。--no-ignore-symlinks フラグが使用されていない限り、gcloud storage rsync はデフォルトでこれらを無視します。

オペレーション	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 の出力を解析するために作成されたスクリプトでは、新しい出力形式を処理するために調整が必要になる場合があります。