gsutilコマンド全部試したので解説する(part1)

gsutil コマンドって何？

gsutil コマンドとは、Google Cloud Storage (GCS) を操作するためのコマンドラインツールのことです。gsutil コマンドは Google Cloud SDK をインストールすることで、利用できるようになります。今回、2部に渡って全ての gsutil コマンドの利用方法を説明します (※1)。Part 1 では、エンジニアには馴染み深い、Linux コマンドのように利用できるコマンド(ls, cp など)を中心として解説します。

GCS公式ページ

※1 … 2017/10/25現在の全 gsutil コマンド (version 4.27) を解説します。ただし、本記事公開後に解説したコマンドが削除されたり、または新規コマンドが追加される可能性がありますので、ご注意ください。また、コマンドごとのオプションについては重要であると思われるものだけピックアップして解説します。

gsutil コマンド実行環境を構築する手順

gsutil コマンドの実行環境を構築するための手順を説明します。以下手順に従って実行環境のセットアップをおこなってください。今回実際にコマンドを試した環境は mac OS です。Linux 系の OS では同じように実行することが可能ですが、Windows から実行する場合には、コマンド自体は同じものを利用しますが、フォルダの区切り文字などは異なるので気をつけましょう。

GCPプロジェクトを作成する

GCS (gsutil コマンド) を利用するためには、最初に GCP プロジェクトの作成が必要となります。下記リンクの「GCPプロジェクトの作成(1)~(3)」を参考にプロジェクトの作成をおこなってください。

– GCP プロジェクトの作成

Google Cloud SDK のセットアップ

Google Cloud SDK のセットアップ手順については、下記リンクの記事を参考にインストール、初期設定をおこなってください。

– Cloud SDKをmac, Linux, Windowsにインストール・初期設定までの導入手順徹底解説！！

gsutil コマンドの種類を確認する

gsutil コマンドの種類を確認するためには、ターミナル上で「gsutil help」コマンドを実行するとサポートされているコマンドの一覧と概要が表示されます(※2)。
現在、gsutil コマンドには計32種類のコマンドが存在します。

acl	du	mb	setmeta
cat	hash	mv	signurl
compose	help	notification	stat
config	iam	perfdiag	test
cors	label	rb	update
cp	lifecycle	rewrite	version
defacl	logging	rm	versioning
defstorageclass	ls	rsync	web

※2 … help コマンドについては後ほど説明します。

gsutilの基本コマンドを解説する

今回は Linux などでも馴染みの深いコマンドと、gsutil の基本的なコマンドを合わせて下記の14個を解説します。理解を深めるために実際にコマンドを実行することをお勧めします。

help
version
update
test
ls
mb
rb
cp
rm
mv
rsync
cat
du
hash

help コマンド

help コマンドは gsutil サブコマンドの利用方法を確認するためのコマンドです。help コマンドを使って「cp」コマンドの利用方法を確認する場合は以下のコマンドを実行します。

例1-1 「cp」コマンドの利用方法を確認するコマンド

コード

$ gsutil help cp
NAME
  cp - Copy files and objects


SYNOPSIS・・・(1)

  gsutil cp [OPTION]... src_url dst_url
  gsutil cp [OPTION]... src_url... dst_url
  gsutil cp [OPTION]... -I dst_url



DESCRIPTION・・・(2)
  The gsutil cp command allows you to copy data between your local file
  system and the cloud, copy data within the cloud, and copy data between
  cloud storage providers. For example, to copy all text files from the
  local directory to a bucket you could do:

    gsutil cp *.txt gs://my-bucke
～省略～

このコマンドを実行すると、上記の結果が出力されます。(1)はコマンドのフォーマット、(2)がコマンドの説明となります。コマンドの使い方がわからない場合は help コマンドを実行するようにしましょう！

また、サブコマンドを指定せずに help コマンドを実行した場合は、全 gsutil コマンドの一覧が出力されます。

version コマンド

version コマンドは gsutil コマンドラインツールのバージョンを出力するためのコマンドです。以下はコマンドの実行例です。

例2-1 gsutil ツールのバージョンを確認するためのコマンド

コード

$ gsutil version
gsutil version: 4.27

コマンドを実行すると、上記のように gsutil ツールのバージョンが出力されます。上記例では gsutil コマンドのバージョンは「4.27」であることが確認できます。

update コマンド

update コマンドは gsutil コマンドラインツールに新しいバージョンがリリースされた場合に、gsutil ツールをアップデートするためのコマンドでしたが、現在は Google Cloud SDK の gcloud コマンドからのアップデートが推奨されています。gcloud コマンドでのアップデートは“gcloud components update” です。こちらを使用するようにしてください。

test コマンド

test コマンドは gsutil コマンドラインツール自体の単体・結合テストを実行するためのコマンドです。おそらく、Python などのライブラリ関連の依存性の検証を行ってくれるものと思われます。
動作がおかしくなってしまった場合にコマンドを実行してみると、原因がわかるかもしれません。

以下はコマンドの実行例です。

例3-1 gsutil ツールのテストを実行するためのコマンド

コード

$ gsutil test
Running 261 tests sequentially.
172/261 finished - E[0] F[0] s[0] - TestPerfDiagUnitTests.test_listing_d - netstat: sysctl: net.inet.ip.input_perf_data: No such file or directory
netstat: sysctl: net.inet.ip.input_perf_data: No such file or directory
223/261 finished - E[0] F[0] s[0] - UpdateUnitTest.test_repo_matches_man - .
～省略～

コマンドを実行するとテストが開始され、上記のようなメッセージが出力されます。
一度テストを実行すると、完了までに30分ほど時間がかかるため、注意しましょう。

ls コマンド … List

ls コマンドはバケットやオブジェクトの一覧を出力するためのコマンドです。たとえば、バケットの一覧を出力するためには、下記のコマンドを実行します。

例4-1 バケットの一覧を出力するコマンド

コード

$ gsutil ls
gs://bucket-ca1/
gs://bucket-ca2/
gs://bucket-ca3/

クラウドコンソールを見てみると、実際に一覧が取得できていることが確認できます。

例4-2 バケット内のオブジェクト一覧を出力するコマンド

コード

$ gsutil ls gs://bucket-ca1
gs://bucket-ca1/file1.png
gs://bucket-ca1/file2.png
gs://bucket-ca1/file3.png
gs://bucket-ca1/local_folder/

クラウドコンソールを見てみると、実際に一覧が取得できていることが確認できます。

例4-3 バケット内のオブジェクトの詳細を表示するコマンド

コード

$ gsutil ls -l gs://bucket-ca1
    197648  2017-10-11T00:10:48Z  gs://bucket-ca1/file1.png
    197648  2017-10-11T00:16:28Z  gs://bucket-ca1/file2.png
    197648  2017-10-11T00:18:20Z  gs://bucket-ca1/file3.png
                                 gs://bucket-ca1/local_folder/
TOTAL: 3 objects, 592944 bytes (579.05 KiB)

クラウドコンソールを見てみると、時間に日本と米国でのずれはあるものの、最終更新日時とファイルサイズが取得出来ていることが確認できます。

また、バケット内のオブジェクトの情報をより詳細に表示するためには「-L」オプションを使用します。

例 4-4 オブジェクトの情報をより詳細に表示するコマンド

コード

$ gsutil ls -L gs://bucket-ca1/file1.png
gs://bucket-ca1/file1.png:
    Creation time:          Wed, 11 Oct 2017 00:10:48 GMT
    Update time:            Wed, 11 Oct 2017 00:10:48 GMT
    Storage class:          MULTI_REGIONAL
    Content-Length:         197648
    Content-Type:           image/png
    Hash (crc32c):          w5bgZw==
    Hash (md5):             6AdSqa/sYEGGoyEcn2HCmw==
    ETag:                   COef6ouk59YCEAE=
    Generation:             1507680648335335
    Metageneration:         1
    ACL:                    [
  {
    "entity": "project-owners-XXXXXXXXXXX",
    "projectTeam": {
      "projectNumber": "XXXXXXXXXXX",
      "team": "owners"
    },
    "role": "OWNER"
  },
  {
    "entity": "project-editors-XXXXXXXXXXX",
    "projectTeam": {
      "projectNumber": "XXXXXXXXXXX",
      "team": "editors"
    },
    "role": "OWNER"
  },
  {
    "entity": "project-viewers-XXXXXXXXXXX",
    "projectTeam": {
      "projectNumber": "XXXXXXXXXXX",
      "team": "viewers"
    },
    "role": "READER"
  },
  {
    "email": "xxx@example.com",
    "entity": "user-xxx@example.com",
    "role": "OWNER"
  }
]
TOTAL: 1 objects, 197648 bytes (193.02 KiB)

ハッシュ値や Accuses Control List など、より詳細な情報が表示されました。

mb コマンド … Make Bucket

mb コマンドは Cloud Storage に新しくバケットを作成するためのコマンドです。
コマンド実行前はこのような状態です。

バケットを作成するためには下記のコマンドを実行します。

例 5-1 バケットを作成するコマンド

コード

$ gsutil mb gs://bucket-ca4
Creating gs://bucket-ca4/...

このコマンドを実行後にクラウドコンソールを見てみると、実際にバケットが作成されていることが確認できます。

デフォルトではストレージクラスは「Multi-Regilnal」、ロケーションは「US」のバケットが作成されます。

ストレージクラス、ロケーションを指定したい場合は下記のコマンドを実行します。

例 5-2 ストレージクラス・ロケーションを指定してバケットを作成するコマンド

コード

$ gsutil mb -c regional -l asia-northeast1 gs://bucket-ca5
Creating gs://bucket-ca5/...

-c オプションでストレージクラス、-l オプションでロケーションを指定することができます。
コマンド実行後にクラウドコンソールを見てみると、指定した条件のバケットが作成されていることが確認できます。

rb コマンド … Remove Bucket

rb コマンドはバケットの削除をするためのコマンドです。
バケットを削除するときの注意点として、削除対象のバケットは空でなければいけません。
バケットを削除するには下記のコマンドを実行します。

例 6-1 バケットを削除するコマンド

コード

$ gsutil rb gs://bucket-ca5
Removing gs://bucket-ca5/...

クラウドコンソールを見てみると、バケットが削除されていることが確認できます。

中身のあるバケットを削除しようとした場合には下記のようなエラーが出ます。

例 6-2 オブジェクトの存在するバケットを選択時のエラー

コード

$ gsutil rb gs://bucket-ca1
Removing gs://bucket-ca1/...
NotEmptyException: 409 BucketNotEmpty (bucket-ca1)

cp コマンド … Copy

cp コマンドはローカルファイルや GCS オブジェクトをコピーするためのコマンドです。
ローカル → GCS や GCS → ローカル、GCS 内でのコピーをすることができます。
次回解説する「gsutil config」コマンドで AWS の設定を追加することで、GCS → S3 や S3 → GCS のコピーを行うことも可能です。

今回は中身が空っぽの「bucket-ca4」を対象にします。

ローカルから GCS へコピー(アップロード)するためには下記のコマンドを実行します。

例 7-1 ローカルファイルを GCS へコピーするコマンド

コード

$ gsutil cp $HOME/local_folder/file1.png gs://bucket-ca4/
Copying file:///Users/xxx/local_folder/file1.png [Content-Type=image/png]...
\ [1 files][193.0 KiB/193.0 KiB]
Operation completed over 1 objects/193.0 KiB.

コマンド実行後にクラウドコンソールを見てみると、指定したバケットにファイルがアップロードされていることが確認できます。

GCS 内で別バケットからオブジェクトをコピーするためには下記のコマンドを実行します。今回は「bucket-ca1」というバケットに存在する「file2.png」というファイルを「bucket-ca4」にコピーします。

例 7-2 GCS 内の別バケットからオブジェクトをコピーするコマンド

コード

$ gsutil cp gs://bucket-ca1/file2.png gs://bucket-ca4/file2.png
Copying gs://bucket-ca1/file2.png [Content-Type=image/png]...
- [1 files][193.0 KiB/193.0 KiB]
Operation completed over 1 objects/193.0 KiB.

コマンド実行後にクラウドコンソールを見てみると、ファイルがコピーされていることが確認できます。

GCS からローカルにコピー(ダウンロード)するためには、下記のコマンドを実行します。

例 7-3 GCS オブジェクトをローカルにコピーするコマンド

コード

$ gsutil cp gs://bucket-ca4/file2.png $HOME/local_folder/
Copying gs://bucket-ca4/file2.png...
- [1 files][193.0 KiB/193.0 KiB]
Operation completed over 1 objects/193.0 KiB.

コマンドを実行後に $HOME/local_folder を見てみると、ファイルがコピーされていることが確認できます。

コード

$ ls $HOME/local_folder
file1.png file2.png

cp コマンドを使用する際に対象がフォルダの場合は、下記コマンドのように「-r」オプションを用いることで、フォルダをまるごとコピーすることができます。

例 7-4 ローカルのフォルダを GCS にコピーするコマンド

コード

$ gsutil cp -r $HOME/local_folder gs://bucket-ca4/
Copying file:///Users/xxx/local_folder/file1.png [Content-Type=image/png]...
Copying file:///Users/xxx/local_folder/file2.png [Content-Type=image/png]...
- [2 files][386.0 KiB/386.0 KiB]
Operation completed over 2 objects/386.0 KiB.

コマンド実行後にクラウドコンソールを確認すると、フォルダが内包するファイルごとコピーされていることが確認できます。

rm コマンド … Remove

rm コマンドはオブジェクトを削除するためのコマンドです。
コマンド実行前の状態をクラウドコンソールで確認します。

オブジェクトを指定して削除するには下記のコマンドを実行します。

例 8-1 オブジェクトを指定して削除するコマンド

コード

$ gsutil rm gs://bucket-ca4/file3.png
Removing gs://bucket-ca4/file3.png...
/ [1 objects]
Operation completed over 1 objects.

コマンド実行後にクラウドコンソールを見てみると、指定したバケットが削除されていることが確認できます。

フォルダ内の全てのオブジェクトを削除するためには下記のコマンドを実行します。

例 8-2 フォルダ内のオブジェクトを全て削除するコマンド

コード

$ gsutil rm gs://bucket-ca4/*
Omitting prefix "gs://bucket-ca4/local_folder/". (Did you mean to do rm -r?)
Removing gs://bucket-ca4/file1.png...
Removing gs://bucket-ca4/file2.png...
/ [2 objects]
Operation completed over 2 objects.

コマンド実行後にクラウドコンソールを見てみると、指定したフォルダのオブジェクトが全て削除されていることが確認できます。

削除対処はオブジェクトのみで、フォルダは対象外である点に注意が必要です。

指定したフォルダも含めて全て削除するには、「-r」オプションを使用します。
コマンド実行前のバケット内は下記の通りです。

下記コマンドが実行例です。

例 8-3 指定したフォルダ内を再帰的に削除するコマンド

コード

$ gsutil rm -r gs://bucket-ca4
Removing gs://bucket-ca4/file1.png#1510189733612920...
Removing gs://bucket-ca4/file2.png#1510189756387814...
Removing gs://bucket-ca4/local_folder/file1.png#1510118944693232...
Removing gs://bucket-ca4/local_folder/file2.png#1510118945268387...
/ [4 objects]
Operation completed over 4 objects.
Removing gs://bucket-ca4/...

コマンド実行後にクラウドコンソールを見てみると、指定したフォルダ(バケット)がまるごと削除されていることが確認できます。

mv コマンド … Move

mv コマンドはオブジェクトの移動やリネームをするためのコマンドです。
ローカル → GCS や GCS → ローカル、GCS 内での移動をすることができます。
次回解説する「gsutil config」コマンドで AWS の設定を追加することで、GCS → S3 や S3 → GCS の移動を行うことも可能です。
GCS からローカルに移動するには下記のコマンドを実行します。

例 9-1 GCS からローカルにファイルを移動するコマンド

コード

$ gsutil mv gs://bucket-ca4/file1.png $HOME/local_folder
Copying gs://bucket-ca4/file1.png...
Removing gs://bucket-ca4/file1.png...

Operation completed over 1 objects/193.0 KiB.

コマンド実行後には、指定したファイルが GCS からローカルに移動します。
クラウドコンソールを確認すると、バケットから「file1.png」が消えていることが確認できます。また、ローカルを確認すると「file1.png」が追加されていることが確認できます。

コード

$ ls $HOME/local_folder
file1.png file2.png

ローカルのファイルを GCS に移動するには下記のコマンドを利用します。

例 9-2 ローカルから GCS にファイルを移動するコマンド

コード

$ gsutil mv $HOME/local_folder/file1.png gs://bucket-ca4/
Copying file:///Users/xxx/local_folder/file1.png [Content-Type=image/png]...
Removing file:///Users/xxx/local_folder/file1.png...

Operation completed over 1 objects/193.0 KiB.

コマンド実行後には、指定したファイルがローカルから GCS に移動します。
クラウドコンソールで確認すると、指定したバケットに「file1.png」が追加されていることが確認できます。また、ローカルを確認すると「file1.png」が消えていることが確認できます。

コード

$ ls $HOME/local_folder
file2.png

オブジェクトをリネームするには下記のコマンドを実行します。

例 9-3 オブジェクトをリネームするコマンド

コード

$ gsutil mv gs://bucket-ca4/file1.png gs://bucket-ca4/fil1000.png
Copying gs://bucket-ca4/file1.png [Content-Type=image/png]...
Removing gs://bucket-ca4/file1.png...

Operation completed over 1 objects/193.0 KiB.

コマンド実行後にクラウドコンソールを見てみると、オブジェクトがリネームされていることが確認できます。

mv コマンドを利用する際の注意点として、mv コマンドは内部的には cp, rm の2処理を行っているため、ストレージクラスが Nearline, Coldline の場合には通常の操作料金に加えて、データ取得料金、削除料金が追加される場合があります。

rsync コマンド … Remote Synchronization

rsync コマンドは2つのバケットやディレクトリの内容を同期するためのコマンドです。
次回解説する「gsutil config」コマンドで AWS の設定を追加することで、GCS → S3 や S3 → GCS のバケット同期を行うことも可能です。
バケットを同期するには下記のコマンドを実行します。

例 10-1 バケットを同期するコマンド

コード

$ gsutil rsync gs://bucket-ca4 gs://bucket-ca5
Building synchronization state...
Starting synchronization
Copying gs://bucket-ca4/fil1000.png [Content-Type=image/png]...
Copying gs://bucket-ca4/file2.png [Content-Type=image/png]...
Copying gs://bucket-ca4/file3.png [Content-Type=image/png]...
| [3 files][579.1 KiB/579.1 KiB]
Operation completed over 3 objects/579.1 KiB.

コマンド実行後にクラウドコンソールから bucket-ca4 と bucket-ca5 の中を確認してみると、バケット内のオブジェクトが同期されていることが確認できます。

オブジェクトの同期は確認できましたが、フォルダは同期されていません。
フォルダを同期するためには -r オプションを使用します。
フォルダごと同期するためには下記のコマンドを実行します。

例 10-2 バケットを内包するフォルダごと同期するコマンド

コード

$ gsutil rsync -r gs://bucket-ca4 gs://bucket-ca6
Building synchronization state...
Starting synchronization
Copying gs://bucket-ca4/fil1000.png [Content-Type=image/png]...
Copying gs://bucket-ca4/file2.png [Content-Type=image/png]...
Copying gs://bucket-ca4/file3.png [Content-Type=image/png]...
Copying gs://bucket-ca4/local_folder/file1.png [Content-Type=image/png]...
/ [4 files][772.1 KiB/772.1 KiB]
==> NOTE: You are performing a sequence of gsutil operations that may
run significantly faster if you instead use gsutil -m -o ... Please
see the -m section under "gsutil help options" for further information
about when gsutil -m can be advantageous.

Copying gs://bucket-ca4/local_folder/file2.png [Content-Type=image/png]...
- [5 files][965.1 KiB/965.1 KiB]
Operation completed over 5 objects/965.1 KiB.

コマンド実行後にクラウドコンソールから bucket-ca4 と bucket-ca6 の中を確認すると、フォルダも含めて同期されていることが確認できます。

フォルダごと同期できていることが確認できました。

cat コマンド … Concatenate

cat コマンドはオブジェクトの内容を出力するためのコマンドです。
オブジェクトの内容を出力するためには下記のコマンドを実行します。

例 11-1 オブジェクトの内容を出力するコマンド

コード

$ gsutil cat gs://bucket-ca7/a.txt
aaa

また、複数のオブジェクトの内容を連結して出力するには下記のコマンドを実行します。

例 11-2 複数のオブジェクトの内容を連結して出力するコマンド

コード

$ gsutil cat gs://bucket-ca7/a.txt gs://bucket-ca7/b.txt gs://bucket-ca7/c.txt
aaa
bbb
ccc

du コマンド … Disk usage

du コマンドはオブジェクトのサイズを表示するためのコマンドです。
オブジェクトを指定してサイズを表示するためには下記のコマンドを実行します。

例 12-1 オブジェクトを指定してサイズを表示するコマンド

コード

$ gsutil du gs://bucket-ca1/file1.png
197648      gs://bucket-ca1/file1.png

バケット・フォルダが内包する全てのオブジェクトのサイズを表示するためには下記のコマンドを実行します。

例 12-2 バケットが内包する全オブジェクトのサイズを表示するコマンド

コード

$ gsutil du gs://bucket-ca1
197648      gs://bucket-ca1/file1.png
197648      gs://bucket-ca1/file2.png
197648      gs://bucket-ca1/file3.png
197648      gs://bucket-ca1/local_folder/file1.png
197648      gs://bucket-ca1/local_folder/file2.png
395296      gs://bucket-ca1/local_folder/

また、「-c」オプションを使用することで出力の最後に合計サイズを表示することができます。下記はコマンド例です。

例 12-3 バケットの合計サイズを表示するコマンド

コード

$ gsutil du -c gs://bucket-ca1
197648      gs://bucket-ca1/file1.png
197648      gs://bucket-ca1/file2.png
197648      gs://bucket-ca1/file3.png
197648      gs://bucket-ca1/local_folder/file1.png
197648      gs://bucket-ca1/local_folder/file2.png
395296      gs://bucket-ca1/local_folder/
988240      total

hash コマンド … Hash

hash コマンドはローカルファイルのハッシュ値を計算するためのコマンドです。gsutil ls -L コマンドで出力されたハッシュ値との比較をするために使用されます。
ハッシュ値を出力するためには下記のコマンドを実行します。

例 13-1 ハッシュ値を計算して出力するコマンド

コード

$ gsutil hash $HOME/local_folder/file1.png
Hashes [base64] for /Users/moto/local_folder/file1.png:
	Hash (crc32c):		w5bgZw==
	Hash (md5):		6AdSqa/sYEGGoyEcn2HCmw==

Operation completed over 1 objects/193.0 KiB.

ls コマンドの実行例の結果と比較してみると、ローカルファイルとバケット内のオブジェクトのハッシュ値が一致していることが確認できます。

コード

$ gsutil ls -L gs://bucket-ca1/file1.png
gs://bucket-ca1/file1.png:
    Creation time:          Wed, 11 Oct 2017 00:10:48 GMT
    Update time:            Wed, 11 Oct 2017 00:10:48 GMT
    Storage class:          MULTI_REGIONAL
    Content-Length:         197648
    Content-Type:           image/png
    Hash (crc32c):          w5bgZw==
    Hash (md5):             6AdSqa/sYEGGoyEcn2HCmw==
～省略～

ハッシュ値の計算結果を16進数で表示したい場合は「-h」オプションを使用します。
下記はコマンドの実行例です。

例 13-2 ハッシュ値の計算結果を16進数で表示するコマンド

コード

$ gsutil hash -h $HOME/local_folder/file1.png
Hashes [hex] for /Users/moto/local_folder/file1.png:
	Hash (crc32c):		C396E067
	Hash (md5):		e80752a9afec604186a3211c9f61c29b

Operation completed over 1 objects/193.0 KiB.

また、「-c」オプションを使用することで、crc32c のみの計算結果、「-m」オプションを使用することで、md5 のみの計算結果をそれぞれ出力することができます。

まとめ

今回は gsutil コマンドの中でも gsutil ツールに対してのコマンドや、Linux コマンドに近い操作のコマンドを説明しました。ツールにありがちな「バージョンを表示するコマンド」、「help コマンド」や、Linux コマンドと同じような処理を行うコマンドなど、エンジニアには馴染み深い内容だったのではないでしょうか！
part2 では GCS の機能に踏み込んだコマンドについて説明する予定です。お楽しみに！！

※ 弊社ではクラウドエース(Cloud Ace)というGCPの導入・運用支援サービスを提供しておりますので、ご興味のある方はこちらまでお問い合わせくださいGAEに限らず、あらゆるGCPサービスのサポートが可能です。