ワイルドカード名

説明

gsutil では、ファイル、バケット、オブジェクトの URI ワイルドカードを使用できます。たとえば、次のコマンドを実行します。

gsutil cp gs://bucket/data/abc* .

名前が gs://bucket/data/abc で始まり、その後に任意の数の文字が続くすべてのオブジェクトが同じサブディレクトリ内でコピーされます。

ワイルドカード文字

gsutil では、次のワイルドカードを使用します。

*
現在のディレクトリ レベル内の任意の数の文字に一致します。たとえば、gsutil cp gs://my-bucket/abc/d* . はオブジェクト abc/def.txt と一致しますが、オブジェクト abc/def/g.txt とは一致しません。gsutil ls の場合、末尾の * が現在のディレクトリ レベルのサブディレクトリと一致する場合、サブディレクトリの内容も一覧表示されます。
**

ディレクトリの境界を超えて任意の数の文字に一致します。ローカル ファイルパスの一部として使用する場合、** ワイルドカードは常にディレクトリ区切り記号が直前に配置される必要があります。たとえば、my-directory/**.txt は有効ですが、my-directory/abc** は無効です。

?

1 文字に一致します。たとえば、gs://bucket/??.txt は、任意の 2 文字の後に .txt が続くオブジェクトにのみ一致します。

[文字]

指定した任意の文字に一致します。たとえば、gs://bucket/[aeiou].txt は、1 つの母音文字の後に .txt が続くオブジェクトに一致します。

[文字範囲]

任意の文字範囲に一致します。たとえば、gs://bucket/[a-m].txt は a、b、c、...、m という文字を含み、.txt で終わるオブジェクトに一致します。

次のように、ワイルドカードを組み合わせて、より複雑なパターンに一致させることもできます。

gs://*/[a-m]??.j*g

結果で非現行バージョンのオブジェクトを返すフラグがコマンドに含まれていない場合、これらのワイルドカードはライブ オブジェクト バージョンにのみ一致します。

gsutil では、オブジェクト名とファイル名の両方に同じワイルドカードを使用できます。たとえば、次のように記述できます。

gsutil cp data/abc* gs://bucket

ローカル ファイル システムの data ディレクトリにある abc で始まるすべてのファイルに一致します。

ワイルドカードの使用時の予期せぬ動作

ワイルドカードを使用すると、予期せぬ動作が生じることがあります。

  1. バケット名にワイルドカードを使用する場合、-p フラグで指定されたプロジェクト内のバケットのみに一致します。gsutil rm などの一部のコマンドでは、-p フラグをサポートしていません。-p フラグをコマンドで使用しない場合や使用できない場合は、一致はデフォルト プロジェクトのバケットに限定されます。

  2. シェル(bash や zsh など)は、gsutil に引数を渡す前にワイルドカードを展開しようとします。ワイルドカードがクラウド オブジェクトを参照しようとした場合、「Not found」エラーが発生する可能性があります(たとえば、シェルがローカルマシンでワイルドカード gs://my-bucket/* を展開しようとすると、ローカル ファイルと一致せず、コマンドが失敗します)。

    一部のシェルでは、ワイルドカード文字セットに追加の文字が含まれています。たとえば、extendedglob オプションを有効にして zsh を使用すると、# が特殊文字として扱われ、バージョニングされたオブジェクトを参照するための使用と競合します(例については、非現行バージョンのオブジェクトを復元するをご覧ください)。

    この問題を回避するには、ワイルドカード式を単一引用符(Linux の場合)または二重引用符(Windows の場合)で囲みます。

  3. gsutil はワイルドカード文字をリテラル文字として使用するのではなく展開しようとするため、ワイルドカード文字が含まれるファイル名を指定することはできません。たとえば、次のコマンドを実行します。

    gsutil cp './file[1]' gs://my-bucket
    

    gsutil は [1] の部分をワイルドカードとして照合します。

    gsutil でワイルドカード文字が含まれるファイル名を処理するために「raw」モードをサポートするという未解決の問題があるものの、このサポートが実装されるまで、または実装されていない場合、実際には gsutil を使用してこのようなファイル名を処理する良い方法はありません。ワイルドカードを使用してこのようなファイル名を付けるには、上記のコマンドを次のように置き換えます。

    gsutil cp './file*1*' gs://my-bucket
    

    ただし、この方法は一般に困難です。

ローカル ファイル システムのドットファイルに対する動作の違い

標準の Unix 動作では、ワイルドカード *. 文字で始まらないファイルにのみ一致します(すべての Unix ディレクトリで ... ディレクトリの混同を防ぐため)。gsutil は、ファイル システム URI にワイルドカードを使用した場合と同じ処理を行いますが、クラウド URI を使用した場合とは異なります。たとえば、次のコマンドは gs://bucket1 から gs://bucket2 にすべてのオブジェクトをコピーします。

gsutil cp gs://bucket1/* gs://bucket2

ただし、次のコマンドは、. で始まらないファイルのみをディレクトリ dir から gs://bucket1 にコピーします。

gsutil cp dir/* gs://bucket1

効果的な使い方: 多くのオブジェクトにワイルドカードを使用する場合

次のように、オブジェクト名の先頭以外にワイルドカードを使用すると、処理が速くなり、ネットワーク トラフィックも少なくなります。

gs://bucket/abc*.txt

次のように、オブジェクト名の先頭にワイルドカードを使用すると、効率が悪くなります。

gs://bucket/*abc.txt

gs://bucket/abc*.txt の場合、サーバーはバケットのルートにあり、名前が abc で始まるオブジェクトの結果のサブセットを返し、gsutil がその結果の一覧をフィルタリングし、名前が .txt 終わるオブジェクトの名前のリストを表示します。これに対し、gs://bucket/*abc.txt の場合、サーバーはバケットのルートにあり、すべてのオブジェクトをリクエストし、名前が abc.txt で終わるオブジェクトをフィルタリングします。バケット内に数千のオブジェクトが存在している場合、この効率性は非常に大きな問題となります。サーバー側の接頭辞リクエストを効率的に処理するため、ワイルドカードの一致パターンに合わせてオブジェクトの名前を設定できる場合があります。具体的な例については、gsutil help prod をご覧ください。

効果的な使い方: パスの途中にワイルドカードを使用する場合

たとえば、バケットに次のオブジェクトがあるとします。

gs://bucket/obj1
gs://bucket/obj2
gs://bucket/obj3
gs://bucket/obj4
gs://bucket/dir1/obj5
gs://bucket/dir2/obj6

次のコマンドを実行します。

gsutil ls gs://bucket/*/obj5

gsutil は、/ で区切られたトップレベルのバケットの一覧を作成し、各サブディレクトリのバケットの一覧を作成します。合計で 3 つのバケットリストを作成します。

GET /bucket/?delimiter=/
GET /bucket/?prefix=dir1/obj5&delimiter=/
GET /bucket/?prefix=dir2/obj5&delimiter=/

ワイルドカードで必要なバケットの一覧表示が多くなると、時間とともにコストもかかります。次の数に応じてバケットリストの数が増加します。

  • ワイルドカード コンポーネントの数(例: 「gs://bucket/a??b/c*/*/d」には 3 つのワイルドカード コンポーネントがあります)。

  • 各コンポーネントと比較するサブディレクトリの数

  • 結果の数(結果の数が多すぎる場合は複数のページに分割され、各ページにマーカーが表示されます)。

パスの途中でワイルドカードを使用する場合には、次のように再帰的なワイルドカードを試してください。

gsutil ls gs://bucket/**/obj5

ディレクトリの境界を超えているため、gs://bucket/*/obj5 よりも多くのオブジェクトに一致しますが、区切りのないバケットリストを使用しているのでバケット リクエストの数は少なくなります。バケット全体のリストが作成され、ローカルでフィルタリングされるのでネットワーク トラフィックの量は多くなります。