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

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

オブジェクト

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

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

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

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

命名に関する考慮事項

オブジェクトに付ける名前は、次の要件を満たす必要があります。

  • オブジェクト名は Unicode 文字で任意に設定でき、UTF-8 エンコード時の長さが 1～1,024 バイトになるようにします。
  • オブジェクト名に、改行やラインフィード文字を含めることはできません。
  • オブジェクト名の先頭を .well-known/acme-challenge/ にすることはできません。
  • オブジェクト名を「.」や「..」にすることはできません。

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

  • 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. 複数のソースファイルを宛先 URL にコピーした場合、gcloud CLI は宛先 URL をフォルダとして扱います。たとえば、次のコマンドを実行するとします。ここで、your-dir は file1 や file2 などのファイルを含むフォルダです。

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

    このコマンドの結果として、Cloud Storage はバケット your-bucket にオブジェクト abc/your-dir/file1 と abc/your-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 が中断されたリクエストを再試行すると、最初の試行ではファイルのサブセットがコピーされ、その後の試行では既存の宛先フォルダが検出され、オブジェクトの名前が正しく付けられないという問題が発生する可能性があります。

たとえば、次のコマンドを実行するとします。ここで、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 で定義されるフォルダの命名規則を使用しません。宛先サブフォルダが存在するかどうかにかかわらず、一貫した命名を行います。

名前の構成の詳細については、cp を使用した名前の構成をご覧ください。

その他の情報

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

  • / はオブジェクト名の中の 1 文字にすぎない場合もあるため、CLI は gs://my-bucket/folder/ と gs://my-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 コンソールなど、ゼロバイトのオブジェクトをフォルダのプレースホルダとして作成するツールを使用している場合は、ゼロバイトのオブジェクトを削除してフォルダを削除する必要があります。

オブジェクトの不変性

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

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

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

次のステップ