Cloud Storage オブジェクトについて

このページでは、Cloud Storage のリソースであるオブジェクトについて説明します。Cloud Storage の一般的な概要については、Cloud Storage プロダクトの概要をご覧ください。

オブジェクト

オブジェクトとは、Cloud Storage 内に保存する個々のデータのことです。バケットで作成できるオブジェクトの数に上限はありません。

オブジェクトは、オブジェクト データとオブジェクト メタデータという 2 つのコンポーネントで構成されます。通常、オブジェクト データは Cloud Storage に保存するファイルで、Cloud Storage にとっては完全に不透明です。オブジェクト メタデータは、オブジェクトのさまざまな性質を記述した名前と値のペアの集合です。

すべてのオブジェクトに共通のオブジェクト メタデータの 2 つの重要な部分は、オブジェクトの名前と世代番号です。Cloud Storage バケットにオブジェクトを追加するときに、オブジェクト名を指定すると世代番号が割り当てられます。名前と世代により、バケット内のオブジェクトを一意に識別します。

アクセス制御リスト（ACL）を使用して、個々のオブジェクトへのアクセスを制御できます。Identity and Access Management（IAM）を使用して、バケットまたはマネージド フォルダ内のすべてのオブジェクトへのアクセスを制御することもできます。

命名に関する考慮事項

Cloud Storage でオブジェクトに名前を付けるときは、互換性を確保しエラーを防ぐために、特定の要件に準拠することが重要です。これらの要件は、フラットな名前空間バケットと階層型名前空間が有効なバケットの両方に適用されます。

一般的な要件

  • オブジェクト名には、有効な Unicode 文字を任意の順序で含めることができます。
  • オブジェクト名に、改行やラインフィード文字を含めることはできません。
  • オブジェクト名の先頭を .well-known/acme-challenge/ にすることはできません。
  • オブジェクト名を「.」や「..」にすることはできません。

名前空間固有のオブジェクト サイズの上限

オブジェクト名の最大サイズは、バケットの名前空間によって異なります。

  • フラットな名前空間バケット内のオブジェクト名のサイズ: UTF-8 でエンコードする場合は 1～1,024 バイト。

  • 階層型名前空間が有効になっているバケット内のオブジェクト名のサイズ: オブジェクト名は次の 2 つの部分に分けられます。

    • フォルダ名: オブジェクトが存在するフォルダの名前。UTF-8 でエンコードされたフォルダ名の最大サイズは 512 バイトです。
    • ベース名: フォルダ内にあるオブジェクトの名前。UTF-8 でエンコードする場合、ベース名の最大サイズは 512 バイトです。

    たとえば、パス my-folder/my-object.txt は、my-folder/ という名前のフォルダ内に保存されている、ベース名が my-object.txt のオブジェクトを表します。

推奨事項

オブジェクト名では次のことを避けるよう強くおすすめします。

  • XML 1.0 で不正な制御文字（#x7F～#x84 および #x86～#x9F）: オブジェクトを一覧表示するときにこれらの文字が原因で XML リストに問題が発生します。
  • # 文字: Google Cloud CLI コマンドは、#<数字文字列> で終わるオブジェクト名をバージョン識別子として解釈します。オブジェクト名に # が含まれていると、gcloud CLI を使用してバージョン指定されたオブジェクトのオペレーションを実行することが困難、または不可能になる可能性があります。
  • [、]、*、? 文字: Google Cloud CLI コマンドはこれらの文字をワイルドカードとして解釈するため、これらの文字がオブジェクト名に含まれていると、ワイルドカードのオペレーションを実行することが困難、または不可能になる可能性があります。また、* と ? は Windows のファイル名で有効な文字ではありません。
  • :、"、<、>、| 文字: Windows ではファイル名に有効な文字ではないため、ダウンロード方法に Windows ファイル名の変更が含まれていない場合、Windows ファイル名にこのような文字を使用するオブジェクトのダウンロードは失敗します。/ 文字は、Windows ではファイル名に有効な文字ではありませんが、通常はディレクトリ構造を模倣するためにオブジェクト名で使用できます。Google Cloud CLI などのツールは、Windows 環境にダウンロードするときに、この文字を自動的に \ に変換します。
  • 機密情報または個人を特定できる情報（PII）: オブジェクト名は、オブジェクト データよりも広い範囲で表示されます。たとえば、オブジェクト名は、オブジェクトの URL やバケット内のオブジェクトを一覧表示するときに表示されます。

既存のオブジェクトの名前を直接変更することはできませんが、元のオブジェクトをコピーして削除することで、間接的にオブジェクトの名前を変更できます。

オブジェクトの名前空間

オブジェクトは次の名前空間に保存できます。

フラットな名前空間

フラットな名前空間を持つバケットでは、階層のないフラットな構造にオブジェクトが保存されます。つまり、ディレクトリやフォルダはありません。

便宜上、オブジェクトがフォルダ階層に保存されているかのように扱う方法がいくつかあります。

たとえば、バケット your-bucket に folder1/file.txt という名前のオブジェクトを作成した場合、オブジェクトのパスは your-bucket/folder1/file.txt になりますが、Cloud Storage には folder1 という名前のフォルダは保存されません。Cloud Storage から見ると、文字列 folder1/ はオブジェクトの名前の一部になります。

ただし、オブジェクトの名前に / が含まれているため、一部のツールではフォルダのように見えます。たとえば Google Cloud コンソールでオブジェクト folder1/file1.txt に移動すると、folder1 という名前のフォルダに file1.txt という名前のオブジェクトが存在しているように見えます。同様に、folder1 という名前のマネージド フォルダを作成すると、file1.txt には、このマネージド フォルダによって設定されたアクセス ポリシーが適用されます。

オブジェクトはフラットな名前空間に配置されているため、ネスト構造の深いディレクトリに似た構造では、ネイティブ ファイル システムでネストの深いサブディレクトリを一覧表示する場合のようなパフォーマンスは得られません。

大規模なアップロードでシーケンシャルな名前を使用しないでパフォーマンスを最適化する方法については、リクエスト レートのベスト プラクティスをご覧ください。シーケンシャルな名前でアップロードされたオブジェクトは、同じバックエンド サーバーに到達してパフォーマンスが低下する可能性があります。

シミュレートされたフォルダ

Cloud Storage バケット内のオブジェクトを整理するために、一部のツールはフォルダをシミュレートします。JSON API と XML API には、フォルダをシミュレートする独自の命名スキームを設計できる機能があります。次のタブをクリックすると、シミュレートされたフォルダがさまざまなツールでどのように処理されるかを確認できます。

コンソール

Google Cloud コンソールでは、ローカルのファイル ブラウザと同じようにフォルダが表示されます。

Google Cloud コンソールでは、バケット内に空のフォルダを作成するか、既存のフォルダをアップロードできます。

既存のフォルダをアップロードすると、そのフォルダ内のすべてのオブジェクトのパスにフォルダ名が含まれます。サブフォルダとそこにあるオブジェクトもアップロードに含まれます。

フォルダを作成するには:

  1. Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。

    [バケット] に移動

  2. バケットに移動します。

  3. [フォルダを作成] をクリックして空のフォルダを新規に作成するか、[フォルダをアップロード] をクリックして既存のフォルダをアップロードします。

コマンドライン

Cloud Storage CLI は、さまざまなルールを使用して一般的なコマンドライン ディレクトリをシミュレートします。

疑似的な階層型ファイルツリーを実現するため、gcloud CLI は次のルールを適用して、コマンド内の宛先 URL をオブジェクト名として扱うか、フォルダとして扱うかを決定します。

  1. 宛先 URL が / 文字で終わる場合、gcloud CLI コマンドは宛先 URL をフォルダとして扱います。たとえば、次のコマンドを実行するとします。ここで、your-file はファイルの名前です。

    gcloud storage cp your-file gs://your-bucket/abc/

    このコマンドの結果として、Cloud Storage はバケット your-bucket に abc/your-file という名前のオブジェクトを作成します。

  2. --recursive フラグまたは ** などのワイルドカードを使用して複数のソースファイルを宛先 URL にコピーする場合、gcloud CLI はリンク先 URL をフォルダとして扱います。たとえば、次のコマンドを実行するとします。ここで、top-dir は file1 や file2 などのファイルを含むフォルダです。

    gcloud storage cp top-dir gs://your-bucket/abc --recursive

    このコマンドの結果として、Cloud Storage はバケット your-bucket にオブジェクト abc/top-dir/file1 と abc/top-dir/file2 を作成します。

  3. これらのルールのいずれも該当しない場合、gcloud CLI はバケット内のオブジェクトをチェックし、宛先 URL がオブジェクト名とフォルダのどちらであるかを判断します。たとえば、次のコマンドを実行するとします。ここで、your-file はファイルの名前です。

    gcloud storage cp your-file gs://your-bucket/abc

    gcloud CLI は、区切り文字に /、接頭辞に abc を指定して、your-bucket に対するオブジェクト一覧表示リクエストを行い、パスが abc/ で始まるオブジェクトが your-bucket にあるかどうかを判断します。その場合、gcloud CLI では abc/ がフォルダ名として扱われ、コマンドによりバケット your-bucket にオブジェクト abc/your-file が作成されます。それ以外の場合、gcloud CLI ではオブジェクト abc が your-bucket に作成されます。

このルールベースのアプローチは、フォルダの存在を示すために 0 バイトのオブジェクトを作成する多くのツールの仕組みとは異なります。gcloud CLI では、0 バイト オブジェクトの名前の末尾に _$folder$ を追加する規則など、これらのツールで使用されるいくつかの規則が理解されていますが、gcloud CLI では、UNIX コマンドの一貫した命名動作を実装するために、このようなマーカー オブジェクトは必要ありません。

これらのルールに加えて、gcloud CLI がソースファイルを処理する方法は、--recursive フラグを使用するかどうかによって異なります。このフラグを使用すると、gcloud CLI は、再帰処理の開始点から、ソース ディレクトリ構造をミラーリングするオブジェクト名を作成します。たとえば、次のコマンドを実行するとします。ここで、home/top-dir は file1 や sub-dir/file2 などのファイルを含むフォルダです。

gcloud storage cp home/top-dir gs://your-bucket --recursive

このコマンドの結果として、Cloud Storage はバケット your-bucket にオブジェクト top-dir/file1 と top-dir/sub-dir/file2 を作成します。

一方、--recursive フラグなしでコピーする場合、** などのワイルドカードが存在するために複数のファイルがコピーされた場合でも、ソースファイルの最後のパス コンポーネントで名前が付けられたオブジェクトが作成されます。たとえば、home/top-dir が file1 や sub-dir/file2 などのファイルを含むフォルダであるとします。この場合、コマンドは次のようになります。

gcloud storage cp home/top-dir/** gs://your-bucket

バケット your-bucket に file1 という名前のオブジェクトと file2 という名前のオブジェクトを作成します。

再試行と命名

gcloud CLI が中断されたリクエストを再試行すると、最初の試行ではファイルのサブセットがコピーされ、その後の試行では既存の宛先フォルダが検出され、オブジェクトの名前が正しく付けられないという問題が発生する可能性があります。

たとえば、次のコマンドを実行するとします。ここで、your-dir/ には dir1、dir2 というサブフォルダが存在し、両サブフォルダにはファイル abc が含まれています。

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

パス gs://your-bucket/new がまだ存在しない場合、gcloud CLI では最初の成功時に次のオブジェクトが作成されます。

new/dir1/abc
new/dir2/abc

ただし、同じコマンドが次回成功すると、gcloud CLI では次のオブジェクトが作成されます。

new/your-dir/dir1/abc
new/your-dir/dir2/abc

すべての試行で gcloud CLI が一貫して動作するように、次のことを試してください。

  1. 宛先 URL の末尾にスラッシュを追加すると、gcloud CLI では常にそのパスがフォルダとして扱われます。

  2. gcloud storage rsync を使用します。rsync は Unix cp で定義されるフォルダの命名規則を使用しません。宛先サブフォルダが存在するかどうかにかかわらず、一貫した命名を行います。

その他の情報

  • gcloud CLI を使用して空のフォルダをシミュレートするために、ゼロバイトのオブジェクトを作成することはできません。

  • ローカル ファイル システムにダウンロードする場合、gcloud CLI は名前が / 文字で終わるオブジェクトをスキップします。これは、Linux と macOS では / で終わるファイルの作成が許可されていないためです。

  • / はオブジェクト名の中の 1 文字にすぎない場合もあるため、CLI は gs://your-bucket/folder/ と gs://your-bucket//folder は異なるものと解釈します。スクリプト内でサブパスを組み合わせてファイルパスを作成する場合には注意してください。

REST API

JSON API

JSON API にフォルダは存在しません。一覧表示するオブジェクトを絞り込み、prefix と delimiter クエリ パラメータを使用してフォルダをシミュレートできます。

たとえば、接頭辞 folder/subfolder/ を使用してバケット my-bucket 内のすべてのオブジェクトを一覧表示するには、次の URL を使用してオブジェクトの一覧表示リクエストを行います。

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

XML API

XML API にフォルダは存在しませんが、prefix と delimiter クエリ パラメータを使用すると、オブジェクト リストを絞り込むことができます。

たとえば、接頭辞 folder/subfolder/ を使用してバケット my-bucket 内のすべてのオブジェクトを一覧表示するには、次の URL を使用してオブジェクトの一覧表示リクエストを行います。

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

シミュレートされたフォルダの削除

シミュレートされたフォルダは実際には存在しないため、通常、シミュレートされたフォルダはオブジェクトの名前を変更することで削除できます。この操作を行うと、シミュレートされたフォルダはオブジェクト名の一部ではなくなります。たとえば、folder1/file という名前のオブジェクトがある場合、オブジェクトの名前を file に変更することで、シミュレートされたフォルダ folder1/ を削除できます。

ただし、Google Cloud コンソールなど、ゼロバイトのオブジェクトをフォルダのプレースホルダとして作成するツールを使用している場合は、ゼロバイトのオブジェクトを削除してフォルダを削除する必要があります。

階層名前空間

階層型名前空間を使用すると、Cloud Storage バケット内のオブジェクトを、フォルダの階層のようなファイル システムに整理できます。階層型名前空間を使用すると、パフォーマンスが向上し、データを効率的に管理できます。階層型名前空間とその使用方法について詳しくは、階層型名前空間をご覧ください。

オブジェクトの不変性

オブジェクトは不変です。具体的には、アップロードされたオブジェクトは、その保存期間が終わるまで変わることはありません。オブジェクトの保存期間とは、オブジェクトが正常に作成され（たとえば、アップロードなど）、正常に削除されるまでの時間です。つまり、後からオブジェクトに付加や切り捨てなどのオペレーションで部分的な変更を加えることはできません。ただし、Google Cloud Storage に保存されているオブジェクトを置換することは可能で、これはアトミックに行われます。新しいアップロードが完了するまではオブジェクトの古いバージョンがリーダーに配信され、アップロードが完了すると、オブジェクトの新しいバージョンがリーダーに配信されます。したがって、置換オペレーションを 1 回行うと、1 つの不変オブジェクトの保存期間が終了し、別の新たな不変オブジェクトの保存期間が開始することになります。

オブジェクトの世代番号は、オブジェクトのデータを置換するたびに変更されます。したがって、世代番号は不変オブジェクトを一意に識別します。

同じオブジェクトを頻繁に置き換えることに対して、1 秒に 1 回の上限があります。同じオブジェクトを頻繁に置き換えると、429 Too Many Requests エラーが発生する可能性があります。特定のオブジェクトのデータを 1 秒あたり 1 回を超えてアップロードしないようにアプリケーションを設計し、指数バックオフの再試行戦略を使用して、時折発生する 429 Too Many Requests エラーを処理するようにしてください。

次のステップ