オブジェクトのメタデータの使用

メタデータの概要

オブジェクトには、Content-Type、Cache-Control、Content-Disposition、Content-Encoding など、関連するメタデータが存在します。これにより、GET リクエストの処理方法を制御します(詳細は以降で説明します)。また、アプリケーションで使用するカスタム メタデータを設定することもできます(特定のオブジェクトが所有するプロパティにタグを付ける場合など)。

オブジェクトにメタデータを設定する方法は 2 つあります。

  • アップロード時に、gsutil -h オプションを使用して、オブジェクトに関連するメタデータ プロパティを 1 つ以上指定します。たとえば、次のコマンドを実行すると、gsutil は images という名前のローカル ディレクトリからアップロードされる各ファイルの Content-Type と Cache-Control を設定します。

    gsutil -h "Content-Type:text/html" \
           -h "Cache-Control:public, max-age=3600" cp -r images \
           gs://bucket/images
    

    -h は、gsutil コマンドのオプションです。cp サブコマンドのオプションではありません。

  • gsutil setmeta コマンドを使用して、アップロードされたオブジェクトにメタデータ フィールドを設定したり、削除したりします。詳細については、gsutil help setmeta をご覧ください。

以下では、特定のメタデータについて、より詳しく説明します。

Content-Type

最もよく設定されるメタデータは Content-Type(MIME タイプともいう)です。ブラウザは、このメタデータを使用してオブジェクトを正しく表示します。アップロード時に、gsutil はファイル名の拡張子に基づいて Content-Type を自動的に設定します。たとえば、名前が .txt で終わるファイルをアップロードすると、Content-Type は text/plain に設定されます。Linux または macOS で gsutil を実行し、名前に加えてコンテンツの説明に基づいてコンテンツ タイプを設定したい場合は、.boto 構成ファイルの use_magicfile 構成変数をご覧ください。一般に、use_magicfile の使用がより安定して構成可能ですが、Windows では使用できません。

コンテンツのアップロード時に -h と一緒に Content-Type を指定すると(前のセクションの gsutil コマンドの例を参照)、ファイル名の拡張子またはコンテンツに基づいて設定された Content-Type が上書きされます。特定のファイルについて Content-Type 検出アルゴリズムが思い通りに機能しない場合、この方法は便利です。

Cache-Control

Cache-Control もよく利用されるメタデータです。このメタデータを使用すると、ブラウザ キャッシュとインターネット キャッシュに、オブジェクトの保存を許可するかどうか、許可する場合はどのくらいの時間保存するかを制御できます。Cache-Control は、公開読み取り ACL が設定されているオブジェクトにのみ適用されます。非公開データはキャッシュに保存されません。

キャッシュへの保存を許可するために、photos という名前のローカル ディレクトリから一連のオブジェクトをアップロードする例を次に示します。

gsutil -h "Cache-Control:public,max-age=3600" cp -a public-read \
       -r photos gs://bucket/photos

このコマンドを実行すると、photos ディレクトリ(およびサブディレクトリ)内のすべてのファイルがアップロードされます。このファイルは公開されて読み取りとキャッシュへの保存が可能になり、キャッシュの有効期限が 1 時間に設定されます。

キャッシュへの保存を許可した場合、新しいバージョンに置き換えるためにオブジェクトをアプロードした後でも、ダウンロード時に古いバージョンが表示される場合があります。オブジェクトはインターネット上のさまざまな場所のキャッシュに保存されることがあるため、ブラウザのキャッシュを強制的に更新する場合とは異なり、キャッシュに保存されているオブジェクトをすべて強制的に期限切れにする方法はありません。一般公開された読み取り可能なオブジェクトのキャッシュされたバージョンの提供を防ぐには、オブジェクトに「Cache-Control:no-cache, max-age=0」を設定します。この設定を行うには、次のコマンドを実行します。

gsutil -h "Cache-Control:no-cache,max-age=0" \
       cp -a public-read file.png gs://your-bucket

Cache-Control のもう 1 つの用途は、「no-transform」値を使用することで、互換性のないクライアントのために gzip content-encoding を削除するなど、ダウンロード リクエストの詳細に基づくコンテンツ変換を適用しないように、Cloud Storage に指示することです。このパラメータは XML API でのみ考慮されます。Cloud Storage JSON API では、public、private、no-cache、max-age の Cache-Control パラメータのみが考慮されます。

Cache-Control メタデータの設定方法について詳しくは、gsutil help setmeta をご覧ください。

Content-Encoding

Content-Encoding を指定すると、オブジェクトの Content-Type を維持しながら、オブジェクトが圧縮(たとえば、gzip 圧縮)されていることを示すことができます。gsutil でアップロードする前に、指定した Content-Encoding でファイルが圧縮されていることを確認する必要があります。次の Linux の例について考えてみます。

echo "Highly compressible text" | gzip > foo.txt
gsutil -h "Content-Encoding:gzip" \
       -h "Content-Type:text/plain" \
       cp foo.txt gs://bucket/compressed

これは、gzip で圧縮されたオブジェクト foo.txt.gz を Content-Type: application/x-gzip でアップロードする場合とは異なります。大半のブラウザは、Content-Encoding: gzip のオブジェクトを Content-Type に従って動的に解凍し、処理することができます。

圧縮可能なコンテンツの場合、Content-Encoding: gzip を使用すると、ネットワークとストレージのコストを抑え、コンテンツ配信のパフォーマンスを向上させることができます。ただし、すでに圧縮されているコンテンツの場合(アーカイブや多くのメディア形式など)、Content-Encoding で別のレベルの圧縮を適用しても、オブジェクトのサイズとパフォーマンスの両方にとって通常は弊害となるため、このような操作は避けてください。

また、gsutil では、Content-Encoding: gzip でコンテンツを簡単に圧縮し、保存できます。詳細については、gsutil help cp で -z オプションと -Z オプションの説明をご覧ください。

Content-Disposition

オブジェクトに Content-Disposition を設定すると、転送するデータの表示情報を指定できます。attachments という名前のローカル ディレクトリからファイルをアップロードする例を次に示します。

gsutil -h 'Content-Disposition:attachment; filename=filename.ext' \
       cp -r attachments gs://bucket/attachments

Content-Disposition を設定すると、コンテンツの表示スタイルを制御できます。たとえば、添付ファイルを自動的に表示するかどうか、もしくは開く前に操作を要求するかどうかを決めることができます。Content-Disposition の詳細については、https://tools.ietf.org/html/rfc6266 をご覧ください。

カスタム メタデータ

-h を指定して「x-goog-meta」を使用すると、独自のカスタム メタデータ(アプリケーションによる使用など)を Cloud Storage オブジェクトに追加できます。例:

gsutil -h x-goog-meta-reviewer:jane cp mycode.java gs://bucket/reviews

1 つのオブジェクトに複数のカスタム メディア フィールドを追加できます。

設定可能なフィールドとフィールド値

ETag や Content-Length など、一部のメタデータ フィールドは設定できません。設定可能なフィールドは次のとおりです。

  • Cache-Control
  • Content-Disposition
  • Content-Encoding
  • Content-Language
  • コンテンツ タイプ
  • カスタム メタデータ

フィールド名は、大文字と小文字が区別されません。

x-goog-meta- フィールドの値(任意の Unicode 値を含むことが可能)を除き、すべてのフィールドとその値は ASCII 文字のみで構成される必要があります。カスタム メタデータを HTTP ヘッダーとして送信する XML API を使用してメタデータを設定する場合、Unicode 文字は UTF-8 でエンコードされ、その後 ASCII に URL エンコードされます。例:

gsutil setmeta -h "x-goog-meta-foo: ã" gs://bucket/object

上記の例では、「foo」と「%C3%A3」のカスタム メタデータ Key-Value ペアが格納されます。その後、オブジェクトのメタデータを一覧表示するために JSON API を使用して「ls -L」を実行すると、「%C3%A3」が出力されます。一方、XML API を使用して「ls -L」を実行すると、この値を自動的に URL デコードして、文字「ã」を出力します。

現在設定されているメタデータの確認

現在オブジェクトに設定されているメタデータを確認するには、次のコマンドを使用します。

gsutil ls -L gs://the_bucket/the_object